Version 1.0.0 #51

Manually merged
miko merged 0 commits from development into master 2026-11-02 20:18:48 +01:00
Owner

First release of kataba: open, visual documentation — step-by-step guides with annotated photos, organised in a category tree, self-hosted for one organisation.

This merges everything on development since the theme and sign-in merge (#19) into master.

Highlights

Content

  • Guides — create, read, publish and delete; drafts and published guides, edits to published guides go live (#22, ADR-0008)
  • Steps — edit route and step list (#23)
  • Step lines — coloured bullets and icon lines (caution, note, reminder), indented up to two levels (#24)
  • Step images — upload, 4:3 crop, image variants, served through a guarded media route (#25, #36, ADR-0006)
  • Annotations — rectangle and circle outlines per step line, highlighted in the reading view (#26, ADR-0011)
  • Cover images for guides (#29), descriptions and images for categories (#41)
  • Manual child order for categories and guides (#40)
  • Full-text search across guides, filtered by visibility (#33)

Access

  • Permission module — effective visibility (most restrictive wins) and permissions (#20, ADR-0002)
  • Ownership and wiki mode in the UI (#27, ADR-0003)

Interface

  • Guide editor with properties in a sidebar (#28)
  • Admin settings page — instance name, session lifetime and more (#31)
  • Freely chosen accent colour, adjusted for contrast in light and dark mode (#32, ADR-0012)
  • Translated UI (English, German) with Lingui/gettext (#34, ADR-0007) and a per-user interface language (#44)
  • Titlebar with a user menu and centred search (#48)

Operations

  • Docker image and an example Compose setup with MariaDB; migrations run on container start (#50, ADR-0014)
  • README rewritten as a full project introduction, with screenshots

Fixes

  • Rich text is kept when a form is sent before Editor.js has loaded (#45)
  • No more deadlocks between parallel step and image saves: transactions run under READ COMMITTED behind guide row locks (#46, ADR-0013)

Quality

  • End-to-end tests with Playwright against their own database (#35)
  • Lint, typecheck and unit tests (Vitest)

Upgrading an existing installation

  • Apply the database migrations: npx prisma migrate deploy (the Docker image does this on start).
  • No new environment variables.

Before merging

  • Set version in package.json to 1.0.0
  • Tag the merge commit on master as v1.0.0

🤖 Generated with Claude Code

First release of kataba: open, visual documentation — step-by-step guides with annotated photos, organised in a category tree, self-hosted for one organisation. This merges everything on `development` since the theme and sign-in merge (#19) into `master`. ## Highlights ### Content - **Guides** — create, read, publish and delete; drafts and published guides, edits to published guides go live (#22, ADR-0008) - **Steps** — edit route and step list (#23) - **Step lines** — coloured bullets and icon lines (caution, note, reminder), indented up to two levels (#24) - **Step images** — upload, 4:3 crop, image variants, served through a guarded media route (#25, #36, ADR-0006) - **Annotations** — rectangle and circle outlines per step line, highlighted in the reading view (#26, ADR-0011) - **Cover images** for guides (#29), **descriptions and images** for categories (#41) - **Manual child order** for categories and guides (#40) - **Full-text search** across guides, filtered by visibility (#33) ### Access - **Permission module** — effective visibility (most restrictive wins) and permissions (#20, ADR-0002) - **Ownership and wiki mode** in the UI (#27, ADR-0003) ### Interface - Guide editor with properties in a sidebar (#28) - **Admin settings page** — instance name, session lifetime and more (#31) - **Freely chosen accent colour**, adjusted for contrast in light and dark mode (#32, ADR-0012) - **Translated UI** (English, German) with Lingui/gettext (#34, ADR-0007) and a **per-user interface language** (#44) - Titlebar with a user menu and centred search (#48) ### Operations - **Docker image** and an example Compose setup with MariaDB; migrations run on container start (#50, ADR-0014) - README rewritten as a full project introduction, with screenshots ## Fixes - Rich text is kept when a form is sent before Editor.js has loaded (#45) - No more deadlocks between parallel step and image saves: transactions run under READ COMMITTED behind guide row locks (#46, ADR-0013) ## Quality - End-to-end tests with Playwright against their own database (#35) - Lint, typecheck and unit tests (Vitest) ## Upgrading an existing installation - Apply the database migrations: `npx prisma migrate deploy` (the Docker image does this on start). - No new environment variables. ## Before merging - [x] Set `version` in `package.json` to `1.0.0` - [ ] Tag the merge commit on `master` as `v1.0.0` 🤖 Generated with [Claude Code](https://claude.com/claude-code)
miko added 67 commits 2026-11-02 20:08:35 +01:00
Category model with sibling-unique slugs, visibility, child order and
position. A pure category tree module handles path lookup, child order,
ancestors, cycle-free moves and the guest visibility filter (ADR-0002).
Category pages at /c/<slug-path>, the top level on /. Admins create,
rename, move and delete (empty only) categories, switch child order and
reorder in manual mode; new entries go last. The top level stays
alphabetical until the settings page (#5) exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pure functions answering who may see or do what with a guide or category
(ADR-0002, ADR-0003). The category tree and admin shortcuts use them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Deleted guides are not editable; isAdmin and RoleActor are exported and
used by requireAdmin and the category tree; more edge-case tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Guide model and migration; create, edit (optimistic locking via version),
publish/unpublish, soft delete and admin restore, all checked through the
permission module. /guides/<id>/<slug> redirects to the canonical slug.
Descriptions are edited with Editor.js and rendered by our own sanitising
React renderer (ADR-0005); plain text goes into searchText.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Store and load descriptions only as sanitised Editor.js JSON, so the editor
never inserts submitted HTML (stored XSS). Drop headings and quotes left
empty by sanitising; treat a malformed version as a conflict; share form
helpers, guide access fields and guide URLs; glossary-conform names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #20
Reviewed-on: #22
Step model and migration (position, optional title, Editor.js content,
searchText, per-step version). The guide editor gets a step list (add,
delete, reorder by drag and drop or arrow buttons) and an editor for the
active step, saved explicitly with optimistic locking; leaving a step with
unsaved changes asks first. The reading view lists the steps in order,
numbered, falling back to "Step n" without a title.

Submitted rich text is parsed by a shared helper for guide descriptions
and step content; the Editor.js wrapper moves to src/richText.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Step actions run in one transaction each and tolerate a step deleted
concurrently; addStep reports errors like the other actions. The editor
loads its content once per step, so a save no longer rebuilds it and drops
what was typed meanwhile; "unsaved" clears only if nothing changed during
the save. Unsaved step changes also ask before following a link or
submitting the guide form. A failed reorder shows the server's order again,
and a thrown action no longer leaves the list disabled. Shared helpers for
storing and reporting rich text submissions and for the step sort order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #23
- StepLine model (position, indent 0–2, kind, colour name, sanitised text)
  with migration; lines are saved with their step and replaced atomically.
- stepLines module: submission normalising/sanitising (bold, italic, links
  only), limits, and editor list ops (add, remove, move, indent, outdent).
- StepLinesEditor in the step form; StepLines in the reading view, nested by
  indent, with palette bullets and caution/note/reminder icons.
- Inline renderer extracted to InlineNodes; moveStep generalised to moveItem.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replaces the native select, whose options cannot show coloured bullets in
every browser, with an accessible listbox (arrow keys, Home/End, Enter,
Escape) that shows each option's bullet or icon.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #24
Up to three 4:3 images per step (ADR-0006). The browser crops to 4:3 and
uploads the original with the crop rectangle; sharp applies the EXIF
orientation, strips metadata and renders thumb/medium/large WebP variants.
Files live in UPLOAD_DIR behind a small storage interface. /media checks the
guide's effective visibility; re-cropping gives the image a new id so the
immutable cache stays truthful. The reading view shows the iFixit layout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Use glossary terms instead of "media" in identifiers.
- Lock the step row so concurrent uploads cannot exceed three images and
  re-crops keep their place during a reorder.
- Remove written files whenever rendering or saving fails.
- Answer NOT_EDITABLE consistently; share upload rules and messages
  between browser and server.
- ADR-0006: record per-crop image ids, the original route and the
  shared-cache trade-off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #25
Annotations are coloured rectangles and circles stored in percent of the
cropped image (ADR-0004); circles are round in the 4:3 frame, so their
height is 4/3 of their width. A dialog per step image draws them by
dragging, selects, moves, resizes and deletes them and picks a palette
colour (no black); they are saved as a whole set per image. The reading
view and the editor's thumbnails draw them as an SVG over the image, with a
fixed stroke width that scales with it. Re-cropping discards them through
the cascade on the replaced image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Focus follows the selection, so Delete and the arrow keys act on the
  annotation just clicked or drawn.
- Shift and arrow keys resize by one axis (resizeAnnotationBy), so circles
  can shrink too; resizing stops at the image's edges.
- Read the drawn annotation from a ref at pointer-up, so a quick drag is
  not lost; Escape cannot close the dialog during a save.
- Share the annotation colours (palette.ts) and the limit message; avoid
  "shape" for an annotation itself; clearer helper type names.
- ADR-0004: record percent storage and the 4/3 circle height.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every annotation now references one coloured bullet line of its step and
takes its colour (ADR-0011, superseding ADR-0004). Step lines keep their ids
across saves: the editor gives a new line a UUID, saving updates lines by
id, and lines that are removed, blackened or turned into icon lines lose
their annotations; the editor asks first. The migration moves existing
annotations to the first line of their colour.

The annotation dialog picks a line instead of a colour and shows the
selection as a thin frame with eight small handles of fixed pixel size;
every handle resizes, and circles stay round.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Clicking a step line that has annotations highlights them on the images
  (thicker, the others faded), switching to an image that has some; the
  bullet is a toggle button for keyboard and screen reader users.
- Editor.js never appeared: React's development double mount let the first,
  asynchronously created editor tear down the second one's UI. Each mount
  now gets its own element.
- Editor.js uses the field's full width, keeps its toolbar inside the
  border and follows the theme in light and dark mode; the list tool no
  longer offers checklists, which the renderer does not know (ADR-0005).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Ask before removing or blanking a line added in this session that has
  annotations (its key is its id), and before saving a step whose
  annotated lines were emptied, which drops them with their annotations.
- Derive "annotatable" from the palette in the step save, map stored
  annotations to line ids once, share the annotated-line set and the
  handle sides, and name test lines as lines, not colours.
- The selection frame is white on dark instead of the accent, which stays
  off step lines (ADR-0010); no short-circuits as control flow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The guide editor gets a Settings section for visibility, category and
wiki mode, with a hint when an ancestor category makes the guide
internal. Admins can transfer ownership to an author or admin. The
reading view shows the owner and the last editor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Call visibility, category and wiki mode the guide's "properties", as
  GLOSSARY.md reserves "Setting" for instance-wide values
- Validate the visibility with a type guard instead of a cast
- Derive canCreateGuide from canOwnGuides; share the owner type
- Hint wording also fits a guide that is internal itself
- Skip the update when ownership goes to the current owner

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #26
Reviewed-on: #27
Title, language, description and the steps stay in the main column; the
guide properties (visibility, category, wiki mode, ownership) move to a
sidebar on the right from 1280 px, and stack below on narrower screens.
The page widens to max-w-7xl so the step images keep their room.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #28
An optional 4:3 image represents a guide in category grids (GLOSSARY:
Cover Image); without one the guide keeps its coloured tile, with no
fallback to step images.

- New CoverImage model, one per guide, stored like a step image
  (ADR-0006): the original is kept for re-cropping, and each crop gets
  its own id, so immutable caching stays truthful.
- Set/replace, re-crop and remove actions reuse the step-image pipeline
  (readUpload, renderVariants, file helpers). Edits are checked with
  canEditGuide (owner, any author in wiki mode, admins) and serialised
  by a lock on the guide row.
- /media resolves step and cover images alike; the guide-based access
  rules are now named imageAccess/imageHref.
- The cover editor sits in the guide editor's sidebar and reuses
  CropDialog.
- Tile renders a plain <img> with a thumb/medium srcset, because
  next/image would cache guarded media past the visibility check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #29
Instance-wide settings stored as key/value rows in a new Setting model,
read typed with defaults (invalid stored values fall back to the default):
session lifetime, instance name, default UI locale and the top level's
child order.

- /admin/settings (admins only) edits them and shows the group → role
  mapping from the environment read-only; with manual top-level child
  order it also arranges the top-level categories
- Auth.js uses lazy configuration and reads the session lifetime from the
  settings
- The instance name is the Titlebar wordmark and the page title
- Admins get a Settings link in the Titlebar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #31
Admins choose the instance's accent colour from the curated list
(ADR-0010) on /admin/settings.

- New setting accentColor, a semantic accent name, defaulting to blue;
  unknown or removed names fall back to blue
- The picker shows each accent as a button and a link on the light and
  on the dark surface, via preview-only tokens (surface-light/-dark,
  accent-light/-dark) and a nested data-accent
- The root layout sets data-accent on <html> from the cached settings,
  so the shells stay prerendered and saving revalidates them; next build
  now needs the database
- Accent display names live in src/theme/accent.ts; the unused
  resolveAccent is removed (the settings parser does the fallback)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admins now choose any accent colour instead of one from the curated list
(ADR-0012, partly superseding ADR-0010).

- accentColor stores the chosen #rrggbb; suggestion names stored before
  still read as that suggestion's colour, anything else falls back to blue
- accentPair() derives the light- and dark-mode value in OKLCH: darkened
  or lightened until 4.5:1 on every surface of the mode, chroma lowered
  only to stay in gamut; the curated accents stay as suggestions with
  their hand-checked pairs
- The picker offers the suggestions with swatches, a colour field and a
  hex field, and previews the values actually used
- The root layout sets --accent-light/-dark as inline style on <html>,
  still from the settings cache
- Colour maths lives in src/theme/colour.ts; a test checks the contrast
  surfaces against globals.css

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #32
Guide.searchText now holds the plain text of the guide's title and
description and of all its steps (titles, step lines, content), rebuilt
from the stored data in every transaction that saves the guide or a
step, deletes or reorders steps; the guide row is locked first so
concurrent saves cannot write stale text. A FULLTEXT index covers it;
the migration backfills existing guides from their steps.

A search box in the Titlebar leads to /search, which runs a boolean-mode
query (every word a required prefix; words the index leaves out, i.e.
shorter than three characters or stopwords, are optional; typed
operators are ignored) and shows only the guides the viewer may see
via canViewGuide, so drafts, internal and deleted guides stay hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No results and an empty query now show a large, centred notice with an
icon; an "All categories" link leads back to the top level.

getCurrentUser awaits connection() before auth(), so prerendering stops
there instead of hitting auth()'s random values (flagged by Next on
/search).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #33
Lingui 6 with .po catalogs (English msgids, en and de), extract/compile
scripts, @lingui/swc-plugin pinned to 6.7.1 to match Next 16.4.3's SWC
crates. The locale comes from a cookie, else Accept-Language, else en.
Account and the home link are translated Server Components; the theme
switch and a new language switch are translated Client Components under
<Suspense>. Setup notes in ADR-0007.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Locale and i18n instance are cached per request, the provider takes only
the locale (one createI18n helper), lingui.config reuses LOCALES, and the
ADR notes that the per-user language setting is still to come.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every user-visible string goes through Lingui: pages, forms, editors,
Editor.js's own interface, metadata, and the error messages of actions
and validation (descriptors in plain modules, translated in the action).
Locale-dependent headings moved under <Suspense>; dates use the viewer's
locale. German catalog complete (279 messages, `lingui compile --strict`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #34
Playwright runs a production build on port 3100 against its own
kataba_e2e database (refused unless the name ends in _e2e) and upload
directory. Global setup migrates and empties the database, seeds one
user per role plus a second author, and creates the test category
through the admin form so the cached category tree is invalidated.
Tests sign in without Authentik by minting the Auth.js session cookie
with the test server's secret.

Specs cover: an author creating a guide with an annotated step and
publishing it, a guest reading it, a guest locked out of an internal
guide and its images while a viewer reads them, and another author
editing only once wiki mode is on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #35
Move the code step and cover images share (storage, files, processing,
crop, upload, media access, href, CropDialog) from src/stepImages/ to
src/images/; src/stepImages/ keeps only MAX_STEP_IMAGES and its actions
and components.

- recropImage runs the one re-crop flow for both kinds; each action only
  supplies its locked row swap.
- storedCrop maps the crop columns both ways (cropColumns, croppedImage),
  replacing cropFields, the edit page's own mapping and the inline field
  lists in the re-crop actions.
- submittedCrop moves next to cropForm, removingOnFailure into files.
- The editors' call/run helpers are now callServer/changeImages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #36
Guides get a position among the guides of their category, arranged
separately from subcategories but governed by the same child-order switch.

- Guide.position; the migration numbers existing guides per category
  alphabetically by title
- Category pages list guides in the category's child order (title breaks
  ties in manual order)
- Switching a category to manual numbers its guides alphabetically
- /admin/categories/[id] lists all non-deleted guides (drafts marked) with
  up/down buttons in manual order (moveGuide)
- New, recategorised and restored guides go last; other saves keep the
  position
- sortChildren and positionOnArrival in childOrder.ts, shared with the
  category tree and saveCategory; ArrangeChildren made generic
- Playwright: admin switches to manual, moves a guide up, guest sees it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #40
Both fields are in v1. Admins write a category's description with
Editor.js in the category form; the category page renders it with the
own renderer (ADR-0005). The bare Category.image column becomes a
CategoryImage table modelled on CoverImage: set, re-cropped and removed
on the category's edit page, shown on its tile, and served through
/media by the category's effective visibility, its original to admins
only (ADR-0006).

The cover image editor and its upload step move into the shared image
module (SingleImageEditor, storeReplacingImage) so both owners use them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #41
A signed-in user's language switch now also stores User.locale, and
resolveLocale prefers it over the cookie; a null locale follows the
cookie, Accept-Language and the default locale setting. ADR-0007 updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #44
The guide and category forms only add their description, and the step
form its content, once the editor exists. A form sent earlier had no such
field, which the server read as empty and saved as SQL NULL, wiping the
stored document. A missing rich text field now means "unchanged":
richTextFromForm reports it, and storedJson turns it into undefined, which
Prisma leaves alone. A field that is present but empty still clears it.

e2e/richText.spec.ts saves a guide and a step with Editor.js blocked and
checks that the description and content survive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #45
Saving two empty steps at once deadlocked (MySQL 1213, which Prisma reports
as TransactionWriteConflict): deleting each step's lines by stepId under
REPEATABLE READ locks the same index gap, and each first insert then waits
for the other's gap lock. Transactions already serialise by locking their
parent row first, so the gap locks guarded nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Saving a step locked the guide and then wrote the step, while image and
annotation changes locked the step and then wrote the guide as its last
editor, so the two could deadlock on each other. Every change inside a guide
now takes the guide's lock first; addStep takes it too, so concurrent adds
cannot get the same position. ADR-0013 records the rule, and the db.ts
comment points to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #46
Signed in, language, theme and sign-out now sit in a disclosure under the
user's name, closing on Escape and on an outside click. Guests keep them in
the bar. The search sits in the middle column from md up; below, it takes
the space the logo mark and the icon-only buttons leave.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review follow-ups: Translated now sits inside the menu, so a language change
remounts only the controls. The search centres from xl up, where an admin's
links fit their column. Escape refocuses the button only from inside the
menu. The theme switch is a group of three equally wide buttons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #48
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A multi-stage Dockerfile builds one generic image from the Next.js
standalone output; the container applies pending migrations on start
and keeps uploads in a volume. docker/ holds a Compose example with
MariaDB. Local development stays on the host, so standalone output is
only switched on in the image build.

The image is built without a database, so the settings baked into the
prerendered shells are the defaults, marked stale at once: the first
request at runtime regenerates the shells with the stored settings
(ADR-0014).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-on: #50
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko changed title from WIP: Version 1.0.0 to Version 1.0.0 2026-11-02 20:13:27 +01:00
miko self-assigned this 2026-11-02 20:17:16 +01:00
miko manually merged commit 5fa1a7403c into master 2026-11-02 20:18:48 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!51
No description provided.