Merge feat/calm-suggestions: drop no-op suggestions + suppress fickle re-edits

Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd

.env.example

@@ -7,6 +7,9 @@ BASE_URL=http://localhost:8080
 # Database (SQLite, pure-Go modernc — no cgo)
 DATABASE_PATH=./data/petal.db
 
+# On-disk store for images pasted/dropped/inserted in the editor
+IMAGE_DIR=./data/images
+
 # LLM
 LLM_BACKEND=vllm                  # vllm | ollama
 LLM_ENDPOINT=http://localhost:8000   # vLLM :8000, Ollama :11434
@@ -14,6 +17,20 @@ LLM_MODEL=                        # checkpoint model (small/fast). Never hardcod
 LLM_CHAT_MODEL=                   # Ask Petal model (Mandarin-native). Falls back to LLM_MODEL if empty.
 LLM_TIMEOUT=30s
 
+# Read-aloud (TTS). Off unless TTS_ENDPOINT is set — when empty, the /api/tts route
+# is not mounted and the frontend falls back to the browser's Web Speech API.
+# Backed by a local Piper HTTP server (python3 -m piper.http_server).
+# Each Piper HTTP server loads ONE voice, so English and Chinese need separate
+# instances (different ports). zh is only routed when both TTS_ENDPOINT_ZH and
+# TTS_VOICE_ZH are set; otherwise Chinese falls back to Web Speech.
+TTS_ENDPOINT=                     # e.g. http://127.0.0.1:5005 — empty disables server TTS
+TTS_ENDPOINT_ZH=                  # e.g. http://127.0.0.1:5006 — Chinese Piper instance
+TTS_VOICE_EN=en_US-amy-medium     # Piper voice id for English
+TTS_VOICE_ZH=zh_CN-huayan-medium  # Piper voice id for Chinese
+TTS_CACHE_DIR=./data/tts          # on-disk store for synthesized clips (content-addressed)
+TTS_TIMEOUT=15s
+TTS_AUDIO_FORMAT=mp3              # mp3 | opus | wav — mp3/opus transcode Piper's WAV via ffmpeg
+
 # --- Deferred (not wired in the local-dev build) ---
 
 # Auth (Authentik OIDC) — deferred; single hardcoded local user for now

BUILD_PLAN.md

@@ -7,6 +7,7 @@ Multi-session build. **Source of truth for what's done and what's next.** Update
 - **Copyleaks deferred** — needs a public webhook; skip Tier-2 plagiarism until there's a public endpoint. Tier-1 voice-consistency (local) is in scope.
 - **Traefik/deploy deferred** — local dev first.
 - **LLM**: Qwen 3.5 (256K context) on 64GB dual-GPU. Grammar checkpoint cap ~10K tokens (latency guard); voice pass sends whole document.
+  - **Reasoning models**: the Ollama client sends `"think": false` on every request. Qwen 3.5 is a reasoning model — left on, it streams chain-of-thought into a separate `thinking` field and exhausts `num_predict` before emitting any answer in `content` (empty response). Non-thinking models ignore the flag. (Validated on deployment hardware 2026-06-25.)
 - **Suggestion anchoring**: resolve by `original` string in ProseMirror coords at render time; stored `from_pos`/`to_pos` are plaintext offsets for server-side use only. (Spec Note #6.)
 - **Aesthetic is an acceptance criterion**: pretty, warm, Chinese-woman-friendly; CJK fonts first-class.
 
@@ -21,52 +22,144 @@ Multi-session build. **Source of truth for what's done and what's next.** Update
 - [x] Dev workflow documented in README; `.env.example` added
 - [x] Verified end-to-end: binary serves `/api/health` + embedded SPA + SPA fallback
 
-### Phase 1 — Data layer
+### Phase 1 — Data layer ✅
-- [ ] SQLite (modernc) init + migrations (`internal/db/db.go`)
+- [x] SQLite (modernc) init + migrations (`internal/db/db.go`) — versioned `schema_migrations` runner, WAL + foreign keys, single writer conn
-- [ ] Models: User, Document, Suggestion (`internal/db/models.go`)
+- [x] Models: User, Document, Suggestion (`internal/db/models.go`) — + type/status constants
-- [ ] Seed hardcoded `local` user
+- [x] Seed hardcoded `local` user (idempotent on startup)
-- [ ] Schema includes `voice` in suggestions type CHECK
+- [x] Schema includes `voice` in suggestions type CHECK (full spec schema incl. plagiarism_reports, to avoid a later migration)
+- [x] `db.Open` wired into `cmd/server/main.go`; `db_test.go` covers migrate/seed idempotency, CHECK constraint, FK cascade
 
-### Phase 2 — Document CRUD + auto-save  ← first "it works" milestone
+### Phase 2 — Document CRUD + auto-save  ← first "it works" milestone ✅
-- [ ] Doc handlers: list/create/get/update/delete (`internal/docs/handlers.go`)
+- [x] Doc handlers: list/create/get/update/delete (`internal/docs/handlers.go`) — chi sub-router mounted at `/api/docs`, all scoped to `local` user, partial-update via COALESCE so rename and full save share one PUT; `handlers_test.go` covers the lifecycle
-- [ ] Frontend DocList sidebar (create/rename/delete)
+- [x] Frontend DocList sidebar (create/rename/delete) — `DocList`/`DocListItem`, optimistic title/word-count patching
-- [ ] Tiptap EditorCore (StarterKit, Underline, TextAlign, Placeholder, CharacterCount)
+- [x] Tiptap EditorCore (StarterKit, Underline, TextAlign, Placeholder, CharacterCount) + inline `Toolbar` (B/I/U, H1/H2, bullets, align)
-- [ ] `useAutoSave` (1.5s debounce) → PUT /api/docs/:id
+- [x] `useAutoSave` (1.5s debounce) → PUT /api/docs/:id, with `saveNow()` flush before doc switch/create
-- [ ] StatusBar: word count + save status
+- [x] StatusBar: word count + save status (Editing→Saving→Saved, fades after 3s)
-- [ ] Keep `content` (Tiptap JSON) and `content_text` (plain) in sync on save
+- [x] Keep `content` (Tiptap JSON) and `content_text` (plain) in sync on save — editor emits both + word_count together
 
-### Phase 3 — LLM grammar checkpoint
+### Phase 3 — LLM grammar checkpoint ✅
-- [ ] `LLMClient` interface + factory (`internal/llm/client.go`)
+- [x] `LLMClient` interface + factory (`internal/llm/client.go`) — chat-model fallback in factory; doc/history truncation helpers
-- [ ] `vllm.go` (OpenAI-compat), `ollama.go` (native) — both behind interface
+- [x] `vllm.go` (OpenAI-compat), `ollama.go` (native) — both behind interface; Complete + Stream; no client-level timeout (ctx deadline for Complete, open stream for SSE)
-- [ ] `checkpoint.go` (30s/doc rate limit), `prompts.go`
+- [x] `checkpoint.go` (30s/doc `RateLimiter`), `prompts.go` — brace-matched JSON salvage from model output, empty-original drop, type normalization
-- [ ] `POST /api/docs/:id/check`
+- [x] `POST /api/docs/:id/check` (+ `GET /api/docs/:id/suggestions`, `POST /api/suggestions/:id/{accept,dismiss}`) in `internal/suggestions`; replaces pending set per check, leaves accepted/rejected as history; throttled checks return current set
-- [ ] `useCheckpoint` (4s debounce) + checkpoint indicator
+- [x] `useCheckpoint` (4s debounce) + breathing rose checkpoint dot in StatusBar
-- [ ] SuggestionMark + SuggestionCard (accept/dismiss); **string-anchoring**, not stored pos
+- [x] `SuggestionHighlight` (ProseMirror **decorations**, re-anchored by `original` string on every doc change — not stored marks) + `SuggestionCard` (accept applies replacement in-editor then PATCHes; dismiss)
-- [ ] Suggestion colors: grammar=mint, phrasing=peach, idiom=lavender, clarity=sky
+- [x] Suggestion colors: grammar=mint, phrasing=peach, idiom=lavender, clarity=sky (honey reserved for voice)
 
-### Phase 4 — Ask Petal (conversational follow-up)
+### Phase 4 — Ask Petal (conversational follow-up) ✅
-- [ ] `POST /api/suggestions/:id/chat` SSE streaming; server-side context injection
+- [x] `POST /api/suggestions/:id/chat` SSE streaming; server-side context injection — `internal/suggestions/chat.go` loads the suggestion + parent doc in one user-scoped query, extracts the `\n\n`-bounded paragraph around `from_pos` (falls back to truncated doc when `from_pos == -1`), injects it via `AskPetalSystemPrompt`, streams `event: token`/`event: done` SSE frames (JSON-encoded data so token newlines don't break framing). LLM-unreachable returns a clean 502 before any SSE headers; unknown suggestion 404s.
-- [ ] AskPetal component, token-by-token render, no persistence
+- [x] AskPetal component, token-by-token render, no persistence — `AskPetal.tsx` holds the whole conversation in component state (cleared on close), pre-seeds Petal's first bubble with the suggestion explanation, streams via `streamSuggestionChat` (fetch + ReadableStream, not EventSource). `SuggestionCard` gains an "Ask Petal ✨" pill; the card pins open (hover-close suppressed, click-away to dismiss) while the panel is expanded.
-- [ ] CJK font fallbacks on chat bubbles (spec Note #17)
+- [x] CJK font fallbacks on chat bubbles (spec Note #17) — bubbles + input use the `'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC'` stack (the user asks in Mandarin); applied to the chat surface only, not the serif editor body.
+- `internal/llm/chat.go`: `StreamAskPetal` (max_tokens 512, temp 0.7, rep 1.15, top_p 0.92, stop `\n\n\n`) reusing the existing `AskPetalSystemPrompt` + `TrimHistory`. Backend stays interface-only; the SSE handler never touches a concrete client.
 
-### Phase 5 — Voice consistency pass (Tier 1)
+### Phase 5 — Voice consistency pass (Tier 1) ✅
-- [ ] `POST /api/docs/:id/voice`, whole-document, slow cadence / explicit action
+- [x] `POST /api/docs/:id/voice`, whole-document (no `TruncateDoc`), explicit "Check my voice 🍯" toolbar action — `internal/llm/voice.go` (`RunVoice`, `VoiceInterval` 20s floor, MaxTokens 2048), `voiceSystemPrompt`/`VoiceMessages` in `prompts.go` (standalone — not bundled with the grammar checkpoint per spec)
-- [ ] `voice` suggestion type, honey decoration (`--color-honey`)
+- [x] `voice` suggestion type, honey decoration — type already in schema/CSS; voice flags carry `replacement: null` → stored `""`, `SuggestionCard` hides the diff row + Accept (Dismiss only)
+- [x] **Family-scoped pending sets**: grammar and voice are independent passes sharing the suggestions table. `replacePending` now scopes its DELETE by family (`pendingScope`: grammar = `type != 'voice'`, voice = `type = 'voice'`), so neither pass wipes the other's pending flags. Both `/check` and `/voice` return the **unified** pending set (grammar + voice) so the client never drops one family's highlights when the other refreshes (also fixes a latent throttle-vs-success inconsistency).
+- [x] Frontend: `api.voiceDoc`, `useCheckpoint` gains `voicing`/`runVoice` (shares the run-token guard), `Toolbar` honey "Check my voice 🍯" pill (loading→"Reading…"), `StatusBar` breathing honey dot "Reading your voice…". `check`/`voice` collapsed into a shared `runPass` server-side.
+- Tests: `TestVoicePassCoexists` (grammar+voice coexist, unified response, null→"" replacement, voice re-run scoped). go build/vet/test clean, tsc clean, vite build OK; live smoke vs a fake vLLM (voice anchored at 62, grammar preserved, unified list `[grammar, voice]`).
+- **Known limitation (carried from Phase 3)**: `findRange` anchors within a single textblock, so a voice passage spanning a paragraph break (`\n\n`) won't decorate. Model passages usually sit within one paragraph; multi-block anchoring is deferred.
 
-### Phase 6 — Design system & polish
+### Phase 6 — Design system & polish ✅
-- [ ] Full pastel tokens, Nunito + Lora + JetBrains Mono
+- [x] Full pastel tokens, Nunito + Lora + JetBrains Mono — `@theme` tokens + Google Fonts (landed in Phase 0, in use throughout)
-- [ ] Shape language, shadows, transitions
+- [x] Shape language, shadows, transitions — `--radius-*`, `--shadow-soft`, global `200ms ease` on interactive elements
-- [ ] Signature animations (suggestion fade-float, accept confetti, breathing checkpoint dot)
+- [x] Signature animations (suggestion fade-float, accept confetti, breathing checkpoint dot) — fade-float + breathing dot already live; **accept confetti** added this phase: CSS-only 4-dot burst (`petal-confetti`/`@keyframes petal-confetti`, direction via `--dx`/`--dy` inline), spawned in `EditorCore.handleAccept` at the card position, auto-cleared after 720ms
-- [ ] Distraction-free mode
+- [x] Distraction-free mode — entered on editor focus (`EditorCore` `onFocus` → `App.setFocusMode`), the doc-list sidebar slides left + collapses to 0 width (`.petal-sidebar`/`.petal-sidebar-hidden`, 280ms), editor canvas re-centers full-width. Restored by Escape or a pointer-down outside the centered canvas (gutters, header, status bar via `handleChromeDown` + `canvasRef` containment check)
+- [x] **Companion mascot** (`web/src/components/Companion/`) — cozy corner mascot that reacts to the writing session. `useCompanion` is the library-agnostic behavior engine (cheers on accept/milestones, Mandarin-first writing tips, screen-break reminders after a long stretch, idle naps + welcome-back); `PetalCompanion` renders it + a CJK-first speech bubble (zh prominent, en subtitle — Note #17). Animation via `lottie-web/build/player/lottie_light` (offline, no eval/CDN) behind a `LottiePlayer` wrapper that **auto-crops the asset to its content bbox** (unions getBBox across 6 frames → square viewBox) so stock files with empty artboard padding fill the badge. **Selectable companions** (`companions.ts` roster): clicking the mascot opens a bilingual picker ("选个小伙伴 · Choose a companion") to switch between **瞌睡猫 Sleepy Cat** (`sleeping-cat.json`, `alwaysAsleep` → every mood maps to the sleeping loop, so she snoozes yet still mumbles tips/cheers — a deliberate gag) and **开心狗 Happy Dog** (`happy-dog.json`, awake/bouncy; naps via 😴 emoji). Choice persists in `localStorage` (`petal.companion`). Add a companion = drop a pure-vector Lottie JSON in `animations/` + append a `COMPANIONS` entry. `napping = companion.alwaysAsleep || mood === 'sleeping'` drives the sway/zzz. Each asset is auto-cropped to its content bbox by `LottiePlayer`. App feeds it `editTick`/`acceptTick` + `wordCount`/`saveStatus`. All copy bilingual in `tips.ts`. (`resolveJsonModule` enabled in tsconfig for the JSON import.)
 
-### Phase 7 — Spell check
+### Phase 7 — Spell check ✅
-- [ ] nspell browser-side (en-US), vendor dictionaries
+- [x] nspell browser-side (en-US), vendor dictionaries — Hunspell `en.aff`/`en.dic` (from `dictionary-en`, now a devDep) vendored into `web/public/dictionaries/en/` (+ upstream `LICENSE`); Vite copies them to `dist/`, the Go binary embeds them. ~550KB `.dic` stays out of the JS bundle, fetched as a static asset.
+- [x] `useSpellChecker` hook (App-level, loads **once per session** not per doc) — `fetch`es aff+dic, builds an `nspell` instance, replays a personal word list from `localStorage` (`petal.spell.personal`); `addWord` persists + bumps a `version` so the checker's identity changes and consumers re-decorate. Exposes a minimal `SpellChecker` ({ `correct`, `suggest` }). Ambient types in `src/types/nspell.d.ts` (package ships none).
+- [x] `SpellCheck` Tiptap extension — ProseMirror **decorations** (no stored marks, same as the AI-suggestion layer), recomputed on doc edit / caret move / checker swap. English-only tokenizer (`/[A-Za-z][A-Za-z']*/`) so **CJK is never tokenized → never flagged** (north-star: the user writes Mandarin + English); skips <2-char tokens and all-caps acronyms, trims edge apostrophes. Exempts the word under the caret (no jitter mid-typing). Reuses `mapOffset` (now exported from `SuggestionHighlight`) for atom-aware offset→PM-pos mapping. `wordAt(doc, pos)` resolves the exact span under a click (robust to duplicate misspellings).
+- [x] `MisspellCard` popover + EditorCore wiring — soft **rose wavy underline** (`.petal-misspelling`, pastel take on the red squiggle, not classic red). Click a flagged word → `posAtCoords`→`wordAt` opens a bilingual card ("拼写 · Spelling") with up to 5 nspell corrections as pills (click to replace via `insertContentAt`) + "添加到词典 · Add to dictionary". Closes on outside-pointer-down, doc edit, or doc switch.
+- Verified: tsc clean, vite build OK (dict in `dist/dictionaries/en/`), go build/vet clean; live server serves both dict files (200, 3086B aff / 551762B dic); nspell smoke (`helllo→hello`, `recieve→receive`, `写作` untokenized, `NASA` ok, `add()` persists).
+
+### Phase 8 — Trust foundation (version history + export) ✅
+- [x] **Version history** — `document_versions` table (migration `0003`), full-body snapshots that cascade with the doc. Kinds: `auto` (throttled background, ≥3min apart, max 40/doc, pruned), `manual` (explicit restore point), `pre_restore` (safety copy taken before a restore, so restore is undoable). Snapshot taken post-save in `update` only when a real body came through and content changed (empties + bare renames never snapshot). Endpoints: `GET/POST /api/docs/:id/versions`, `GET /api/docs/:id/versions/:vid`, `POST /api/docs/:id/versions/:vid/restore`. All scoped to the owner via a join on `documents`. `versions_test.go` covers lifecycle/throttle/restore/pre_restore/404.
+- [x] **Export** — pure-Go Tiptap-JSON → Markdown / HTML / plain-text / **docx** (`export.go`), no cgo/pandoc, CJK-safe. docx is a hand-built OOXML zip (marks→run props, headings→built-in styles, lists→prefix). RFC 5987 `filename*=UTF-8''` so Chinese titles download cleanly. `GET /api/docs/:id/export?format=`. **PDF is client-side** via the browser print dialog + a `@media print` stylesheet (uses the reader's fonts → CJK for free, no embedded-font bloat). `export_test.go` asserts every format incl. valid-zip docx with CJK.
+- [x] **Frontend** — `ExportMenu` (download links + Print/PDF) and `HistoryPanel` (slide-over drawer: snapshot list w/ relative-time + kind badge, preview, restore; restore remounts the editor via an `editorEpoch` bump). Both bilingual zh-first, matching chrome. Wired into the title row; `.petal-no-print` strips all chrome for print.
+- [x] **Stop saving empty docs** — blank `Untitled` drafts now self-discard: `handleCreate` reuses an existing blank instead of stacking another; `openDoc` deletes the blank doc being left. Cleaned the 2 existing orphan empties from the live DB. (Backend also refuses to snapshot empties.)
+- Verified: go build/vet/test + tsc + vite all clean; live smoke on a throwaway binary — auto-snapshot on save, throttle holds at 1, manual snapshot, restore brings back exact text + leaves a `pre_restore`, empty doc → no snapshot, md/docx export with CJK+bold+heading+list, docx validates as "Microsoft Word 2007+".
+
+### Phase 9 — ESL superpowers ✅
+- [x] **Inline Chinese gloss (offline)** — embedded English→Chinese dictionary (`internal/lexicon/data/gloss.json.gz`, ~1.3MB, 57k common words built from ECDICT via `scripts/build_gloss.py`: frequency-gated to rank ≤50k, `[网络]`/slang/archaic sense-lines dropped, trimmed to ≤3 senses / 80 chars). `Lexicon` gains a `gloss` map + `Gloss(word)` (same `candidates()` de-inflection as defs/syns); `Result` gains a `Gloss` field. Two surfaces: the right-click **WordCard** now leads with the 中文 gloss, and a new lightweight `GET /api/gloss/{word}` (→ `{word, gloss}`, cached) backs the **hover tooltip**. Offline + instant, works with the LLM down (north-star reliability). Frontend: `GlossTip` (dark pointer-events-none bubble under the resting word; 350ms hover delay; reuses `wordAt` so CJK is never glossed — it's the source language), wired into `EditorCore`'s `onMouseMove`/`onMouseLeave` with a request-token guard, suppressed during selection/preview/other popovers.
+- [x] **"Say it more naturally" / tone-rewrite** — selecting text pops a `SelectionBubble` (✨更自然 + the tone vocabulary 学术/专业/轻松/幽默/创意/说服, mirrored from `ToneSelect`/`styleGuidance`). Picking a style calls `POST /api/docs/:id/rewrite` (`{text, style}` → `{rewrite}`), shown in a `RewritePreview` (original struck-through → rewrite, 用这个/取消, breathing-dot loading, gentle retry on failure). Accept applies it in-editor via `insertContentAt` over the captured PM range. Backend: `llm.RunRewrite` (one-shot Complete, `RewriteMaxRunes` 2000 cap, `cleanRewrite` strips stray wrapping quotes) + `rewriteSystemTemplate`/`styleGuidance` in `prompts.go`; handler in `internal/suggestions/rewrite.go` (owner-scoped 404, 400 on empty/too-long, 502 on LLM-down). **Stateless** — not persisted as a suggestion; the version history captures the resulting doc change.
+- Tests: `lexicon` gloss + Lookup-includes-gloss + inflection/miss; `suggestions` rewrite happy-path (style steering + de-quote asserted), empty→400, unknown-doc→404. go build/vet/test clean, tsc clean, vite build OK. Live smoke vs a fake vLLM (fresh port 8055, throwaway DB; pre-existing dev servers on :8077/:8099 untouched): gloss for `river`/inflected/CJK-empty/nonsense-empty, `word/happy` carries the gloss, rewrite returns text, empty→400, unknown→404, LLM-down→502; new CSS classes present in the built bundle.
+- **Known limitation**: `Gloss` tries the literal form first (matching defs/syns ordering), so an inflected word that is *itself* a separate ECDICT headword resolves to that entry rather than de-inflecting (e.g. `rivers` → the proper-noun "Rivers" sense, not `river`). The base form always glosses correctly; acceptable.
+
+### Phase 10 — Organization & polish ✅
+- [x] **Cross-document search (FTS5)** — migration `0004` adds a `documents_fts` virtual table over `title` + `content_text` using the **`trigram` tokenizer** (so search works for both English and space-free Chinese; the default unicode61 tokenizer treats a CJK run as one token). Kept in sync by `AFTER INSERT/UPDATE/DELETE` triggers on `documents`, back-filled from existing rows in the migration (verified: pre-existing docs are searchable immediately). `GET /api/search?q=` (`internal/docs/search.go`): queries of ≥3 runes use the FTS index (fast, `ORDER BY rank`); shorter queries fall back to a `LIKE` scan so **2-character Chinese words** (e.g. 公园) still resolve. Snippets are built in **Go** from the original text (clean word boundaries, rune-aware so CJK never splits mid-char), with the match wrapped in `\x01…\x02` sentinels; the client splits on these to highlight without `innerHTML`. Owner-scoped, capped at 50 hits. Frontend `SearchBox` in the sidebar: 220ms-debounced, results with highlighted two-line snippets, click to open.
+- [x] **Tags (organize)** — migration `0004` adds `tags` (user-scoped, `UNIQUE(user_id, name)`, `color` = palette key) + `document_tags` join (both sides cascade). `internal/docs/tags.go`: `GET/POST/PATCH/DELETE /api/tags` (create is **idempotent** on name; unknown colors coerced to rose) + `POST /api/docs/:id/tags` / `DELETE /api/docs/:id/tags/:tagId` (owner-validated, idempotent assign). The doc-list and search responses carry each doc's tags (loaded in one `tagsByDoc` query, no N+1). Frontend: `useTags` (roster + counts), `TagChip`, `TagPicker` (assign existing / create-and-attach with a color swatch), tag chips on each doc row, a **filter bar** (client-side filter by tag, shows in-use tags with counts). Colors map to the existing design tokens via `tagColorVar`.
+- [x] **Tablet / touch polish** — responsive sidebar: below 768px it becomes an overlay **drawer** toggled by a header hamburger, with a scrim (auto-closes on doc select). `@media (pointer: coarse)` enlarges tap targets (`.petal-tap` ≥44px, `.petal-tap-sm` ≥36px) and reveals the hover-only row actions (tag/delete). **Tap-to-open** for AI-suggestion cards (no hover on touch): a tap on a `.petal-suggestion` opens its card via the editor click handler, and a `pointerdown` outside the card/highlight dismisses it (mouse users keep the hover bridge).
+- [x] **Warm LLM-down failure states** — `useCheckpoint` now tracks an `llmDown` flag (set when a check/voice pass hits the server's 502/network path, cleared on the next success or doc switch). The `StatusBar` shows a gentle bilingual note — 🌙 **小助手在休息 · Petal's helper is resting · 文字已保存** — reassuring that the writing still saved locally (saving is independent of the LLM). Rewrite already had a gentle retry from Phase 9.
+- Tests: `tags_test.go` (full lifecycle — create/idempotent/color-coerce/rename-recolor/assign/unassign/doc-list inclusion/roster counts/delete-cascade/404s), `search_test.go` (EN FTS, CJK FTS, 2-char CJK LIKE fallback, title-only, case-insensitive, empty/no-match, **edit re-indexes via the update trigger**). go build/vet/test clean, tsc clean, vite build OK. Live smoke vs the binary on a throwaway DB (port 8061, LLM pointed at a dead host): search EN/CJK/2-char all highlighted, tag create+assign+roster-counts+doc-list-tags+delete-cascade, check→502 (warm path), new CSS classes (`petal-tag-chip`/`petal-scrim`/`petal-drawer-open`/`pointer:coarse`) and the 小助手在休息 string present in the served bundle. FTS backfill of pre-existing docs verified separately.
+- **Known limitations**: trigram FTS snippets/ranking treat the query as a contiguous phrase (multi-term relevance is substring, not BM25-per-term) — fine for a personal corpus. Search is title+body only (not tag names). Hover gloss and right-click word lookup remain pointer-oriented (long-press contextmenu on touch is browser-dependent); the spelling/suggestion cards and rewrite bubble are fully touch-reachable.
+
+### Phase 11 — Writer power-ups ✅
+- [x] **In-document Find & Replace (Ctrl/Cmd+F)** — `SearchHighlight` ProseMirror extension (decorations, not marks — same anchoring discipline as the suggestion/spell layers; matches recomputed per-textblock on every edit, never stranded). `FindReplace` bar (bilingual zh-first): live match highlighting, ↑/↓ step-through with no-selection DOM scroll-into-view (so it never pops the rewrite bubble), match-case toggle, replace / replace-all (replace-all applies back-to-front so earlier edits don't shift later positions). Honey wash on all matches, rose ring on the active one.
+- [x] **Read-aloud / TTS** (`web/src/audio/speech.ts`) — Web Speech API, offline, feature-detected. 🔊 in the `WordCard` (pronounce the word) and the selection bubble (read the selection). Pairs with the phonetic line.
+- [x] **Keyboard + touch access to the ESL helpers** — refactored the right-click word-lookup into a position-based `openWordLookup(pos)`; now also driven by **Ctrl/Cmd+D** (look up the word at the caret) and a **touch long-press** (~500ms, the touch equivalent of right-click). **Ctrl/Cmd+J** rewrites the selection more naturally. (Closes the "pointer-only" limitation noted in Phase 10.)
+- [x] **Whole-corpus backup** — `GET /api/docs/export-all?format=md|docx|…` zips every doc (reuses the per-doc renderers; de-duplicates same-titled filenames; dated `petal-backup-YYYY-MM-DD.zip`). Static route takes priority over `/{id}` in chi — covered by `TestExportAll`. Sidebar footer "备份 · Back up all: Word / Markdown" download links.
+- [x] **Smart typography** (`Typography.ts`) — dependency-free input rules: curly quotes, em-dash (`--`), ellipsis (`...`). ASCII-only triggers so CJK fullwidth punctuation is untouched; every rule is plain-Undo-able.
+- [x] **Org niceties** — duplicate-a-document (App `handleDuplicate` → "… (副本)", copies body/tone, not tags), sidebar **sort** (Recent / Title / Longest), and a **document outline** popover in the toolbar (headings → click to scroll, indented by level).
+- [x] **English phonetic (pivot from pinyin)** — for a native-Mandarin English learner the useful pronunciation aid is the English IPA, not pinyin (she reads Chinese fluently). `scripts/build_phonetic.py` extracts ECDICT's `phonetic` column (same source/freq-gate as the gloss); `phonetic.json.gz` embedded + lazily loaded; `Result.Phonetic` resolved via the same de-inflecting candidate walk; shown as `/ˈrɪvər/` in the WordCard. **Full dataset built from ECDICT: 46,579 words (361KB gz)**, in line with the other lexicon assets. The script also has a `--seed` mode (71 curated common words) that ships as a fallback / works without the csv. Curated seed entries (clean IPA) override the ECDICT form where both exist.
+- Verified: go build/vet/test (incl. new `TestExportAll`), tsc, vite build all clean; live smoke vs throwaway binaries — `/word/river|running|serendipity|rivers` all return phonetic (`rivers`→`river` de-inflected), export-all returns a valid 2-entry zip with de-duped CJK filenames + dated name, route doesn't collide with `/{id}`.
+
+### Phase 12 — Collocation coach ✅ (2026-06-26)
+**Why:** ESL writers nail grammar but miss *which words go together* — "do a decision" → "make a decision", "strong rain" → "heavy rain". These aren't *wrong*, so the grammar pass won't flag them; they're just non-native. Gentle "natives usually say…" hints are the single highest-leverage upgrade for making her writing sound native. **Build this first** — it's small and de-risks the migration-rebuild pattern Phase 13 also needs.
+
+**Key insight:** the suggestion pipeline is already generic over a `pass` + a `pendingScope` "family" (`runPass` in `internal/suggestions/handlers.go`; grammar + voice already prove it). Collocation drops in as a **third family** and reuses the entire accept/dismiss/re-anchoring/rail/Mandarin-explanation machinery — no new frontend rendering layer.
+- [x] `internal/llm/collocation.go` — `CollocationInterval` (25s) + `RunCollocation(...)`, reusing the existing `ParseCheckpoint` parser (same as `RunVoice`). Whole-document (no `TruncateDoc`), tone passed through.
+- [x] `internal/llm/prompts.go` — `CollocationMessages(contentText, tone)` + `collocationSystemPrompt`. The prompt flags only non-wrong-but-non-native word pairings ("do a decision" → "make a decision"), explicitly defers grammar/spelling to the grammar family, and frames every explanation as warm "Natives usually say…" with a Mandarin gloss — never "error/wrong/mistake".
+- [x] `internal/db/models.go` (`SuggestionTypeCollocation`) + migration `0005_collocation_suggestion_type` — **rebuilds** the `suggestions` table (new table w/ extended CHECK, copy rows, drop, rename, recreate `idx_suggestions_doc_id`), since SQLite can't `ALTER` a CHECK. Verified against a copy of the live DB (5 migrations apply cleanly, collocation insert accepted, rows preserved).
+- [x] `internal/suggestions/handlers.go` — `collocationScope` (`deleteWhere: "type = 'collocation'"`, `forceType: collocation`), `CollocationLimit` on `Handler` (+ wired in `New`), `POST /{id}/collocation`, `normalizeType` extended. **Also fixed `grammarScope`** from `type != 'voice'` → `type NOT IN ('voice','collocation')` so a grammar checkpoint no longer wipes the collocation pending flags (the third family must survive like voice does).
+- [x] Frontend: `suggestionMeta.ts` collocation entry (`--color-blossom` warm pink, "Word pairing" label); `client.ts` `collocationDoc(docId)` + `SuggestionType` extended; `index.css` token + `.petal-suggestion-collocation` decoration; `useCheckpoint` `collocating`/`runCollocation` (mirrors `runVoice`, shares the run-token guard); `Toolbar` blossom **"Make it sound natural 🌸"** pill (→ "Reading…"); `StatusBar` breathing blossom dot "Finding natural phrasing…"; threaded through `EditorCore`/`App`. Renders straight into the existing `SuggestionRail`/`SuggestionCard` (Accept applies the native pairing).
+- [x] Verified: go build/vet/test (`TestCollocationPassCoexists` — three families coexist, grammar checkpoint doesn't wipe voice/collocation), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (dead LLM) → collocation route returns the warm 502 like check/voice.
+
+### Phase 13 — Vocabulary garden (spaced repetition) ✅ (2026-06-26)
+**Why:** the lexicon (`internal/lexicon`) is a stateless static-dataset lookup — **nothing records which words she's looked up.** Capturing them turns passive lookups into real vocabulary, and the review surface ties straight into the "petal garden" delight idea (words become blossoms; the sleeping kitten naps among them). Build **after** Phase 12.
+- [x] New `internal/vocab` package + migration `0006_vocab_garden` (0005 was taken by collocation) — `vocab_words` table: `word, gloss, phonetic, example` (sentence captured at lookup), `doc_id` (`ON DELETE SET NULL` so a word outlives its source doc), + SM-2-lite scheduling: `due_at, interval_days, ease, reps, lapses, last_reviewed`; `UNIQUE(user_id, word)` + `idx_vocab_due`.
+- [x] Auto-capture: `EditorCore.openWordLookup` fires `POST /api/vocab` after a successful lookup — **only for words the dictionary actually knows** (a real gloss or definition), so typos/proper-noun lookups don't clutter the garden. Captures the surrounding sentence (`sentenceAround`) + `doc_id`. Idempotent upsert: re-looking-up a word refreshes its gloss/phonetic/example but never resets its schedule.
+- [x] Endpoints (`internal/vocab/handlers.go`): `POST /api/vocab` (upsert; new word → `due_at = datetime('now','+1 day')`), `GET /api/vocab/due` (due now, server-side `datetime('now')` comparison — avoids JS local-vs-UTC parsing bugs), `POST /api/vocab/{id}/review` (grade → reschedule via `datetime('now','+N days')`), `GET /api/vocab` (full garden), `DELETE /api/vocab/{id}`. All owner-scoped.
+- [x] SR scheduler (`internal/vocab/scheduler.go`): gentle SM-2-lite / Leitner ladder (1d → 3d → 7d → 16d → 35d, then geometric by ease). "again" steps back to 1d + counts a lapse + nudges ease down (floored at 1.3) — no harsh wipe; "good" climbs one rung; "easy" climbs a rung and a bit more + raises ease. No streaks to break.
+- [x] Frontend `GardenPanel` (slide-over drawer, sibling to `HistoryPanel`): each word a blossom that opens further with reps (🌱→🌿→🌷→🌸→🌺); a "复习 N 个词 · Review N due" button; per-word detail (phonetic/example/source-doc/remove); footer "🐱💤 N 朵花在花园里" — the sleepy kitten napping among the blossoms. **Flashcard review**: due queue, the example sentence with the word blanked (`blankOut`), flip to reveal word+phonetic+gloss+sentence, again/good/easy grades; **direction alternates** by cursor parity for recognition (EN→中文) *and* production (中文→EN). A 🤍/💚 "save to garden" toggle on `WordCard` alongside the silent auto-capture. Opened from a global 🌷 词汇花园 button in the app header. All copy bilingual zh-first.
+- [x] Verified: go build/vet/test (`scheduler_test.go` — ladder/again-gentle/easy-further; `handlers_test.go` — capture/upsert/due/review/delete lifecycle + empty-word 400 + doc-delete SET NULL), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (throwaway DB) — full capture→list→due→review→delete flow + 400 on bad grade verified end-to-end.
+
+### Phase 14 — Companion warmth + bedtime nag + night mode ✅
+**Why:** the companion kitten is the heart of Petal's "built for her" feel. Three additions: (1) a wider, fresher pool of **encouraging phrases** so cheers don't repeat as quickly; (2) when she's still writing **late at night (≥11pm)**, the kitten gently nags her to go to bed; (3) at the same hour the whole app drifts into a calm **night mode** — dark moonlit theme + the falling petals become **falling stars**. Caring, never scolding — the sleepy-cat gag makes "you should be sleeping too 🐱💤" land perfectly. Self-contained, frontend-only.
+- [x] `web/src/components/Companion/tips.ts` — `ENCOURAGEMENTS` grown from 5→10 bilingual zh-first lines so cheers rotate fresher. New `BEDTIME: Line[]` array — four warm/playful lines (user-supplied English wit: "I bet your bed is missing you right now", "A tired writer is a bad writer", "Sleep is a wondrous enabler", "Hear that? No… everyone is sleeping and you should be too") with gentle Mandarin leads.
+- [x] `web/src/components/Companion/useCompanion.ts` — bedtime check folded into the existing 10s heartbeat (after the idle-return + break check, before the generic tip): `isBedtime()` = local hour ≥ 23 or < 4 (`new Date().getHours()`, the writer's machine clock). Only fires while actively writing (idle branch returns first). Own `lastBedtime` ref + `BEDTIME_GAP` 30min cooldown; respects `PROACTIVE_GAP`. New `BubbleTone` `'bedtime'` paces `readBubbleMs` (BUBBLE_MS + 4s lingers a touch longer for a wind-down read). Window knobs `BEDTIME_FROM`/`BEDTIME_TO` so the 11pm–4am range is one edit to retune.
+- [x] No tone-based bubble styling exists, so no CSS needed; the tone is metadata for pacing only. Sound stays the rotating pop.
+- [x] **Night mode** — `web/src/lib/night.ts` centralizes `isBedtime()` + the `BEDTIME_FROM`/`BEDTIME_TO` window (shared with the companion nag so they always agree). `web/src/hooks/useNightMode.ts` re-checks every 60s and toggles a `petal-night` class on `<html>`. `index.css` adds an `html.petal-night` block that **only re-points the palette tokens** (`--color-bg/surface/border/plum/muted/accent…`) to a dark moonlit set — every Tailwind color utility reads them via `var()`, so the whole UI flips with zero component changes (verified: `.text-plum{color:var(--color-plum)}`). Accent/type colors kept (they pop on dark); 600ms bg/color fade for a gentle dusk transition; print stays white (the `#fff` override is inside `@media print`).
+- [x] **Falling stars** — `PetalFall` gains a `night` prop. Particles are **chunky cartoon power stars** (`makeCartoonStar`, Mario/Kirby-style: fat 5-point shape, glossy radial fill, puffy round-join colored outline, corner shine + soft glow halo so they pop off the dark sky) in 5 candy colors (`CARTOON_COLORS`), mixed ~70/30 with small four-point twinkle sparkles (`makeStarSprite`/`STAR_PALETTE`) for depth. Every star clearly **spins** (random direction, ~0.5–2.2 rad/s so the quick ones really whirl while slow ones drift for contrast; guaranteed min speed since a 5-point star is symmetric every 72°), **falls straight down** (no sway — that's a petal thing), and shimmers via a shallow alpha pulse (not blink). Effect re-inits on the day↔night flip. App wires `const night = useNightMode()` → `<PetalFall night={night} />`. All sprites are canvas-drawn (offline, no asset files) — `sprites[]` is an image array, so a real PNG/SVG star could drop in later without restructuring.
+- [x] Verified: tsc clean, vite build OK, companion vitest 45/45. **Real-browser screenshots** (local Playwright + Chromium, clock mocked to 23:30): day = warm cream + pink sakura petals; night = dark plum-indigo + twinkling stars + glowing sleepy kitten. Both pretty (acceptance criterion).
 
 ### Deferred (post-v1-local)
-- [ ] Authentik OIDC auth + session middleware
+- [ ] Authentik OIDC auth + session middleware  ← **on hold: user doing foundational work first**
 - [ ] Copyleaks Tier-2 + webhook HMAC
 - [ ] Dockerfile, docker-compose, Traefik, deploy to write.parodia.dev
 
+### Next-up (post-v1 product, agreed with user 2026-06-26)
+- [x] **Phase 9 — ESL superpowers**: inline Chinese gloss on hover/select; "say it more naturally" / tone-rewrite. ✅ (see Phase 9 above)
+- [x] **Phase 10 — organization & polish**: cross-doc search, tags, tablet/touch polish, warm LLM-down failure states. ✅ (see Phase 10 above; "tags only" chosen over folders, FTS5 over LIKE)
+- [x] **Phase 12 — collocation coach**: gentle "natives usually say…" hints for non-native word pairings, as a third suggestion family. ✅ (see Phase 12 above)
+- [x] **Phase 13 — vocabulary garden**: spaced-repetition review built from looked-up words, surfaced as a blooming garden. ✅ (see Phase 13 above)
+- [x] **Phase 14 — companion warmth + bedtime nag + night mode**: more encouraging phrases, a gentle "go to bed" nudge after 11pm, and a calm dark theme + falling stars at night. ✅ (see Phase 14 above)
+
 ## Session log
+- 2026-06-26: **Phases 12 + 13 complete** (collocation coach + vocabulary garden — "finish the rest of the build plan except Authentik/Traefik"). **Phase 12**: collocation drops in as a third suggestion family reusing the whole `runPass`/`pendingScope` machinery — `llm/collocation.go` (`RunCollocation`, 25s floor, reuses `ParseCheckpoint`), `collocationSystemPrompt`/`CollocationMessages` (warm "Natives usually say…" + Mandarin gloss, defers grammar elsewhere), migration `0005` **rebuilds** the suggestions table to extend the `type` CHECK (SQLite can't ALTER a CHECK), `collocationScope` + `CollocationLimit` + `POST /{id}/collocation`. **Caught a latent bug**: `grammarScope` was `type != 'voice'` → would wipe collocation flags; fixed to `type NOT IN ('voice','collocation')`. Frontend: `--color-blossom` pink, "Make it sound natural 🌸" toolbar pill, `collocating`/`runCollocation` in `useCheckpoint`, StatusBar dot — all into the existing rail/card. **Phase 13**: new `internal/vocab` package — migration `0006_vocab_garden` (`vocab_words`, SM-2-lite columns, doc_id `ON DELETE SET NULL`, `UNIQUE(user_id,word)`), `scheduler.go` (Leitner ladder 1/3/7/16/35 → geometric; gentle "again", no streak-shaming), `handlers.go` (capture-upsert/list/due/review/delete, all owner-scoped, time math via SQLite `datetime()` so stored values stay canonical-UTC). Auto-capture wired into `EditorCore.openWordLookup` (only dictionary-known words, captures the surrounding sentence + doc_id) + a 🤍/💚 toggle on `WordCard`. `GardenPanel` slide-over: blossom grid (bloom stage by reps), flashcard review (sentence blanked, flip, again/good/easy, direction alternates recognition↔production), sleepy-kitten footer; opened from a global 🌷 header button. Tests: `TestCollocationPassCoexists`, vocab `scheduler_test.go` + `handlers_test.go`, db CHECK test extended. go build/vet/test + tsc + vite + vitest (51/51) all clean; migration verified against a copy of the live DB; live backend smoke (throwaway DB) walked the full vocab lifecycle + the warm-502 collocation path. **Remaining: only the deferred infra bucket** — Authentik auth, Copyleaks Tier-2 (needs a public webhook), Docker/Traefik/deploy — all on hold per the user's "except Authentik/Traefik".
+- 2026-06-26: **Phase 14 complete** (companion warmth + bedtime nag + night mode). `tips.ts`: `ENCOURAGEMENTS` 5→10 lines; new `BEDTIME` array (4 lines, user-supplied English wit + gentle Mandarin leads). `useCompanion.ts`: bedtime branch in the 10s heartbeat (after idle-return + break, before the generic tip); only nudges while actively writing; own `lastBedtime` ref + 30min `BEDTIME_GAP`, respects `PROACTIVE_GAP`; new `'bedtime'` `BubbleTone` lingers ~4s longer. **Night mode** (added same session, user request): `lib/night.ts` centralizes `isBedtime()` + window (now shared by the nag too); `hooks/useNightMode.ts` toggles `petal-night` on `<html>` (60s re-check); `index.css` `html.petal-night` re-points only the palette tokens → whole UI flips via `var()` (no component edits), 600ms dusk fade, print stays white; `PetalFall` gains a `night` prop → chunky cartoon power stars (`makeCartoonStar`, Mario/Kirby-style, 5 candy colors) mixed ~70/30 with small twinkle sparkles, gentle spin + shallow shimmer, effect re-inits on flip; App: `useNightMode()` → `<PetalFall night={night}/>`. tsc + vite clean, companion vitest 45/45; verified with real-browser Playwright screenshots (clock mocked to 23:30) — day petals/cream vs night stars/dark-plum, both pretty. Bedtime window is `BEDTIME_FROM`/`BEDTIME_TO` (local clock) for easy retune.
+- 2026-06-26: **Phase 11 complete** (writer power-ups, batch requested as "do it all"). Seven features: (1) in-doc **Find & Replace** — `SearchHighlight` decoration extension + `FindReplace` bar (Ctrl/Cmd+F, match-case, replace-all back-to-front, DOM scroll that doesn't trigger the selection bubble); (2) **read-aloud** Web Speech util + 🔊 in WordCard & selection bubble; (3) **keyboard/touch access** — Ctrl/Cmd+D caret lookup, Ctrl/Cmd+J rewrite, touch long-press (refactored `handleContextMenu` → shared `openWordLookup(pos)`); (4) **export-all** backup zip (`GET /api/docs/export-all`, `TestExportAll`, sidebar download links); (5) **smart typography** input-rules extension (curly quotes/em-dash/ellipsis, ASCII-only so CJK untouched); (6) **duplicate doc + sidebar sort + outline popover**; (7) **English phonetic** (pivoted from pinyin — IPA is what an English learner needs; pinyin annotates Chinese she already reads) via `scripts/build_phonetic.py` + embedded `phonetic.json.gz` + `Result.Phonetic` + WordCard `/ˈrɪvər/` line — **full 46,579-word dataset built from ECDICT** (the csv re-download worked; `--seed` mode kept as a csv-free fallback). Also folded in this session: the **selection-bubble vs copy/paste fix** (bubble deferred to pointer-up + container `pointer-events:none` so it never sits where you click). go build/vet/test + tsc + vite all clean; live smoke verified word-phonetic (incl. de-inflection) + export-all zip (de-duped CJK names, route priority). Next: deferred bucket (auth/Copyleaks/deploy), still on hold per user.
+- 2026-06-26: **Phase 10 complete** (organization & polish). Scope confirmed with user: all four areas, **tags** (not folders), **FTS5** search. Backend: migration `0004_tags_and_search` (tags + document_tags + `documents_fts` trigram virtual table with sync triggers + back-fill); `db.Tag` model + color constants; `internal/docs/tags.go` (tag CRUD + idempotent assignment + `tagsByDoc` helper, doc list now carries tags); `internal/docs/search.go` (`GET /api/search`, FTS for ≥3 runes + LIKE fallback for 1-2, Go-built sentinel-highlighted rune-aware snippets, owner-scoped). Mounted `/api/tags` + `/api/search` in main.go. Frontend: `useTags`, `TagChip`/`TagPicker`/`SearchBox`, rewritten `DocList`/`DocListItem` (chips + filter bar + search), `api.search`/tag methods + `splitSnippet`/`tagColorVar`; responsive sidebar drawer (hamburger + scrim, <768px) + `pointer:coarse` tap-target/affordance CSS; tap-to-open + outside-pointerdown-close for suggestion cards (touch); `useCheckpoint` `llmDown` flag → warm bilingual "小助手在休息" StatusBar note. Tests: `tags_test.go`, `search_test.go` (incl. update-trigger re-index). All builds/tests/vet/tsc/vite clean; live smoke vs binary on :8061 (dead LLM host) verified search EN/CJK/2-char, full tag lifecycle, check→502 warm path, bundle contents; FTS backfill of pre-existing docs verified. **All v1 phases (0–7) + post-v1 product (8–10) done.** Remaining: deferred bucket (auth/Copyleaks/deploy), on hold per user.
+- 2026-06-26: **Phase 9 complete** (ESL superpowers: inline Chinese gloss + tone-rewrite). Decisions confirmed with user: gloss is an **offline EC dictionary** (instant, LLM-down-proof, fits the embedded-lexicon ethos), rewrite is a **selection bubble**. Data: `scripts/build_gloss.py` builds `internal/lexicon/data/gloss.json.gz` from ECDICT (66MB csv → 1.3MB gz, 57k freq-≤50k words, cleaned/trimmed). Backend: `lexicon` gloss map + `Gloss()`/`Result.Gloss` + `GET /api/gloss/{word}`; `llm.RunRewrite` + rewrite prompt/`styleGuidance`; `internal/suggestions/rewrite.go` (`POST /api/docs/:id/rewrite`, stateless, owner-scoped). Frontend: `GlossTip` hover tooltip (350ms delay, reuses `wordAt`, CJK-safe) + gloss line in `WordCard`; `SelectionBubble` + `RewritePreview` wired through `EditorCore` (onMouseMove/onSelectionUpdate, request-token guards, clears on edit/doc-switch); `api.glossWord`/`api.rewriteSelection`; CSS for the three new surfaces (+ print-hidden). Tests added in `lexicon` and `suggestions`. All builds/tests/vet/tsc/vite clean; live smoke vs fake vLLM on :8055 verified gloss + rewrite + 400/404/502 paths. Next: **Phase 10 (organization & polish).**
+- 2026-06-26: **Phase 8 complete** (Trust foundation: version history + export) + empty-doc fix. Backend: migration `0003_document_versions`; `internal/docs/versions.go` (throttled auto-snapshot wired into `update`, manual snapshot, restore-with-pre_restore, prune to 40 auto, owner-scoped via join) and `internal/docs/export.go` (pure-Go Tiptap-JSON → md/html/txt/docx, no deps, CJK-safe filenames via RFC 5987). `DocumentVersion` model + kind constants. Tests: `versions_test.go`, `export_test.go` (incl. valid-zip docx assertion). Frontend: `api.client` version/export methods; `ExportMenu` + `HistoryPanel` components wired into the title row; `@media print` stylesheet + `.petal-no-print` for the browser PDF path; `editorEpoch` remount on restore. Empty-doc fix in `App.tsx` (blank drafts reuse-on-create + discard-on-leave via refs to dodge stale closures); deleted 2 orphan empties from the live :8099 DB. Multi-session plan agreed: this session = Phase 8; **Phase 9 (ESL gloss + tone-rewrite)** next, then **Phase 10 (search/folders/polish)**; **auth/deploy (was Phase 11) shelved** until user's foundational work lands. All builds/tests/vet clean; live smoke verified the full version+export+restore flow end-to-end. Next: **Phase 9.**
 - 2026-06-25: Spec reviewed & amended (voice/grammar decoupled, ctx cap, routes, voice DB type, honey color, string-anchoring). Build plan created.
 - 2026-06-25: **Phase 0 complete.** Go module + chi server, config loader, React/Vite/Tailwind-v4 scaffold with full design tokens, frontend embedded & served by the binary, verified end-to-end. Toolchain: Go 1.24.4, Node 22, npm 10. Next: **Phase 1 (data layer)** — SQLite via modernc, models, seed `local` user.
+- 2026-06-25: **Phase 1 complete.** `internal/db` package: modernc.org/sqlite (pulled go toolchain → 1.25), `Open()` does mkdir + WAL/foreign-keys DSN + versioned migration runner + idempotent local-user seed. Models with type/status constants. Wired into `main.go`; tests pass (migrate/seed idempotency, CHECK reject, FK cascade). Verified server boots and writes `petal.db`. Next: **Phase 2 (document CRUD + auto-save)** — first "it works" milestone.
+- 2026-06-25: **Phase 2 complete.** Backend `internal/docs`: chi sub-router (list/create/get/update/delete) mounted at `/api/docs`, local-user scoped, RETURNING on create, COALESCE partial-update (one PUT serves rename + full save), 404/400 JSON errors; `handlers_test.go` walks the full lifecycle. Frontend: `api/client.ts`, `useAutoSave` (1.5s debounce + `saveNow` flush), `EditorCore` (Tiptap StarterKit/Underline/TextAlign/Placeholder/CharacterCount) + `Toolbar`, `DocList`/`DocListItem`, `StatusBar`, rewritten `App.tsx` orchestrating load/select/create/delete with optimistic sidebar patching. `.petal-prose` styles (Lora body, Nunito headings). tsc clean, vite build OK, go build OK; smoke-tested full CRUD incl. CJK title round-trip + SPA serve. Next: **Phase 3 (LLM grammar checkpoint).**
+- 2026-06-25: **Phase 3 complete.** Backend `internal/llm`: `LLMClient` interface + factory (vLLM OpenAI-compat + Ollama native, both Complete/Stream), `prompts.go` (checkpoint + Ask Petal templates), `checkpoint.go` (brace-matched JSON salvage, per-doc 30s `RateLimiter`, doc/history truncation). `internal/suggestions`: `/api/docs/:id/check` + `:id/suggestions` + `/api/suggestions/:id/{accept,dismiss}`; each check replaces the pending set in a tx (accepted/rejected kept as history), throttled checks return the current set, positions located by `strings.Index` (advisory only). Frontend: `useCheckpoint` (4s debounce, loads existing on doc open, run-token guards stale responses), `SuggestionHighlight` Tiptap extension rendering ProseMirror **decorations** re-anchored by `original` string on every doc change (precise textblock offset→PM-pos mapping, handles inline atoms), `SuggestionCard` (type-colored tag, original→replacement diff, accept applies replacement in-editor + PATCHes, hover-bridge with close delay), breathing rose checkpoint dot in StatusBar, suggestion fade-float + breathe CSS. Tests: llm parse/rate-limit/truncate, suggestions full flow + rate-limit over httptest with a stub client. go build/vet/test clean, tsc clean, vite build OK; end-to-end smoke-tested against a fake vLLM endpoint (anchoring verified: `I has`→0:5, `two apple`→6:15) and 502 path when LLM unreachable. Next: **Phase 4 (Ask Petal SSE chat).**
+- 2026-06-25: **Phase 5 complete.** Tier-1 voice-consistency pass. Backend: `internal/llm/voice.go` (`RunVoice` — whole document, no `TruncateDoc`, MaxTokens 2048, `VoiceInterval` 20s per-doc floor), standalone `voiceSystemPrompt`/`VoiceMessages` (not bundled with the grammar checkpoint). `internal/suggestions`: `POST /api/docs/:id/voice` route; `check`/`voice` collapsed into a shared `runPass(limiter, pass, scope)`; `pendingScope` makes `replacePending` family-aware (grammar deletes `type != 'voice'`, voice deletes `type = 'voice'`), so the two passes never clobber each other's pending flags; both endpoints now return the **unified** pending set (also fixed a latent throttle-returns-full-set vs success-returns-batch inconsistency). Frontend: `api.voiceDoc`, `useCheckpoint` → `voicing`/`runVoice` (shared run-token guard, reset on doc switch), honey "Check my voice 🍯" pill in `Toolbar` (→ "Reading…" while in flight), breathing honey dot + "Reading your voice…" in `StatusBar`. Voice flags' `replacement: null` round-trips to `""`; `SuggestionCard` already hides the diff row + Accept for those. Tests: `TestVoicePassCoexists` (coexistence both directions, unified response, null→"" replacement). go build/vet/test clean, tsc clean, vite build OK. Live smoke vs a fake vLLM: grammar check → grammar flag; voice pass → unified `[grammar@0, voice@62 (empty replacement)]`, grammar preserved. Known limitation: `findRange` is single-textblock, so a voice passage crossing a `\n\n` paragraph break won't decorate (deferred). Next: **Phase 6 (design system & polish).**
+- 2026-06-25: **Companion kitten added** (Phase 6 extra, per user request). A cozy corner mascot that gives feedback and gentle nudges. `web/src/components/Companion/`: `useCompanion` (behavior engine — cheer on accept/word-count milestones, Mandarin-first writing tips on a paced timer, screen-break reminder after ~25min continuous writing, idle nap after ~75s + welcome-back; priority/cooldown so it never nags), `tips.ts` (all copy bilingual, zh-first), `LottiePlayer` (wraps `lottie-web` **light** build — offline, no eval/CDN fetch, so it bundles into the Go binary), `PetalCompanion` (kitten + CJK-first speech bubble). **Ships working today with an emoji-kitten placeholder** (😺/😻/😴 per mood, CSS bob/nap/zzz); dropping a Lottie cat JSON into `animations/index.ts` is the only change to upgrade to real animation. Library decision: Lottie via `lottie-web` (not the React wrapper → no React 19 peer-dep friction; not dotLottie → no runtime CDN/wasm, stays offline-embeddable). App wires `editTick`/`acceptTick`/`wordCount`/`saveStatus`. tsc clean, vite build OK (light build trimmed ~34KB gzip vs full + removed eval warning), go build/vet/test clean. Verified headless: greeting bubble on load (“嗨～我在这儿陪你写作哦” + EN subtitle), heart-eyes celebrate + “我很喜欢这个改法 💕” on accept. **TODO (user):** source a Lottie cat asset to replace the emoji placeholder.
+- 2026-06-25: **Phase 6 complete.** Design system & polish. Tokens/fonts/shape/transitions were already in place from Phase 0; this phase added the two missing signature pieces. **Accept confetti**: CSS-only burst (`.petal-confetti-dot` + `@keyframes petal-confetti`, each dot's trajectory from inline `--dx`/`--dy`), a `Confetti` component in `EditorCore` spawned at the accepted card's position on `handleAccept` and cleared after 720ms (timer cleaned up on unmount). **Distraction-free mode**: `EditorCore` gains an `onFocus` → `App` `focusMode` state; the doc-list sidebar is wrapped in `.petal-sidebar` and collapses via `.petal-sidebar-hidden` (width→0 + translateX + fade, 280ms) while the centered editor canvas re-centers into the full pane; restored by Escape (window keydown) or a pointer-down outside the canvas (`handleChromeDown` checks `canvasRef` containment; wired on the header, the editor scroll-gutter, and the status bar). tsc clean, vite build OK, go build/vet/test clean; binary boots and serves the rebuilt SPA with the new CSS embedded (confetti + sidebar-collapse classes verified in the served bundle). Next: **Phase 7 (browser-side spell check, nspell en-US).**
+- 2026-06-25: **Phase 7 complete.** Browser-side spell check (nspell, en-US). Vendored Hunspell `en.aff`/`en.dic` → `web/public/dictionaries/en/` (`dictionary-en` moved to devDep; dict served as a static asset + embedded in the binary, kept out of the JS bundle). `useSpellChecker` (App-level, loads once/session) builds the nspell instance, replays a `localStorage` personal word list, `addWord` persists + bumps a version to re-decorate; `src/types/nspell.d.ts` supplies the missing types. `SpellCheck` extension renders misspellings as ProseMirror decorations (Latin-only tokenizer ⇒ CJK never flagged; skips short tokens/acronyms; exempts the caret word; reuses exported `mapOffset`; `wordAt` for click→span). `MisspellCard`: rose wavy underline, bilingual card with correction pills + add-to-dictionary. tsc/vite/go all clean; live server serves both dict files; nspell behavior smoke-tested. **All v1 phases (0–7) done.** Remaining work is the deferred post-v1 bucket (auth, Copyleaks, deploy). Next: per user — Chinese spell check is out of scope for nspell (en-only); see discussion.
+- 2026-06-25: **Phase 4 complete.** Backend: `internal/llm/chat.go` (`StreamAskPetal` — conversational sampling params, reuses `AskPetalSystemPrompt`/`TrimHistory`), `internal/suggestions/chat.go` (`POST /api/suggestions/:id/chat` — one user-scoped join loads the suggestion + parent `content_text`, `surroundingParagraph` extracts the `\n\n`-bounded paragraph at `from_pos` with whole-doc fallback, streams `event: token`/`event: done` SSE frames with JSON-encoded data, `X-Accel-Buffering: no`, real `http.Flusher` per chunk; LLM-down → 502 before SSE headers, unknown id → 404). Handler imports the interface only. Frontend: `streamSuggestionChat` (fetch + ReadableStream SSE parser, abortable), `AskPetal.tsx` (in-component history — no persistence, pre-seeded first bubble, rose/lavender bubbles, CJK font stack per Note #17, streaming caret), `SuggestionCard` "Ask Petal ✨" pill that pins the card open (hover-close suppressed, click-away closes) and widens it to 340px. Tests: `chat_test.go` (streamed-text concat + done event, server-side context injection asserted on the system message, sampling params, 404, `surroundingParagraph` unit). go build/vet/test clean, tsc clean, vite build OK. Live SSE smoke test against a fake streaming vLLM (fresh ports 8077/8088 — a pre-existing dev petal on :8099 left untouched): tokens flushed individually through the chi middleware stack, `done` terminator, 502 on LLM-down, 404 on unknown suggestion all verified. Next: **Phase 5 (voice consistency pass, Tier 1).**

cmd/server/main.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"errors"
 	"io/fs"
 	"log"
@@ -11,23 +13,100 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 
 	"gitea.parodia.dev/drwily/petal/internal/config"
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/docs"
+	"gitea.parodia.dev/drwily/petal/internal/images"
+	"gitea.parodia.dev/drwily/petal/internal/lexicon"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+	"gitea.parodia.dev/drwily/petal/internal/suggestions"
+	"gitea.parodia.dev/drwily/petal/internal/tts"
+	"gitea.parodia.dev/drwily/petal/internal/vocab"
 	"gitea.parodia.dev/drwily/petal/web"
 )
 
 func main() {
 	cfg := config.Load()
 
+	database, err := db.Open(cfg.DatabasePath)
+	if err != nil {
+		log.Fatalf("database: %v", err)
+	}
+	defer database.Close()
+	log.Printf("database ready at %s", cfg.DatabasePath)
+
 	r := chi.NewRouter()
 	r.Use(middleware.RequestID)
 	r.Use(middleware.RealIP)
 	r.Use(middleware.Logger)
 	r.Use(middleware.Recoverer)
 
+	// Build version: a hash of the embedded SPA shell. Vite rewrites index.html
+	// with content-hashed asset names on every build, so this string changes
+	// exactly when a new frontend is deployed — the client polls it to know when
+	// to offer a refresh.
+	version := buildVersion()
+	log.Printf("frontend build version %s", version)
+
 	r.Route("/api", func(api chi.Router) {
+		// Cap request bodies so a runaway or hostile client can't stream an
+		// unbounded payload into a JSON decoder. Image uploads carry their own
+		// (larger) limit inside the images handler, so they're exempt here.
+		api.Use(limitBody(maxAPIBodyBytes, "/api/images"))
+
 		api.Get("/health", func(w http.ResponseWriter, _ *http.Request) {
 			w.Header().Set("Content-Type", "application/json")
 			_, _ = w.Write([]byte(`{"status":"ok"}`))
 		})
+
+		api.Get("/version", func(w http.ResponseWriter, _ *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			// Never cache: a stale cached version would defeat the whole check.
+			w.Header().Set("Cache-Control", "no-store")
+			_, _ = w.Write([]byte(`{"version":"` + version + `"}`))
+		})
+
+		llmClient := llm.NewLLMClient(cfg)
+		sug := suggestions.New(database, llmClient)
+
+		// Document CRUD plus the doc-scoped checkpoint/list suggestion routes,
+		// both under /api/docs.
+		docsHandler := docs.New(database)
+		docsRouter := docsHandler.Routes()
+		sug.RegisterDocRoutes(docsRouter)
+		api.Mount("/docs", docsRouter)
+
+		// Tag management (the roster) and cross-document full-text search.
+		api.Mount("/tags", docsHandler.TagRoutes())
+		api.Mount("/search", docsHandler.SearchRoutes())
+
+		// Per-suggestion actions (accept/dismiss) under /api/suggestions.
+		api.Mount("/suggestions", sug.Routes())
+
+		// Offline lexicon: full word lookups (gloss + definition + synonyms) for
+		// the right-click popover, and the lightweight Chinese-only gloss for the
+		// inline hover/select tooltip. One handler so the datasets load once.
+		lex := lexicon.NewHandler()
+		api.Mount("/word", lex.Routes())
+		api.Mount("/gloss", lex.GlossRoutes())
+
+		// Vocabulary garden: words the writer looks up are captured here and
+		// surfaced for gentle spaced-repetition review.
+		api.Mount("/vocab", vocab.New(database).Routes())
+
+		// Editor image uploads, stored on disk and served back by content hash.
+		imgHandler, err := images.New(cfg.ImageDir)
+		if err != nil {
+			log.Fatalf("image store: %v", err)
+		}
+		api.Mount("/images", imgHandler.Routes())
+
+		// Read-aloud: proxy short passages to a local Piper TTS server. Only
+		// mounted when TTS_ENDPOINT is configured; otherwise the frontend falls
+		// back to the browser's Web Speech API on its own.
+		if ttsHandler, ok := tts.New(cfg); ok {
+			api.Mount("/tts", ttsHandler.Routes())
+			log.Printf("read-aloud enabled (TTS endpoint=%s)", cfg.TTSEndpoint)
+		}
 	})
 
 	// Everything else: serve the embedded SPA (with index.html fallback for client routing).
@@ -40,6 +119,45 @@ func main() {
 	}
 }
 
+// maxAPIBodyBytes caps a JSON API request body at 2 MiB. That's far above any
+// real document save (the body is text plus lightweight marks; images upload
+// separately by reference) while still bounding abuse. Exceeding it makes the
+// handler's json.Decode fail, which surfaces as a 400.
+const maxAPIBodyBytes = 2 << 20
+
+// limitBody wraps each request body in an http.MaxBytesReader so handlers can't
+// be made to read an unbounded payload. Paths under any of exemptPrefixes are
+// left alone (e.g. image uploads, which set their own, larger limit).
+func limitBody(max int64, exemptPrefixes ...string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			for _, p := range exemptPrefixes {
+				if strings.HasPrefix(r.URL.Path, p) {
+					next.ServeHTTP(w, r)
+					return
+				}
+			}
+			if r.Body != nil {
+				r.Body = http.MaxBytesReader(w, r.Body, max)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// buildVersion derives a short, stable identifier for the currently embedded
+// frontend by hashing dist/index.html. Vite stamps content-hashed asset names
+// into that file each build, so the digest is a reliable "did the deploy
+// change?" signal. Falls back to "dev" when the frontend hasn't been built.
+func buildVersion() string {
+	data, err := fs.ReadFile(web.DistFS, "dist/index.html")
+	if err != nil {
+		return "dev"
+	}
+	sum := sha256.Sum256(data)
+	return hex.EncodeToString(sum[:])[:12]
+}
+
 // spaHandler serves the embedded web/dist as a single-page app: static files
 // when they exist, falling back to index.html for unknown paths. If the
 // frontend hasn't been built yet, it returns a friendly dev hint instead.

deploy/README.md

@@ -0,0 +1,65 @@
+# Deploying read-aloud (Piper TTS) to millenia
+
+Petal's read-aloud generates audio with a local **Piper** neural-TTS server and
+transcodes it to mp3 with **ffmpeg**. Both run on millenia (192.168.1.212);
+nothing leaves the box. If Piper is down or `TTS_ENDPOINT` is unset, the frontend
+falls back to the browser's Web Speech API automatically.
+
+## 1. Piper as a systemd service (one-time)
+
+```bash
+# from this repo, on your workstation:
+scp deploy/piper.service deploy/setup-piper.sh 192.168.1.212:/tmp/
+ssh 192.168.1.212 'cd /tmp && sudo ./setup-piper.sh'
+```
+
+`setup-piper.sh` creates `~/piper/venv`, installs `piper-tts[http]`, downloads the
+`en_US-amy-medium` voice into `~/piper/voices`, installs+enables `piper.service`
+(loopback :5005), and smoke-tests it. Idempotent.
+
+Check it any time: `systemctl status piper`, `journalctl -u piper -f`.
+
+## 2. Point petal at Piper + redeploy the binary
+
+Add to petal's environment (its `.env` or launch env):
+
+```
+TTS_ENDPOINT=http://127.0.0.1:5005
+TTS_VOICE_EN=en_US-amy-medium
+TTS_AUDIO_FORMAT=mp3
+```
+
+Then ship the rebuilt binary (`go build -o petal ./cmd/server` already done) and
+restart the petal `:8088` session. Confirm the log line:
+`read-aloud enabled (TTS endpoint=http://127.0.0.1:5005)`.
+
+## 3. Verify
+
+```bash
+# on millenia — end-to-end through petal, including ffmpeg transcode:
+curl -sf -X POST localhost:8088/api/tts \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"hello there","lang":"en-US"}' -o /tmp/petal-tts.mp3 \
+  && file /tmp/petal-tts.mp3   # expect: Audio file ... MPEG ... layer III
+```
+
+- Second identical call is served from the cache (`~/petal/.../data/tts/*.mp3`).
+- A language with no configured instance returns 404 → client uses Web Speech.
+- Browser check via the uitest harness (`~/petal/uitest`): tap a word in the
+  WordCard / select a sentence and hit speak — expect the natural Piper voice.
+
+## Chinese voice (live)
+
+Each Piper HTTP server loads ONE model, so Chinese runs as a **second instance**:
+`piper-zh.service` on :5006 with `zh_CN-huayan-medium`. Deployed via:
+
+```bash
+scp deploy/piper-zh.service 192.168.1.212:~/.config/systemd/user/
+ssh 192.168.1.212 'export XDG_RUNTIME_DIR=/run/user/$(id -u)
+  ~/piper/venv/bin/python -m piper.download_voices zh_CN-huayan-medium --data-dir ~/piper/voices
+  systemctl --user daemon-reload && systemctl --user enable --now piper-zh.service'
+```
+
+Then in petal's `start.sh`: `TTS_ENDPOINT_ZH=http://127.0.0.1:5006` and
+`TTS_VOICE_ZH=zh_CN-huayan-medium`. The handler maps language → instance from config,
+so adding more languages is just another instance + env pair (no code change).

deploy/piper-zh.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Piper TTS HTTP server — Chinese voice (read-aloud backend for petal)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# Bound to loopback only — petal proxies to it; never exposed off-box.
+ExecStart=%h/piper/venv/bin/python -m piper.http_server \
+  -m zh_CN-huayan-medium \
+  --data-dir %h/piper/voices \
+  --host 127.0.0.1 --port 5006
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=default.target

deploy/piper.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Piper TTS HTTP server (read-aloud backend for petal)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# Bound to loopback only — petal proxies to it; never exposed off-box.
+ExecStart=%h/piper/venv/bin/python -m piper.http_server \
+  -m en_US-amy-medium \
+  --data-dir %h/piper/voices \
+  --host 127.0.0.1 --port 5005
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=default.target

deploy/setup-piper.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# One-time Piper TTS setup on millenia as a *user* systemd service (no sudo).
+# Idempotent — safe to re-run. Run on the box:
+#   bash setup-piper.sh
+# To survive logout/reboot, also (once, needs root):
+#   sudo loginctl enable-linger "$USER"
+set -euo pipefail
+
+PIPER_HOME="$HOME/piper"
+VENV="$PIPER_HOME/venv"
+VOICES="$PIPER_HOME/voices"
+VOICE=en_US-amy-medium
+UNIT_DIR="$HOME/.config/systemd/user"
+export XDG_RUNTIME_DIR="/run/user/$(id -u)"
+
+echo ">> ffmpeg check (petal transcodes Piper WAV -> mp3 with it):"
+command -v ffmpeg >/dev/null || { echo "ffmpeg not found on PATH"; exit 1; }
+
+echo ">> venv + piper-tts[http]"
+[ -d "$VENV" ] || python3 -m venv "$VENV"
+"$VENV/bin/pip" install --upgrade pip >/dev/null
+"$VENV/bin/pip" install "piper-tts[http]"
+
+echo ">> download voice $VOICE"
+mkdir -p "$VOICES"
+"$VENV/bin/python" -m piper.download_voices "$VOICE" --data-dir "$VOICES"
+
+echo ">> install user service"
+mkdir -p "$UNIT_DIR"
+install -m 0644 "$(dirname "$0")/piper.service" "$UNIT_DIR/piper.service"
+systemctl --user daemon-reload
+systemctl --user enable --now piper.service
+
+echo ">> wait + status"
+sleep 2
+systemctl --user --no-pager --full status piper.service | head -n 6 || true
+
+echo ">> smoke test"
+curl -sf -X POST localhost:5005/ \
+  -H 'Content-Type: application/json' \
+  -d "{\"text\":\"hello there\",\"voice\":\"$VOICE\"}" -o /tmp/piper-test.wav \
+  && echo "OK: /tmp/piper-test.wav ($(stat -c%s /tmp/piper-test.wav) bytes)" \
+  || { echo "smoke test FAILED"; journalctl --user -u piper.service --no-pager | tail -n 20; exit 1; }

go.mod

@@ -1,5 +1,20 @@
 module gitea.parodia.dev/drwily/petal
 
-go 1.24.4
+go 1.25.0
 
-require github.com/go-chi/chi/v5 v5.3.0
+require (
+	github.com/go-chi/chi/v5 v5.3.0
+	modernc.org/sqlite v1.53.0
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	modernc.org/libc v1.73.4 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+)

go.sum

@@ -1,2 +1,53 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
 github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
+golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
+modernc.org/cc/v4 v4.28.4 h1:Hd/4Es+MBj+/7hSdZaisNyu6bv3V0Dp2MdllyfqaH+c=
+modernc.org/cc/v4 v4.28.4/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.34.4 h1:OVnSOWQjVKOYkFxoHYB+qQmSHK5gqMqARM+K9DpR/Ws=
+modernc.org/ccgo/v4 v4.34.4/go.mod h1:qdKqE8FNIYyysougB1RX9MxCzp5oJOcQXSobANJ4TuE=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.3 h1:6QAplYyVO+KdPW3pGnqmJDUxtkec8ooEWvks/hhU3lc=
+modernc.org/gc/v3 v3.1.3/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.73.4 h1:+ra4Ui8ngyt8HDcO1FTDPWlkAh6yOdaO2yAoh8MddQA=
+modernc.org/libc v1.73.4/go.mod h1:DXZ3eO8qMCNn2SnmTNCiC71nJ9Rcq3PsnpU6Vc4rWK8=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.53.0 h1:20WG8N9q4ji/dEqGk4uiI0c6OPjSeLTNYGFCc3+7c1M=
+modernc.org/sqlite v1.53.0/go.mod h1:xoEpOIpGrgT48H5iiyt/YXPCZPEzlfmfFwtk8Lklw8s=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

internal/config/config.go

@@ -11,6 +11,7 @@ type Config struct {
 	Port         string
 	BaseURL      string
 	DatabasePath string
+	ImageDir     string // on-disk store for editor image uploads
 
 	// LLM
 	LLMBackend   string // "vllm" | "ollama"
@@ -19,6 +20,17 @@ type Config struct {
 	LLMChatModel string // Ask Petal model; falls back to LLMModel if empty
 	LLMTimeout   time.Duration
 
+	// TTS (read-aloud). Off unless TTSEndpoint is set — when empty, the /api/tts
+	// route isn't mounted and the frontend falls back to the browser's Web Speech
+	// API. Endpoint points at a local Piper HTTP server.
+	TTSEndpoint   string // Piper instance serving the English voice
+	TTSEndpointZH string // Piper instance serving the Chinese voice; empty = zh falls back to Web Speech
+	TTSVoiceEN    string // Piper voice id for English (e.g. en_US-amy-medium)
+	TTSVoiceZH    string // Piper voice id for Chinese (e.g. zh_CN-huayan-medium)
+	TTSCacheDir string // on-disk store for synthesized clips (content-addressed)
+	TTSTimeout  time.Duration
+	TTSFormat   string // mp3 | opus | wav — mp3/opus transcode Piper's WAV via ffmpeg
+
 	// Auth (deferred — not wired in the local-dev build, kept for later)
 	AuthentikURL          string
 	AuthentikClientID     string
@@ -32,6 +44,7 @@ func Load() *Config {
 		Port:         env("PORT", "8080"),
 		BaseURL:      env("BASE_URL", "http://localhost:8080"),
 		DatabasePath: env("DATABASE_PATH", "./data/petal.db"),
+		ImageDir:     env("IMAGE_DIR", "./data/images"),
 
 		LLMBackend:   env("LLM_BACKEND", "vllm"),
 		LLMEndpoint:  env("LLM_ENDPOINT", "http://localhost:8000"),
@@ -39,6 +52,14 @@ func Load() *Config {
 		LLMChatModel: env("LLM_CHAT_MODEL", ""),
 		LLMTimeout:   envDuration("LLM_TIMEOUT", 30*time.Second),
 
+		TTSEndpoint:   env("TTS_ENDPOINT", ""),
+		TTSEndpointZH: env("TTS_ENDPOINT_ZH", ""),
+		TTSVoiceEN:    env("TTS_VOICE_EN", "en_US-amy-medium"),
+		TTSVoiceZH:    env("TTS_VOICE_ZH", "zh_CN-huayan-medium"),
+		TTSCacheDir: env("TTS_CACHE_DIR", "./data/tts"),
+		TTSTimeout:  envDuration("TTS_TIMEOUT", 15*time.Second),
+		TTSFormat:   env("TTS_AUDIO_FORMAT", "mp3"),
+
 		AuthentikURL:          env("AUTHENTIK_URL", ""),
 		AuthentikClientID:     env("AUTHENTIK_CLIENT_ID", ""),
 		AuthentikClientSecret: env("AUTHENTIK_CLIENT_SECRET", ""),

internal/db/db.go

@@ -0,0 +1,382 @@
+// Package db owns the SQLite connection, schema migrations, and the core data
+// models. It uses modernc.org/sqlite (pure Go, no cgo) so the app stays a
+// single static binary.
+package db
+
+import (
+	"database/sql"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+
+	_ "modernc.org/sqlite"
+)
+
+// LocalUserID is the id of the single hardcoded user the app runs as while auth
+// is deferred. The seeded row keeps foreign keys valid; real auth replaces it
+// later without a schema change.
+const LocalUserID = "local"
+
+// DB wraps the SQL handle. It's a thin alias today, leaving room for prepared
+// statements or helpers later without churning call sites.
+type DB struct {
+	*sql.DB
+}
+
+// Open initialises the database at path: it ensures the parent directory
+// exists, opens the connection with foreign keys and WAL enabled, runs all
+// pending migrations, and seeds the local user.
+func Open(path string) (*DB, error) {
+	if dir := filepath.Dir(path); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			return nil, fmt.Errorf("create data dir: %w", err)
+		}
+	}
+
+	sqlDB, err := sql.Open("sqlite", dsn(path))
+	if err != nil {
+		return nil, fmt.Errorf("open sqlite: %w", err)
+	}
+	// SQLite is a single writer; one connection avoids "database is locked"
+	// churn while keeping WAL's concurrent readers.
+	sqlDB.SetMaxOpenConns(1)
+
+	if err := sqlDB.Ping(); err != nil {
+		_ = sqlDB.Close()
+		return nil, fmt.Errorf("ping sqlite: %w", err)
+	}
+
+	d := &DB{sqlDB}
+	if err := d.migrate(); err != nil {
+		_ = sqlDB.Close()
+		return nil, fmt.Errorf("migrate: %w", err)
+	}
+	if err := d.seed(); err != nil {
+		_ = sqlDB.Close()
+		return nil, fmt.Errorf("seed: %w", err)
+	}
+	return d, nil
+}
+
+// dsn builds the modernc.org/sqlite connection string with the pragmas we want
+// applied to every connection.
+func dsn(path string) string {
+	q := url.Values{}
+	q.Add("_pragma", "foreign_keys(1)")
+	q.Add("_pragma", "busy_timeout(5000)")
+	q.Add("_pragma", "journal_mode(WAL)")
+	return "file:" + path + "?" + q.Encode()
+}
+
+// migration is one ordered, idempotent schema step. Append new migrations to the
+// slice in migrate(); never edit or reorder an already-shipped one.
+type migration struct {
+	name string
+	stmt string
+}
+
+// migrate runs every migration not yet recorded in schema_migrations, inside a
+// transaction each, in order.
+func (d *DB) migrate() error {
+	if _, err := d.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+		name       TEXT PRIMARY KEY,
+		applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+	)`); err != nil {
+		return err
+	}
+
+	for _, m := range migrations() {
+		var exists bool
+		if err := d.QueryRow(
+			`SELECT EXISTS(SELECT 1 FROM schema_migrations WHERE name = ?)`, m.name,
+		).Scan(&exists); err != nil {
+			return err
+		}
+		if exists {
+			continue
+		}
+
+		tx, err := d.Begin()
+		if err != nil {
+			return err
+		}
+		if _, err := tx.Exec(m.stmt); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("migration %q: %w", m.name, err)
+		}
+		if _, err := tx.Exec(`INSERT INTO schema_migrations (name) VALUES (?)`, m.name); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("record migration %q: %w", m.name, err)
+		}
+		if err := tx.Commit(); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// migrations returns the ordered schema history. The initial migration mirrors
+// the schema in petal-spec.md.
+func migrations() []migration {
+	return []migration{
+		{
+			name: "0001_initial_schema",
+			stmt: `
+CREATE TABLE users (
+    id           TEXT PRIMARY KEY,
+    email        TEXT NOT NULL,
+    display_name TEXT,
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE documents (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    user_id      TEXT NOT NULL REFERENCES users(id),
+    title        TEXT NOT NULL DEFAULT 'Untitled',
+    content      TEXT NOT NULL DEFAULT '{}',
+    content_text TEXT NOT NULL DEFAULT '',
+    word_count   INTEGER NOT NULL DEFAULT 0,
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE suggestions (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    from_pos     INTEGER NOT NULL,
+    to_pos       INTEGER NOT NULL,
+    original     TEXT NOT NULL,
+    replacement  TEXT NOT NULL,
+    explanation  TEXT NOT NULL,
+    type         TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice')),
+    status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')),
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE plagiarism_reports (
+    id              TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id          TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    backend         TEXT NOT NULL DEFAULT 'copyleaks',
+    similarity_pct  REAL,
+    status          TEXT NOT NULL DEFAULT 'pending'
+                    CHECK(status IN ('pending','complete','error')),
+    result_json     TEXT,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
+CREATE INDEX idx_plagiarism_doc_id ON plagiarism_reports(doc_id);
+`,
+		},
+		{
+			// Per-document tone: guides the grammar-checkpoint LLM so advice fits
+			// the writer's target register (academic essay vs casual journal).
+			// 'general' means no specific tone steering.
+			name: "0002_document_tone",
+			stmt: `ALTER TABLE documents ADD COLUMN tone TEXT NOT NULL DEFAULT 'general';`,
+		},
+		{
+			// Version history: point-in-time snapshots of a document's body so a
+			// bad edit or LLM mishap is always recoverable. `kind` distinguishes
+			// throttled background snapshots ('auto'), explicit user restore
+			// points ('manual'), and the safety copy taken right before a restore
+			// ('pre_restore') so restoring is itself undoable. Snapshots cascade
+			// with the document. Stored fully (content + content_text) so a
+			// restore is a plain copy with no re-derivation.
+			name: "0003_document_versions",
+			stmt: `
+CREATE TABLE document_versions (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    title        TEXT NOT NULL,
+    content      TEXT NOT NULL,
+    content_text TEXT NOT NULL,
+    word_count   INTEGER NOT NULL DEFAULT 0,
+    kind         TEXT NOT NULL DEFAULT 'auto'
+                 CHECK(kind IN ('auto','manual','pre_restore')),
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_versions_doc_id ON document_versions(doc_id, created_at DESC);
+`,
+		},
+		{
+			// Organization & search (Phase 10). Two parts:
+			//
+			// 1. Tags. A small, user-scoped label set; `color` holds a palette key
+			//    (rose/mint/peach/lavender/sky/honey) the frontend maps to CSS.
+			//    document_tags is the many-to-many join; both sides cascade so
+			//    deleting a doc or a tag cleans up its assignments.
+			//
+			// 2. Full-text search. A standalone FTS5 virtual table over title +
+			//    content_text using the `trigram` tokenizer so search works for
+			//    both English and space-free Chinese (the default tokenizer treats a
+			//    CJK run as one token). It carries an UNINDEXED doc_id to map hits
+			//    back to documents, kept in sync by AFTER INSERT/UPDATE/DELETE
+			//    triggers, and is back-filled from the existing documents here.
+			//    (Trigram needs ≥3 chars to MATCH; the search handler falls back to
+			//    LIKE for shorter queries — common for 2-character Chinese words.)
+			name: "0004_tags_and_search",
+			stmt: `
+CREATE TABLE tags (
+    id         TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    user_id    TEXT NOT NULL REFERENCES users(id),
+    name       TEXT NOT NULL,
+    color      TEXT NOT NULL DEFAULT 'rose',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(user_id, name)
+);
+
+CREATE TABLE document_tags (
+    doc_id  TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    tag_id  TEXT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (doc_id, tag_id)
+);
+
+CREATE INDEX idx_document_tags_tag ON document_tags(tag_id);
+
+CREATE VIRTUAL TABLE documents_fts USING fts5(
+    doc_id UNINDEXED,
+    title,
+    content_text,
+    tokenize='trigram'
+);
+
+CREATE TRIGGER documents_ai AFTER INSERT ON documents BEGIN
+    INSERT INTO documents_fts (doc_id, title, content_text)
+    VALUES (new.id, new.title, new.content_text);
+END;
+
+CREATE TRIGGER documents_ad AFTER DELETE ON documents BEGIN
+    DELETE FROM documents_fts WHERE doc_id = old.id;
+END;
+
+CREATE TRIGGER documents_au AFTER UPDATE ON documents BEGIN
+    UPDATE documents_fts
+       SET title = new.title, content_text = new.content_text
+     WHERE doc_id = old.id;
+END;
+
+INSERT INTO documents_fts (doc_id, title, content_text)
+SELECT id, title, content_text FROM documents;
+`,
+		},
+		{
+			// Collocation coach (Phase 12). Adds a third suggestion family,
+			// 'collocation', for gentle "natives usually say…" hints on
+			// non-native word pairings. The `type` column carries a CHECK
+			// constraint and SQLite cannot ALTER one in place, so we rebuild the
+			// suggestions table with the extended CHECK, copy every row across,
+			// and recreate its index. Nothing references suggestions, so dropping
+			// the old table is safe; the new table keeps the same ON DELETE
+			// CASCADE to documents.
+			name: "0005_collocation_suggestion_type",
+			stmt: `
+CREATE TABLE suggestions_new (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    from_pos     INTEGER NOT NULL,
+    to_pos       INTEGER NOT NULL,
+    original     TEXT NOT NULL,
+    replacement  TEXT NOT NULL,
+    explanation  TEXT NOT NULL,
+    type         TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice','collocation')),
+    status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')),
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO suggestions_new (id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at)
+SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at FROM suggestions;
+
+DROP TABLE suggestions;
+ALTER TABLE suggestions_new RENAME TO suggestions;
+CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
+`,
+		},
+		{
+			// Vocabulary garden (Phase 13). Every word the writer looks up is
+			// captured here and put on a gentle spaced-repetition schedule, turning
+			// passive lookups into real vocabulary. `example` holds the sentence the
+			// word appeared in (captured at lookup) for context during review;
+			// `doc_id` links back to where she met the word (nulled if that doc is
+			// deleted — the word stays in the garden). The SM-2-lite scheduling
+			// columns (due_at/interval_days/ease/reps/lapses/last_reviewed) drive a
+			// Leitner-style ladder (see internal/vocab/scheduler.go). UNIQUE on
+			// (user_id, word) makes capture an idempotent upsert.
+			name: "0006_vocab_garden",
+			stmt: `
+CREATE TABLE vocab_words (
+    id            TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    user_id       TEXT NOT NULL REFERENCES users(id),
+    word          TEXT NOT NULL,
+    gloss         TEXT NOT NULL DEFAULT '',
+    phonetic      TEXT NOT NULL DEFAULT '',
+    example       TEXT NOT NULL DEFAULT '',
+    doc_id        TEXT REFERENCES documents(id) ON DELETE SET NULL,
+    due_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    interval_days INTEGER NOT NULL DEFAULT 0,
+    ease          REAL NOT NULL DEFAULT 2.5,
+    reps          INTEGER NOT NULL DEFAULT 0,
+    lapses        INTEGER NOT NULL DEFAULT 0,
+    last_reviewed DATETIME,
+    created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(user_id, word)
+);
+
+CREATE INDEX idx_vocab_due ON vocab_words(user_id, due_at);
+`,
+		},
+		{
+			// Vocabulary garden, follow-up. Some looked-up words have an English
+			// definition but no Chinese gloss; those produced an unanswerable review
+			// card (review reveals only the gloss). `definition` stores a short
+			// English sense captured at lookup as a fallback "meaning" so such words
+			// are still reviewable.
+			name: "0007_vocab_definition",
+			stmt: `
+ALTER TABLE vocab_words ADD COLUMN definition TEXT NOT NULL DEFAULT '';
+`,
+		},
+		{
+			// Deterministic mechanics pass. Adds a 'mechanics' suggestion family for
+			// rule-based fixes (doubled words, spacing/punctuation, lowercase "i",
+			// curated confusables) detected in pure Go — no LLM. As with 0005, the
+			// `type` CHECK can't be ALTERed in place, so rebuild the table with the
+			// extended constraint, copy every row across, and recreate the index.
+			name: "0008_mechanics_suggestion_type",
+			stmt: `
+CREATE TABLE suggestions_new (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    from_pos     INTEGER NOT NULL,
+    to_pos       INTEGER NOT NULL,
+    original     TEXT NOT NULL,
+    replacement  TEXT NOT NULL,
+    explanation  TEXT NOT NULL,
+    type         TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice','collocation','mechanics')),
+    status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')),
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO suggestions_new (id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at)
+SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at FROM suggestions;
+
+DROP TABLE suggestions;
+ALTER TABLE suggestions_new RENAME TO suggestions;
+CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
+`,
+		},
+	}
+}
+
+// seed inserts the hardcoded local user if it doesn't already exist. It's
+// idempotent, so it runs safely on every startup.
+func (d *DB) seed() error {
+	_, err := d.Exec(
+		`INSERT INTO users (id, email, display_name) VALUES (?, ?, ?)
+		 ON CONFLICT(id) DO NOTHING`,
+		LocalUserID, "local@petal.local", "Writer",
+	)
+	return err
+}

internal/db/db_test.go

@@ -0,0 +1,85 @@
+package db
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestOpenMigratesAndSeeds(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "test.db")
+
+	d, err := Open(path)
+	if err != nil {
+		t.Fatalf("first open: %v", err)
+	}
+
+	// Local user is seeded.
+	var email string
+	if err := d.QueryRow(`SELECT email FROM users WHERE id = ?`, LocalUserID).Scan(&email); err != nil {
+		t.Fatalf("local user not seeded: %v", err)
+	}
+
+	// All expected tables exist.
+	for _, table := range []string{"users", "documents", "suggestions", "plagiarism_reports", "schema_migrations"} {
+		var name string
+		err := d.QueryRow(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, table).Scan(&name)
+		if err != nil {
+			t.Errorf("table %q missing: %v", table, err)
+		}
+	}
+
+	// The voice suggestion type is permitted by the CHECK constraint.
+	if _, err := d.Exec(`INSERT INTO documents (id, user_id) VALUES ('d1', ?)`, LocalUserID); err != nil {
+		t.Fatalf("insert document: %v", err)
+	}
+	if _, err := d.Exec(
+		`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+		 VALUES ('d1', 0, 4, 'teh', '', 'voice flag', 'voice')`,
+	); err != nil {
+		t.Fatalf("insert voice suggestion: %v", err)
+	}
+
+	// The collocation type (added by migration 0005's table rebuild) is permitted.
+	if _, err := d.Exec(
+		`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+		 VALUES ('d1', 0, 9, 'do a decision', 'make a decision', 'natives usually say…', 'collocation')`,
+	); err != nil {
+		t.Fatalf("insert collocation suggestion: %v", err)
+	}
+
+	// An invalid type is rejected.
+	if _, err := d.Exec(
+		`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+		 VALUES ('d1', 0, 4, 'teh', 'the', 'x', 'nonsense')`,
+	); err == nil {
+		t.Error("expected CHECK constraint to reject invalid suggestion type")
+	}
+
+	// Cascade delete removes child suggestions (foreign keys enabled).
+	if _, err := d.Exec(`DELETE FROM documents WHERE id = 'd1'`); err != nil {
+		t.Fatalf("delete document: %v", err)
+	}
+	var n int
+	if err := d.QueryRow(`SELECT COUNT(*) FROM suggestions WHERE doc_id = 'd1'`).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	if n != 0 {
+		t.Errorf("expected cascade delete, got %d orphan suggestions", n)
+	}
+	d.Close()
+
+	// Re-opening is idempotent: migrations and seed don't double-apply or error.
+	d2, err := Open(path)
+	if err != nil {
+		t.Fatalf("second open: %v", err)
+	}
+	defer d2.Close()
+
+	var users int
+	if err := d2.QueryRow(`SELECT COUNT(*) FROM users WHERE id = ?`, LocalUserID).Scan(&users); err != nil {
+		t.Fatal(err)
+	}
+	if users != 1 {
+		t.Errorf("expected exactly 1 local user after reopen, got %d", users)
+	}
+}

internal/db/models.go

@@ -0,0 +1,109 @@
+package db
+
+import "time"
+
+// User is an account. With auth deferred, the app runs as a single hardcoded
+// `local` user (see LocalUserID); the user_id columns and this type exist so
+// real auth can drop in later without a schema migration.
+type User struct {
+	ID          string    `json:"id"`
+	Email       string    `json:"email"`
+	DisplayName string    `json:"display_name"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+// Document is a single piece of writing. `Content` is the Tiptap JSON document
+// (source of truth for the editor); `ContentText` is the flattened plain text
+// kept in sync on every save and fed to the LLM.
+type Document struct {
+	ID          string    `json:"id"`
+	UserID      string    `json:"user_id"`
+	Title       string    `json:"title"`
+	Content     string    `json:"content"`      // Tiptap JSON
+	ContentText string    `json:"content_text"` // plain text for the LLM
+	Tone        string    `json:"tone"`         // target writing tone; steers LLM advice
+	WordCount   int       `json:"word_count"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+}
+
+// DocumentVersion is a point-in-time snapshot of a document's body, captured so
+// a writer can recover from a bad edit or an unwanted change. `Content` mirrors
+// the document's Tiptap JSON at snapshot time; `Kind` records why it was taken
+// (see the kind constants). List responses omit the heavy Content/ContentText
+// fields (the `omitempty`-friendly zero strings) and load them only on preview
+// or restore.
+type DocumentVersion struct {
+	ID          string    `json:"id"`
+	DocID       string    `json:"doc_id"`
+	Title       string    `json:"title"`
+	Content     string    `json:"content,omitempty"`      // Tiptap JSON; omitted in list view
+	ContentText string    `json:"content_text,omitempty"` // plain text; omitted in list view
+	WordCount   int       `json:"word_count"`
+	Kind        string    `json:"kind"` // auto | manual | pre_restore
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+// Document version kinds, mirrored from the schema CHECK constraint.
+const (
+	VersionKindAuto       = "auto"        // throttled background snapshot on save
+	VersionKindManual     = "manual"      // explicit "save a restore point"
+	VersionKindPreRestore = "pre_restore" // safety copy taken just before a restore
+)
+
+// Tag is a user-scoped label for organizing documents. `Color` is a palette key
+// (rose, mint, peach, lavender, sky, honey) the frontend maps to a CSS color;
+// storing the key (not a hex value) keeps tags in step with the design tokens.
+// `DocCount` is populated only by the tag-list endpoint (how many documents wear
+// the tag); it's omitted from per-document tag lists.
+type Tag struct {
+	ID       string `json:"id"`
+	Name     string `json:"name"`
+	Color    string `json:"color"`
+	DocCount int    `json:"doc_count,omitempty"`
+}
+
+// Tag color palette keys, mirrored on the frontend. Kept small and aligned with
+// the existing design tokens; unknown values fall back to rose client-side.
+const (
+	TagColorRose     = "rose"
+	TagColorMint     = "mint"
+	TagColorPeach    = "peach"
+	TagColorLavender = "lavender"
+	TagColorSky      = "sky"
+	TagColorHoney    = "honey"
+)
+
+// Suggestion is a single LLM-proposed edit anchored to a span of the document.
+//
+// FromPos/ToPos are plaintext offsets into ContentText for server-side use only;
+// the frontend re-anchors by matching the `Original` string in ProseMirror
+// coordinates at render time (spec Note #6). `Replacement` is empty for `voice`
+// flags — those are awareness-only, with no correction to apply.
+type Suggestion struct {
+	ID          string    `json:"id"`
+	DocID       string    `json:"doc_id"`
+	FromPos     int       `json:"from_pos"`
+	ToPos       int       `json:"to_pos"`
+	Original    string    `json:"original"`
+	Replacement string    `json:"replacement"`
+	Explanation string    `json:"explanation"`
+	Type        string    `json:"type"`   // grammar | phrasing | idiom | clarity | voice | collocation
+	Status      string    `json:"status"` // pending | accepted | rejected
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+// Suggestion type and status values, mirrored from the schema CHECK constraints.
+const (
+	SuggestionTypeGrammar     = "grammar"
+	SuggestionTypePhrasing    = "phrasing"
+	SuggestionTypeIdiom       = "idiom"
+	SuggestionTypeClarity     = "clarity"
+	SuggestionTypeVoice       = "voice"
+	SuggestionTypeCollocation = "collocation"
+	SuggestionTypeMechanics   = "mechanics" // deterministic rule-based pass (no LLM)
+
+	SuggestionStatusPending  = "pending"
+	SuggestionStatusAccepted = "accepted"
+	SuggestionStatusRejected = "rejected"
+)

internal/docs/export.go

@@ -0,0 +1,901 @@
+package docs
+
+import (
+	"archive/zip"
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// exportRoutes registers the download endpoints: one document
+// (GET /api/docs/{id}/export?format=…) and a whole-corpus backup zip
+// (GET /api/docs/export-all?format=…). The static "export-all" segment takes
+// priority over the {id} param in chi's router, so the two don't collide.
+func (h *Handler) exportRoutes(r chi.Router) {
+	r.Get("/{id}/export", h.export)
+	r.Get("/export-all", h.exportAll)
+}
+
+// exportAll streams every document the user owns, each rendered in the requested
+// format, bundled into a single zip — a one-click "download all my writing"
+// backup. Per-doc version history guards against bad edits; this guards against
+// a lost disk. Reuses the same renderers as the single-document export.
+func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) {
+	formatKey := r.URL.Query().Get("format")
+	if formatKey == "" {
+		formatKey = "md"
+	}
+	format, ok := exportFormats[formatKey]
+	if !ok {
+		badRequest(w, "unsupported export format")
+		return
+	}
+
+	rows, err := h.DB.Query(
+		`SELECT id, user_id, title, content, content_text, tone, word_count, created_at, updated_at
+		   FROM documents
+		  WHERE user_id = ?
+		  ORDER BY updated_at DESC`,
+		db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	seen := map[string]int{} // de-duplicate filenames from same-titled docs
+	for rows.Next() {
+		var doc db.Document
+		if err := rows.Scan(
+			&doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText,
+			&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
+		); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		body, err := format.render(doc)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		base := sanitizeFilename(doc.Title)
+		if base == "" {
+			base = "untitled"
+		}
+		key := base + "." + format.ext
+		name := key
+		if c := seen[key]; c > 0 {
+			name = fmt.Sprintf("%s (%d).%s", base, c, format.ext)
+		}
+		seen[key]++
+		f, err := zw.Create(name)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		if _, err := f.Write(body); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if err := zw.Close(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	filename := "petal-backup-" + time.Now().Format("2006-01-02") + ".zip"
+	w.Header().Set("Content-Type", "application/zip")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename*=UTF-8''%s", urlEscapeFilename(filename)))
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", buf.Len()))
+	_, _ = w.Write(buf.Bytes())
+}
+
+// exportFormat describes one downloadable format: how to render it and how to
+// label the resulting file.
+type exportFormat struct {
+	ext         string
+	contentType string
+	render      func(doc db.Document) ([]byte, error)
+}
+
+// exportFormats is the supported set. PDF is intentionally absent: a faithful,
+// CJK-safe PDF needs an embedded Unicode font (~10MB into the single binary) or
+// a headless browser (breaks the no-cgo, single-binary story). The frontend
+// offers "Print / Save as PDF" via the browser instead, which uses the reader's
+// own fonts and renders CJK correctly for free.
+var exportFormats = map[string]exportFormat{
+	"md":   {ext: "md", contentType: "text/markdown; charset=utf-8", render: renderMarkdown},
+	"html": {ext: "html", contentType: "text/html; charset=utf-8", render: renderHTMLFile},
+	"txt":  {ext: "txt", contentType: "text/plain; charset=utf-8", render: renderPlainText},
+	"docx": {
+		ext:         "docx",
+		contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		render:      renderDocx,
+	},
+}
+
+// export streams the document in the requested format as a download.
+func (h *Handler) export(w http.ResponseWriter, r *http.Request) {
+	formatKey := r.URL.Query().Get("format")
+	if formatKey == "" {
+		formatKey = "md"
+	}
+	format, ok := exportFormats[formatKey]
+	if !ok {
+		badRequest(w, "unsupported export format")
+		return
+	}
+
+	doc, err := h.fetch(chi.URLParam(r, "id"))
+	if errors.Is(err, sql.ErrNoRows) {
+		notFound(w)
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	body, err := format.render(doc)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	filename := sanitizeFilename(doc.Title) + "." + format.ext
+	w.Header().Set("Content-Type", format.contentType)
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename*=UTF-8''%s", urlEscapeFilename(filename)))
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", len(body)))
+	_, _ = w.Write(body)
+}
+
+// --- Tiptap document model --------------------------------------------------
+
+// pmNode is one ProseMirror/Tiptap node. The tree is what the editor stores in
+// Document.Content; we walk it to render every export format from one source.
+type pmNode struct {
+	Type    string         `json:"type"`
+	Attrs   map[string]any `json:"attrs"`
+	Marks   []pmMark       `json:"marks"`
+	Text    string         `json:"text"`
+	Content []pmNode       `json:"content"`
+}
+
+type pmMark struct {
+	Type  string         `json:"type"`
+	Attrs map[string]any `json:"attrs"`
+}
+
+// parseDoc decodes Document.Content into a node tree. On empty or malformed JSON
+// it falls back to wrapping the plain-text mirror in paragraphs, so export never
+// fails just because the editor state is unusual.
+func parseDoc(doc db.Document) pmNode {
+	var root pmNode
+	if err := json.Unmarshal([]byte(doc.Content), &root); err != nil || root.Type == "" {
+		return fallbackDoc(doc.ContentText)
+	}
+	if len(root.Content) == 0 && strings.TrimSpace(doc.ContentText) != "" {
+		return fallbackDoc(doc.ContentText)
+	}
+	return root
+}
+
+// fallbackDoc builds a minimal doc node from plain text, one paragraph per line.
+func fallbackDoc(text string) pmNode {
+	root := pmNode{Type: "doc"}
+	for _, line := range strings.Split(text, "\n") {
+		p := pmNode{Type: "paragraph"}
+		if line != "" {
+			p.Content = []pmNode{{Type: "text", Text: line}}
+		}
+		root.Content = append(root.Content, p)
+	}
+	return root
+}
+
+func (n pmNode) hasMark(t string) bool {
+	for _, m := range n.Marks {
+		if m.Type == t {
+			return true
+		}
+	}
+	return false
+}
+
+// attrStr returns a string-valued attribute (e.g. an image src), or "".
+func (n pmNode) attrStr(key string) string {
+	if n.Attrs == nil {
+		return ""
+	}
+	if s, ok := n.Attrs[key].(string); ok {
+		return s
+	}
+	return ""
+}
+
+// markAttr returns a string attribute from the named mark (e.g. a link href).
+func (n pmNode) markAttr(markType, key string) string {
+	for _, m := range n.Marks {
+		if m.Type == markType && m.Attrs != nil {
+			if s, ok := m.Attrs[key].(string); ok {
+				return s
+			}
+		}
+	}
+	return ""
+}
+
+func (n pmNode) level() int {
+	if n.Attrs == nil {
+		return 1
+	}
+	if l, ok := n.Attrs["level"].(float64); ok && l >= 1 {
+		return int(l)
+	}
+	return 1
+}
+
+// --- Markdown ---------------------------------------------------------------
+
+func renderMarkdown(doc db.Document) ([]byte, error) {
+	root := parseDoc(doc)
+	var blocks []string
+	for _, child := range root.Content {
+		if s := mdBlock(child, 0); s != "" {
+			blocks = append(blocks, s)
+		}
+	}
+	out := "# " + doc.Title + "\n\n" + strings.Join(blocks, "\n\n") + "\n"
+	return []byte(out), nil
+}
+
+func mdBlock(n pmNode, depth int) string {
+	switch n.Type {
+	case "heading":
+		return strings.Repeat("#", n.level()) + " " + mdInline(n.Content)
+	case "paragraph":
+		return mdInline(n.Content)
+	case "blockquote":
+		var lines []string
+		for _, c := range n.Content {
+			for _, l := range strings.Split(mdBlock(c, depth), "\n") {
+				lines = append(lines, "> "+l)
+			}
+		}
+		return strings.Join(lines, "\n")
+	case "codeBlock":
+		return "```\n" + textContent(n) + "\n```"
+	case "horizontalRule":
+		return "---"
+	case "image":
+		alt := n.attrStr("alt")
+		return fmt.Sprintf("![%s](%s)", alt, n.attrStr("src"))
+	case "table":
+		return mdTable(n)
+	case "bulletList", "orderedList":
+		var items []string
+		for i, item := range n.Content {
+			marker := "- "
+			if n.Type == "orderedList" {
+				marker = fmt.Sprintf("%d. ", i+1)
+			}
+			indent := strings.Repeat("  ", depth)
+			// A listItem holds block children (usually one paragraph).
+			var parts []string
+			for _, c := range item.Content {
+				parts = append(parts, mdBlock(c, depth+1))
+			}
+			items = append(items, indent+marker+strings.TrimSpace(strings.Join(parts, "\n")))
+		}
+		return strings.Join(items, "\n")
+	default:
+		// Unknown block: render any inline text it carries.
+		if len(n.Content) > 0 {
+			return mdInline(n.Content)
+		}
+		return ""
+	}
+}
+
+func mdInline(nodes []pmNode) string {
+	var b strings.Builder
+	for _, n := range nodes {
+		switch n.Type {
+		case "text":
+			b.WriteString(applyMdMarks(n))
+		case "hardBreak":
+			b.WriteString("  \n")
+		default:
+			b.WriteString(mdInline(n.Content))
+		}
+	}
+	return b.String()
+}
+
+// mdTable renders a table node as a GitHub-flavored Markdown table. The first
+// row is used as the header (Markdown tables require one); a separator row is
+// inserted after it. Cell text is flattened to inline Markdown.
+func mdTable(n pmNode) string {
+	var rows [][]string
+	for _, row := range n.Content {
+		if row.Type != "tableRow" {
+			continue
+		}
+		var cells []string
+		for _, cell := range row.Content {
+			// A cell holds block children (usually one paragraph); flatten them.
+			var parts []string
+			for _, c := range cell.Content {
+				parts = append(parts, mdInline(c.Content))
+			}
+			// Escape pipes so cell content doesn't break the column layout.
+			cells = append(cells, strings.ReplaceAll(strings.TrimSpace(strings.Join(parts, " ")), "|", "\\|"))
+		}
+		rows = append(rows, cells)
+	}
+	if len(rows) == 0 {
+		return ""
+	}
+	cols := 0
+	for _, r := range rows {
+		if len(r) > cols {
+			cols = len(r)
+		}
+	}
+	pad := func(r []string) string {
+		for len(r) < cols {
+			r = append(r, "")
+		}
+		return "| " + strings.Join(r, " | ") + " |"
+	}
+	var lines []string
+	lines = append(lines, pad(rows[0]))
+	sep := make([]string, cols)
+	for i := range sep {
+		sep[i] = "---"
+	}
+	lines = append(lines, "| "+strings.Join(sep, " | ")+" |")
+	for _, r := range rows[1:] {
+		lines = append(lines, pad(r))
+	}
+	return strings.Join(lines, "\n")
+}
+
+func applyMdMarks(n pmNode) string {
+	t := n.Text
+	if n.hasMark("code") {
+		return "`" + t + "`" // code spans don't combine with other emphasis
+	}
+	if n.hasMark("bold") {
+		t = "**" + t + "**"
+	}
+	if n.hasMark("italic") {
+		t = "*" + t + "*"
+	}
+	if n.hasMark("strike") {
+		t = "~~" + t + "~~"
+	}
+	if n.hasMark("underline") {
+		t = "<u>" + t + "</u>"
+	}
+	if href := n.markAttr("link", "href"); href != "" {
+		t = "[" + t + "](" + href + ")"
+	}
+	return t
+}
+
+// --- Plain text -------------------------------------------------------------
+
+func renderPlainText(doc db.Document) ([]byte, error) {
+	root := parseDoc(doc)
+	var blocks []string
+	for _, child := range root.Content {
+		if s := txtBlock(child); s != "" {
+			blocks = append(blocks, s)
+		}
+	}
+	out := doc.Title + "\n\n" + strings.Join(blocks, "\n\n") + "\n"
+	return []byte(out), nil
+}
+
+func txtBlock(n pmNode) string {
+	switch n.Type {
+	case "bulletList", "orderedList":
+		var items []string
+		for i, item := range n.Content {
+			marker := "• "
+			if n.Type == "orderedList" {
+				marker = fmt.Sprintf("%d. ", i+1)
+			}
+			items = append(items, marker+strings.TrimSpace(textContent(item)))
+		}
+		return strings.Join(items, "\n")
+	case "horizontalRule":
+		return "----------"
+	default:
+		return textContent(n)
+	}
+}
+
+// textContent flattens all descendant text, joining hardBreaks as newlines.
+func textContent(n pmNode) string {
+	if n.Type == "text" {
+		return n.Text
+	}
+	if n.Type == "hardBreak" {
+		return "\n"
+	}
+	var b strings.Builder
+	for _, c := range n.Content {
+		b.WriteString(textContent(c))
+	}
+	return b.String()
+}
+
+// --- HTML -------------------------------------------------------------------
+
+func renderHTMLFile(doc db.Document) ([]byte, error) {
+	root := parseDoc(doc)
+	var body strings.Builder
+	for _, child := range root.Content {
+		body.WriteString(htmlBlock(child))
+	}
+	page := fmt.Sprintf(htmlTemplate, htmlEscape(doc.Title), htmlEscape(doc.Title), body.String())
+	return []byte(page), nil
+}
+
+// htmlTemplate is a standalone, self-contained page with a warm, readable
+// stylesheet and a CJK-first font stack so exported writing looks like Petal,
+// not a raw dump. No external assets — opens offline anywhere.
+const htmlTemplate = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>%s</title>
+<style>
+  :root { color-scheme: light; }
+  body {
+    font-family: "Georgia", "Songti SC", "Noto Serif CJK SC", "Source Han Serif SC", serif;
+    line-height: 1.75; color: #463a3f; background: #fffafb;
+    max-width: 42rem; margin: 3rem auto; padding: 0 1.5rem;
+  }
+  h1, h2, h3 { font-family: "Georgia", "Songti SC", serif; color: #b04a6a; line-height: 1.3; }
+  h1 { font-size: 1.9rem; border-bottom: 2px solid #f6d6e0; padding-bottom: .4rem; }
+  blockquote { border-left: 3px solid #f3b6c8; margin: 1rem 0; padding: .2rem 1rem; color: #6b5860; background: #fff2f6; }
+  code { background: #fdeef3; padding: .1rem .35rem; border-radius: .3rem; font-size: .9em; }
+  pre { background: #fdeef3; padding: 1rem; border-radius: .6rem; overflow-x: auto; }
+  pre code { background: none; padding: 0; }
+  hr { border: none; border-top: 1px solid #f3cdd9; margin: 2rem 0; }
+  a { color: #b04a6a; }
+  ul, ol { padding-left: 1.4rem; }
+</style>
+</head>
+<body>
+<h1>%s</h1>
+%s</body>
+</html>
+`
+
+func htmlBlock(n pmNode) string {
+	switch n.Type {
+	case "heading":
+		tag := fmt.Sprintf("h%d", clampHeading(n.level()))
+		return fmt.Sprintf("<%s>%s</%s>\n", tag, htmlInline(n.Content), tag)
+	case "paragraph":
+		inner := htmlInline(n.Content)
+		if inner == "" {
+			return "<p><br></p>\n"
+		}
+		return "<p>" + inner + "</p>\n"
+	case "blockquote":
+		var b strings.Builder
+		for _, c := range n.Content {
+			b.WriteString(htmlBlock(c))
+		}
+		return "<blockquote>" + b.String() + "</blockquote>\n"
+	case "codeBlock":
+		return "<pre><code>" + htmlEscape(textContent(n)) + "</code></pre>\n"
+	case "horizontalRule":
+		return "<hr>\n"
+	case "image":
+		alt := htmlEscape(n.attrStr("alt"))
+		return fmt.Sprintf("<p><img src=\"%s\" alt=\"%s\"></p>\n", htmlEscape(n.attrStr("src")), alt)
+	case "table":
+		return htmlTable(n)
+	case "bulletList", "orderedList":
+		tag := "ul"
+		if n.Type == "orderedList" {
+			tag = "ol"
+		}
+		var b strings.Builder
+		b.WriteString("<" + tag + ">\n")
+		for _, item := range n.Content {
+			var inner strings.Builder
+			for _, c := range item.Content {
+				// Unwrap a lone paragraph so list items aren't double-spaced.
+				if c.Type == "paragraph" {
+					inner.WriteString(htmlInline(c.Content))
+				} else {
+					inner.WriteString(htmlBlock(c))
+				}
+			}
+			b.WriteString("<li>" + inner.String() + "</li>\n")
+		}
+		b.WriteString("</" + tag + ">\n")
+		return b.String()
+	default:
+		if len(n.Content) > 0 {
+			return "<p>" + htmlInline(n.Content) + "</p>\n"
+		}
+		return ""
+	}
+}
+
+// htmlTable renders a table node as an HTML <table>. tableHeader cells become
+// <th>, tableCell cells become <td>; each cell's block children are flattened
+// to inline HTML.
+func htmlTable(n pmNode) string {
+	var b strings.Builder
+	b.WriteString("<table>\n")
+	for _, row := range n.Content {
+		if row.Type != "tableRow" {
+			continue
+		}
+		b.WriteString("<tr>")
+		for _, cell := range row.Content {
+			tag := "td"
+			if cell.Type == "tableHeader" {
+				tag = "th"
+			}
+			var inner strings.Builder
+			for _, c := range cell.Content {
+				if c.Type == "paragraph" {
+					inner.WriteString(htmlInline(c.Content))
+				} else {
+					inner.WriteString(htmlBlock(c))
+				}
+			}
+			b.WriteString("<" + tag + ">" + inner.String() + "</" + tag + ">")
+		}
+		b.WriteString("</tr>\n")
+	}
+	b.WriteString("</table>\n")
+	return b.String()
+}
+
+func htmlInline(nodes []pmNode) string {
+	var b strings.Builder
+	for _, n := range nodes {
+		switch n.Type {
+		case "text":
+			b.WriteString(applyHTMLMarks(n))
+		case "hardBreak":
+			b.WriteString("<br>")
+		default:
+			b.WriteString(htmlInline(n.Content))
+		}
+	}
+	return b.String()
+}
+
+func applyHTMLMarks(n pmNode) string {
+	t := htmlEscape(n.Text)
+	if n.hasMark("code") {
+		return "<code>" + t + "</code>"
+	}
+	if n.hasMark("bold") {
+		t = "<strong>" + t + "</strong>"
+	}
+	if n.hasMark("italic") {
+		t = "<em>" + t + "</em>"
+	}
+	if n.hasMark("underline") {
+		t = "<u>" + t + "</u>"
+	}
+	if n.hasMark("strike") {
+		t = "<s>" + t + "</s>"
+	}
+	if n.hasMark("highlight") {
+		t = "<mark>" + t + "</mark>"
+	}
+	if href := n.markAttr("link", "href"); href != "" {
+		t = fmt.Sprintf("<a href=\"%s\">%s</a>", htmlEscape(href), t)
+	}
+	return t
+}
+
+func clampHeading(level int) int {
+	if level < 1 {
+		return 1
+	}
+	if level > 6 {
+		return 6
+	}
+	return level
+}
+
+// --- DOCX -------------------------------------------------------------------
+
+// renderDocx builds a minimal but valid .docx (Office Open XML) in pure Go: a
+// zip of the few XML parts Word needs. Bold/italic/underline/strike map to run
+// properties; headings use Word's built-in styles; lists are rendered with a
+// bullet/number prefix (no numbering.xml dependency). CJK renders with the
+// reader's own fonts, so no font embedding is required.
+func renderDocx(doc db.Document) ([]byte, error) {
+	root := parseDoc(doc)
+
+	var body strings.Builder
+	body.WriteString(docxHeading(doc.Title, 1))
+	for _, child := range root.Content {
+		body.WriteString(docxBlock(child))
+	}
+
+	document := xmlHeader + `<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">` +
+		`<w:body>` + body.String() +
+		`<w:sectPr><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:bottom="1440" w:left="1440" w:right="1440"/></w:sectPr>` +
+		`</w:body></w:document>`
+
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	parts := []struct{ name, content string }{
+		{"[Content_Types].xml", docxContentTypes},
+		{"_rels/.rels", docxRootRels},
+		{"word/_rels/document.xml.rels", docxDocRels},
+		{"word/document.xml", document},
+	}
+	for _, p := range parts {
+		fw, err := zw.Create(p.name)
+		if err != nil {
+			return nil, err
+		}
+		if _, err := fw.Write([]byte(p.content)); err != nil {
+			return nil, err
+		}
+	}
+	if err := zw.Close(); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+const (
+	xmlHeader        = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + "\n"
+	docxContentTypes = xmlHeader + `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
+		`<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>` +
+		`<Default Extension="xml" ContentType="application/xml"/>` +
+		`<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>` +
+		`</Types>`
+	docxRootRels = xmlHeader + `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+		`<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>` +
+		`</Relationships>`
+	docxDocRels = xmlHeader + `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>`
+)
+
+func docxBlock(n pmNode) string {
+	switch n.Type {
+	case "heading":
+		return docxHeading(textContent(n), n.level())
+	case "paragraph":
+		return docxPara(n, "")
+	case "blockquote":
+		var b strings.Builder
+		for _, c := range n.Content {
+			b.WriteString(docxPara(c, "Quote"))
+		}
+		return b.String()
+	case "codeBlock":
+		// One paragraph per line preserves layout without a code style.
+		var b strings.Builder
+		for _, line := range strings.Split(textContent(n), "\n") {
+			b.WriteString(`<w:p><w:r><w:rPr><w:rFonts w:ascii="Consolas" w:hAnsi="Consolas"/></w:rPr>` +
+				`<w:t xml:space="preserve">` + xmlEscape(line) + `</w:t></w:r></w:p>`)
+		}
+		return b.String()
+	case "horizontalRule":
+		return `<w:p><w:pPr><w:pBdr><w:bottom w:val="single" w:sz="6" w:space="1" w:color="auto"/></w:pBdr></w:pPr></w:p>`
+	case "image":
+		// Image bytes aren't embedded (that needs media parts); leave a labeled
+		// placeholder so the reader knows an image belonged here.
+		label := n.attrStr("alt")
+		if label == "" {
+			label = "image"
+		}
+		return docxPara(pmNode{Content: []pmNode{{Type: "text", Text: "[" + label + "]", Marks: []pmMark{{Type: "italic"}}}}}, "")
+	case "table":
+		return docxTable(n)
+	case "bulletList", "orderedList":
+		var b strings.Builder
+		for i, item := range n.Content {
+			prefix := "•  "
+			if n.Type == "orderedList" {
+				prefix = fmt.Sprintf("%d.  ", i+1)
+			}
+			for _, c := range item.Content {
+				b.WriteString(docxPara(c, "", prefix))
+			}
+		}
+		return b.String()
+	default:
+		if len(n.Content) > 0 {
+			return docxPara(n, "")
+		}
+		return ""
+	}
+}
+
+// docxTable renders a table node as a Word table (w:tbl) with single-line
+// borders. Header cells get a shaded background; every cell's block children are
+// rendered as paragraphs inside the cell.
+func docxTable(n pmNode) string {
+	var b strings.Builder
+	b.WriteString(`<w:tbl><w:tblPr><w:tblStyle w:val="TableGrid"/><w:tblW w:w="0" w:type="auto"/>` +
+		`<w:tblBorders>` +
+		`<w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`<w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`<w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`<w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`<w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`<w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/>` +
+		`</w:tblBorders></w:tblPr>`)
+	for _, row := range n.Content {
+		if row.Type != "tableRow" {
+			continue
+		}
+		b.WriteString("<w:tr>")
+		for _, cell := range row.Content {
+			b.WriteString("<w:tc><w:tcPr>")
+			if cell.Type == "tableHeader" {
+				b.WriteString(`<w:shd w:val="clear" w:color="auto" w:fill="FFF0F5"/>`)
+			}
+			b.WriteString("</w:tcPr>")
+			// A cell must contain at least one paragraph to be valid.
+			if len(cell.Content) == 0 {
+				b.WriteString("<w:p/>")
+			}
+			for _, c := range cell.Content {
+				b.WriteString(docxBlock(c))
+			}
+			b.WriteString("</w:tc>")
+		}
+		b.WriteString("</w:tr>")
+	}
+	b.WriteString("</w:tbl>")
+	// Word needs a paragraph after a table; otherwise consecutive tables merge.
+	b.WriteString("<w:p/>")
+	return b.String()
+}
+
+// docxPara renders a block's inline children as a Word paragraph. An optional
+// style name (e.g. "Quote") and an optional literal text prefix (for list
+// markers) may be supplied.
+func docxPara(n pmNode, style string, prefix ...string) string {
+	var b strings.Builder
+	b.WriteString("<w:p>")
+	if style != "" {
+		b.WriteString(`<w:pPr><w:pStyle w:val="` + style + `"/></w:pPr>`)
+	}
+	if len(prefix) > 0 && prefix[0] != "" {
+		b.WriteString(docxRun(pmNode{Type: "text", Text: prefix[0]}))
+	}
+	b.WriteString(docxInline(n.Content))
+	b.WriteString("</w:p>")
+	return b.String()
+}
+
+func docxHeading(text string, level int) string {
+	return `<w:p><w:pPr><w:pStyle w:val="Heading` + fmt.Sprintf("%d", clampHeading(level)) + `"/></w:pPr>` +
+		docxRun(pmNode{Type: "text", Text: text}) + `</w:p>`
+}
+
+func docxInline(nodes []pmNode) string {
+	var b strings.Builder
+	for _, n := range nodes {
+		switch n.Type {
+		case "text":
+			b.WriteString(docxRun(n))
+		case "hardBreak":
+			b.WriteString(`<w:r><w:br/></w:r>`)
+		default:
+			b.WriteString(docxInline(n.Content))
+		}
+	}
+	return b.String()
+}
+
+func docxRun(n pmNode) string {
+	var props strings.Builder
+	if n.hasMark("bold") {
+		props.WriteString("<w:b/>")
+	}
+	if n.hasMark("italic") {
+		props.WriteString("<w:i/>")
+	}
+	if n.hasMark("underline") {
+		props.WriteString(`<w:u w:val="single"/>`)
+	}
+	if n.hasMark("strike") {
+		props.WriteString("<w:strike/>")
+	}
+	if n.hasMark("highlight") {
+		// Word's text highlight only supports a fixed palette of named colors.
+		props.WriteString(`<w:highlight w:val="yellow"/>`)
+	}
+	if n.markAttr("link", "href") != "" {
+		// Without hyperlink relationships, style links as blue underlined text so
+		// they at least read as links (the URL itself is preserved in md/html).
+		props.WriteString(`<w:color w:val="2563EB"/><w:u w:val="single"/>`)
+	}
+	rpr := ""
+	if props.Len() > 0 {
+		rpr = "<w:rPr>" + props.String() + "</w:rPr>"
+	}
+	return `<w:r>` + rpr + `<w:t xml:space="preserve">` + xmlEscape(n.Text) + `</w:t></w:r>`
+}
+
+// --- small helpers ----------------------------------------------------------
+
+func htmlEscape(s string) string {
+	r := strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&#39;")
+	return r.Replace(s)
+}
+
+func xmlEscape(s string) string {
+	r := strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;")
+	return r.Replace(s)
+}
+
+// sanitizeFilename makes a title safe as a download filename, preserving CJK and
+// most letters while dropping path separators and control characters.
+func sanitizeFilename(title string) string {
+	title = strings.TrimSpace(title)
+	if title == "" {
+		return "untitled"
+	}
+	var b strings.Builder
+	for _, r := range title {
+		switch {
+		case r < 0x20, r == '/', r == '\\', r == ':', r == '*', r == '?', r == '"', r == '<', r == '>', r == '|':
+			b.WriteRune('-')
+		default:
+			b.WriteRune(r)
+		}
+	}
+	out := strings.TrimSpace(b.String())
+	if out == "" {
+		return "untitled"
+	}
+	return out
+}
+
+// urlEscapeFilename percent-encodes a filename for the RFC 5987 filename*=
+// Content-Disposition form, which carries UTF-8 (CJK titles) safely.
+func urlEscapeFilename(s string) string {
+	var b strings.Builder
+	for _, c := range []byte(s) {
+		if (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') ||
+			c == '-' || c == '_' || c == '.' || c == '~' {
+			b.WriteByte(c)
+		} else {
+			fmt.Fprintf(&b, "%%%02X", c)
+		}
+	}
+	return b.String()
+}

internal/docs/export_test.go

@@ -0,0 +1,245 @@
+package docs
+
+import (
+	"archive/zip"
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// richDocJSON is a Tiptap document exercising headings, marks, and a list —
+// including CJK text, which every format must carry through intact.
+const richDocJSON = `{"type":"doc","content":[` +
+	`{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"My Section"}]},` +
+	`{"type":"paragraph","content":[{"type":"text","text":"Hello "},{"type":"text","marks":[{"type":"bold"}],"text":"world"},{"type":"text","text":" 你好"}]},` +
+	`{"type":"bulletList","content":[` +
+	`{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"text","text":"first"}]}]},` +
+	`{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"text","text":"second"}]}]}` +
+	`]}` +
+	`]}`
+
+func seedRichDoc(t *testing.T, srv http.Handler) string {
+	t.Helper()
+	id := newDoc(t, srv)
+	body := `{"title":"日记 Diary","content":` + jsonString(richDocJSON) + `,"content_text":"My Section\nHello world 你好\nfirst\nsecond","word_count":6}`
+	if rec := do(t, srv, http.MethodPut, "/"+id, body); rec.Code != http.StatusOK {
+		t.Fatalf("seed rich doc: code=%d body=%s", rec.Code, rec.Body)
+	}
+	return id
+}
+
+// jsonString quotes a string as a JSON string literal (so the Tiptap JSON can be
+// embedded as the "content" field value).
+func jsonString(s string) string {
+	b, _ := json.Marshal(s)
+	return string(b)
+}
+
+func TestExportMarkdown(t *testing.T) {
+	srv := newTestServer(t)
+	id := seedRichDoc(t, srv)
+
+	rec := do(t, srv, http.MethodGet, "/"+id+"/export?format=md", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("export md: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/markdown") {
+		t.Fatalf("unexpected content-type: %q", ct)
+	}
+	out := rec.Body.String()
+	for _, want := range []string{"## My Section", "**world**", "你好", "- first", "- second"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("markdown missing %q in:\n%s", want, out)
+		}
+	}
+	// CJK filename must survive in the RFC 5987 form.
+	if cd := rec.Header().Get("Content-Disposition"); !strings.Contains(cd, "filename*=UTF-8''") {
+		t.Fatalf("expected RFC 5987 filename, got %q", cd)
+	}
+}
+
+func TestExportAll(t *testing.T) {
+	srv := newTestServer(t)
+	// Two docs, one with a duplicate title to exercise filename de-duplication.
+	seedRichDoc(t, srv)
+	id2 := newDoc(t, srv)
+	if rec := do(t, srv, http.MethodPut, "/"+id2, `{"title":"日记 Diary","content":`+jsonString(richDocJSON)+`,"content_text":"x","word_count":1}`); rec.Code != http.StatusOK {
+		t.Fatalf("seed second doc: %d %s", rec.Code, rec.Body)
+	}
+
+	rec := do(t, srv, http.MethodGet, "/export-all?format=md", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("export-all: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "application/zip" {
+		t.Fatalf("unexpected content-type: %q", ct)
+	}
+	zr, err := zip.NewReader(bytes.NewReader(rec.Body.Bytes()), int64(rec.Body.Len()))
+	if err != nil {
+		t.Fatalf("zip open: %v", err)
+	}
+	if len(zr.File) != 2 {
+		t.Fatalf("expected 2 files in backup, got %d", len(zr.File))
+	}
+	names := map[string]bool{}
+	for _, f := range zr.File {
+		names[f.Name] = true
+		rc, _ := f.Open()
+		b, _ := io.ReadAll(rc)
+		rc.Close()
+		if !strings.Contains(string(b), "你好") {
+			t.Fatalf("backup entry %q missing CJK body", f.Name)
+		}
+	}
+	// The duplicate title must have been disambiguated, not overwritten.
+	if !names["日记 Diary.md"] || !names["日记 Diary (1).md"] {
+		t.Fatalf("expected de-duplicated filenames, got %v", names)
+	}
+}
+
+func TestExportHTML(t *testing.T) {
+	srv := newTestServer(t)
+	id := seedRichDoc(t, srv)
+
+	rec := do(t, srv, http.MethodGet, "/"+id+"/export?format=html", "")
+	out := rec.Body.String()
+	for _, want := range []string{"<!doctype html>", "<h2>My Section</h2>", "<strong>world</strong>", "你好", "<li>first</li>"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("html missing %q", want)
+		}
+	}
+}
+
+func TestExportPlainText(t *testing.T) {
+	srv := newTestServer(t)
+	id := seedRichDoc(t, srv)
+
+	rec := do(t, srv, http.MethodGet, "/"+id+"/export?format=txt", "")
+	out := rec.Body.String()
+	for _, want := range []string{"My Section", "Hello world 你好", "• first"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("txt missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+func TestExportDocx(t *testing.T) {
+	srv := newTestServer(t)
+	id := seedRichDoc(t, srv)
+
+	rec := do(t, srv, http.MethodGet, "/"+id+"/export?format=docx", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("export docx: code=%d", rec.Code)
+	}
+	raw := rec.Body.Bytes()
+	zr, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw)))
+	if err != nil {
+		t.Fatalf("docx is not a valid zip: %v", err)
+	}
+
+	want := map[string]bool{"[Content_Types].xml": false, "word/document.xml": false}
+	var docXML string
+	for _, f := range zr.File {
+		if _, ok := want[f.Name]; ok {
+			want[f.Name] = true
+		}
+		if f.Name == "word/document.xml" {
+			rc, _ := f.Open()
+			b, _ := io.ReadAll(rc)
+			rc.Close()
+			docXML = string(b)
+		}
+	}
+	for name, found := range want {
+		if !found {
+			t.Fatalf("docx missing part %q", name)
+		}
+	}
+	for _, w := range []string{"My Section", "你好", "<w:b/>", "Heading2"} {
+		if !strings.Contains(docXML, w) {
+			t.Fatalf("document.xml missing %q", w)
+		}
+	}
+}
+
+// richDocJSON2 exercises the newer node/mark types: links, highlight, an image,
+// and a table (with a header row). Each export format should carry them through.
+const richDocJSON2 = `{"type":"doc","content":[` +
+	`{"type":"paragraph","content":[` +
+	`{"type":"text","marks":[{"type":"link","attrs":{"href":"https://petal.test"}}],"text":"site"},` +
+	`{"type":"text","text":" and "},` +
+	`{"type":"text","marks":[{"type":"highlight","attrs":{"color":"#FFF1A8"}}],"text":"lit"}` +
+	`]},` +
+	`{"type":"image","attrs":{"src":"/api/images/abc123.png","alt":"a cat"}},` +
+	`{"type":"table","content":[` +
+	`{"type":"tableRow","content":[` +
+	`{"type":"tableHeader","content":[{"type":"paragraph","content":[{"type":"text","text":"Name"}]}]},` +
+	`{"type":"tableHeader","content":[{"type":"paragraph","content":[{"type":"text","text":"年龄"}]}]}` +
+	`]},` +
+	`{"type":"tableRow","content":[` +
+	`{"type":"tableCell","content":[{"type":"paragraph","content":[{"type":"text","text":"Mei"}]}]},` +
+	`{"type":"tableCell","content":[{"type":"paragraph","content":[{"type":"text","text":"30"}]}]}` +
+	`]}` +
+	`]}` +
+	`]}`
+
+func seedRichDoc2(t *testing.T, srv http.Handler) string {
+	t.Helper()
+	id := newDoc(t, srv)
+	body := `{"title":"Rich2","content":` + jsonString(richDocJSON2) + `,"content_text":"site and lit\nName 年龄 Mei 30","word_count":6}`
+	if rec := do(t, srv, http.MethodPut, "/"+id, body); rec.Code != http.StatusOK {
+		t.Fatalf("seed rich doc 2: code=%d body=%s", rec.Code, rec.Body)
+	}
+	return id
+}
+
+func TestExportLinksImagesTables(t *testing.T) {
+	srv := newTestServer(t)
+	id := seedRichDoc2(t, srv)
+
+	md := do(t, srv, http.MethodGet, "/"+id+"/export?format=md", "").Body.String()
+	for _, want := range []string{"[site](https://petal.test)", "![a cat](/api/images/abc123.png)", "| Name | 年龄 |", "| --- | --- |", "| Mei | 30 |"} {
+		if !strings.Contains(md, want) {
+			t.Fatalf("markdown missing %q in:\n%s", want, md)
+		}
+	}
+
+	html := do(t, srv, http.MethodGet, "/"+id+"/export?format=html", "").Body.String()
+	for _, want := range []string{`<a href="https://petal.test">site</a>`, "<mark>lit</mark>", `<img src="/api/images/abc123.png" alt="a cat">`, "<th>Name</th>", "<td>Mei</td>"} {
+		if !strings.Contains(html, want) {
+			t.Fatalf("html missing %q in:\n%s", want, html)
+		}
+	}
+
+	docx := do(t, srv, http.MethodGet, "/"+id+"/export?format=docx", "")
+	raw := docx.Body.Bytes()
+	zr, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw)))
+	if err != nil {
+		t.Fatalf("docx not a zip: %v", err)
+	}
+	var docXML string
+	for _, f := range zr.File {
+		if f.Name == "word/document.xml" {
+			rc, _ := f.Open()
+			b, _ := io.ReadAll(rc)
+			rc.Close()
+			docXML = string(b)
+		}
+	}
+	for _, want := range []string{"<w:tbl>", "Name", "年龄", "[a cat]", "<w:highlight"} {
+		if !strings.Contains(docXML, want) {
+			t.Fatalf("docx document.xml missing %q", want)
+		}
+	}
+}
+
+func TestExportUnsupportedFormat(t *testing.T) {
+	srv := newTestServer(t)
+	id := newDoc(t, srv)
+	if rec := do(t, srv, http.MethodGet, "/"+id+"/export?format=pdf", ""); rec.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400 for unsupported format, got %d", rec.Code)
+	}
+}

internal/docs/handlers.go

@@ -0,0 +1,234 @@
+// Package docs implements the document CRUD HTTP handlers — the create / list /
+// read / update / delete surface that backs the editor and its 1.5s auto-save.
+// All access is scoped to the single hardcoded local user while auth is deferred.
+package docs
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"log"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// Handler holds the dependencies shared by every document route.
+type Handler struct {
+	DB *db.DB
+}
+
+// New constructs a Handler.
+func New(database *db.DB) *Handler {
+	return &Handler{DB: database}
+}
+
+// Routes returns a router mounting the document CRUD endpoints. Mount it under
+// "/docs" so the full paths are /api/docs, /api/docs/{id}, etc.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)
+	r.Post("/", h.create)
+	r.Get("/{id}", h.get)
+	r.Put("/{id}", h.update)
+	r.Delete("/{id}", h.delete)
+	h.versionRoutes(r)
+	h.exportRoutes(r)
+	h.registerTagRoutes(r)
+	return r
+}
+
+// docSummary is the lightweight shape returned by the list endpoint — enough to
+// render the DocList sidebar without shipping every document's full body. Tags
+// ride along so the sidebar can show chips and filter without a second request.
+type docSummary struct {
+	ID        string   `json:"id"`
+	Title     string   `json:"title"`
+	WordCount int      `json:"word_count"`
+	UpdatedAt string   `json:"updated_at"`
+	Tags      []db.Tag `json:"tags"`
+}
+
+// list returns the local user's documents, most-recently-updated first, each
+// decorated with its tags.
+func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
+	rows, err := h.DB.Query(
+		`SELECT id, title, word_count, updated_at
+		   FROM documents
+		  WHERE user_id = ?
+		  ORDER BY updated_at DESC`,
+		db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+
+	out := []docSummary{} // non-nil so an empty list serializes as [] not null
+	ids := []string{}
+	for rows.Next() {
+		var d docSummary
+		if err := rows.Scan(&d.ID, &d.Title, &d.WordCount, &d.UpdatedAt); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		out = append(out, d)
+		ids = append(ids, d.ID)
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	byDoc, err := h.tagsByDoc(ids)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	for i := range out {
+		out[i].Tags = byDoc[out[i].ID] // nil → JSON null is fine; client treats as none
+		if out[i].Tags == nil {
+			out[i].Tags = []db.Tag{}
+		}
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// create inserts a fresh blank document and returns it in full.
+func (h *Handler) create(w http.ResponseWriter, r *http.Request) {
+	var doc db.Document
+	err := h.DB.QueryRow(
+		`INSERT INTO documents (user_id) VALUES (?)
+		 RETURNING id, user_id, title, content, content_text, tone, word_count, created_at, updated_at`,
+		db.LocalUserID,
+	).Scan(
+		&doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText,
+		&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusCreated, doc)
+}
+
+// get returns a single full document by id.
+func (h *Handler) get(w http.ResponseWriter, r *http.Request) {
+	doc, err := h.fetch(chi.URLParam(r, "id"))
+	if errors.Is(err, sql.ErrNoRows) {
+		notFound(w)
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, doc)
+}
+
+// updateRequest is the auto-save payload. Every field is optional (a pointer) so
+// the same endpoint serves both the editor's full save ({content, content_text,
+// word_count, title}) and a DocList rename ({title} alone).
+type updateRequest struct {
+	Title       *string `json:"title"`
+	Content     *string `json:"content"`
+	ContentText *string `json:"content_text"`
+	Tone        *string `json:"tone"`
+	WordCount   *int    `json:"word_count"`
+}
+
+// update applies the provided fields to a document and returns the saved row.
+// content and content_text are kept in sync by the client and written together.
+func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	var req updateRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		badRequest(w, "invalid JSON body")
+		return
+	}
+
+	res, err := h.DB.Exec(
+		`UPDATE documents
+		    SET title        = COALESCE(?, title),
+		        content      = COALESCE(?, content),
+		        content_text = COALESCE(?, content_text),
+		        tone         = COALESCE(?, tone),
+		        word_count   = COALESCE(?, word_count),
+		        updated_at   = CURRENT_TIMESTAMP
+		  WHERE id = ? AND user_id = ?`,
+		req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, id, db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFound(w)
+		return
+	}
+
+	doc, err := h.fetch(id)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	// Capture a throttled history snapshot when a real body save came through
+	// (not a bare rename) and the document has content. Best-effort: a failed
+	// snapshot must never fail the save itself.
+	if req.Content != nil && doc.ContentText != "" {
+		if err := h.maybeAutoSnapshot(doc); err != nil {
+			log.Printf("docs: auto-snapshot for %s failed: %v", id, err)
+		}
+	}
+
+	httputil.WriteJSON(w, http.StatusOK, doc)
+}
+
+// delete removes a document (suggestions cascade via the FK).
+func (h *Handler) delete(w http.ResponseWriter, r *http.Request) {
+	res, err := h.DB.Exec(
+		`DELETE FROM documents WHERE id = ? AND user_id = ?`,
+		chi.URLParam(r, "id"), db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFound(w)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// fetch loads one full document scoped to the local user.
+func (h *Handler) fetch(id string) (db.Document, error) {
+	var doc db.Document
+	err := h.DB.QueryRow(
+		`SELECT id, user_id, title, content, content_text, tone, word_count, created_at, updated_at
+		   FROM documents
+		  WHERE id = ? AND user_id = ?`,
+		id, db.LocalUserID,
+	).Scan(
+		&doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText,
+		&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
+	)
+	return doc, err
+}
+
+// --- small response helpers -------------------------------------------------
+//
+// The generic JSON/error helpers live in internal/httputil; these are the
+// document-specific shorthands that carry domain wording.
+
+func badRequest(w http.ResponseWriter, msg string) { httputil.BadRequest(w, msg) }
+func notFound(w http.ResponseWriter) {
+	httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
+}
+func notFoundMsg(w http.ResponseWriter, msg string) { httputil.ErrorJSON(w, http.StatusNotFound, msg) }

internal/docs/handlers_test.go

@@ -0,0 +1,103 @@
+package docs
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// newTestServer spins up an isolated on-disk database and the docs router.
+func newTestServer(t *testing.T) http.Handler {
+	t.Helper()
+	database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { database.Close() })
+	return New(database).Routes()
+}
+
+func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	} else {
+		r = httptest.NewRequest(method, path, nil)
+	}
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, r)
+	return rec
+}
+
+func TestDocumentCRUD(t *testing.T) {
+	srv := newTestServer(t)
+
+	// Empty list serializes as [].
+	rec := do(t, srv, http.MethodGet, "/", "")
+	if rec.Code != http.StatusOK || bytes.TrimSpace(rec.Body.Bytes())[0] != '[' {
+		t.Fatalf("list empty: code=%d body=%s", rec.Code, rec.Body)
+	}
+
+	// Create.
+	rec = do(t, srv, http.MethodPost, "/", "")
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var created db.Document
+	if err := json.Unmarshal(rec.Body.Bytes(), &created); err != nil {
+		t.Fatalf("decode create: %v", err)
+	}
+	if created.ID == "" || created.Title != "Untitled" {
+		t.Fatalf("unexpected created doc: %+v", created)
+	}
+
+	// Update (auto-save shape) keeps content + content_text + word count together.
+	body := `{"title":"My Essay","content":"{\"x\":1}","content_text":"hello world","word_count":2}`
+	rec = do(t, srv, http.MethodPut, "/"+created.ID, body)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("update: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var updated db.Document
+	_ = json.Unmarshal(rec.Body.Bytes(), &updated)
+	if updated.Title != "My Essay" || updated.ContentText != "hello world" || updated.WordCount != 2 {
+		t.Fatalf("update not applied: %+v", updated)
+	}
+
+	// Partial update (rename only) leaves other fields intact.
+	rec = do(t, srv, http.MethodPut, "/"+created.ID, `{"title":"Renamed"}`)
+	_ = json.Unmarshal(rec.Body.Bytes(), &updated)
+	if updated.Title != "Renamed" || updated.WordCount != 2 {
+		t.Fatalf("partial update clobbered fields: %+v", updated)
+	}
+
+	// Get.
+	rec = do(t, srv, http.MethodGet, "/"+created.ID, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("get: code=%d", rec.Code)
+	}
+
+	// List now has one entry.
+	rec = do(t, srv, http.MethodGet, "/", "")
+	var summaries []docSummary
+	_ = json.Unmarshal(rec.Body.Bytes(), &summaries)
+	if len(summaries) != 1 || summaries[0].Title != "Renamed" {
+		t.Fatalf("list after create: %+v", summaries)
+	}
+
+	// Delete, then 404 on subsequent get/delete.
+	if rec = do(t, srv, http.MethodDelete, "/"+created.ID, ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("delete: code=%d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodGet, "/"+created.ID, ""); rec.Code != http.StatusNotFound {
+		t.Fatalf("get after delete: code=%d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodPut, "/missing", `{"title":"x"}`); rec.Code != http.StatusNotFound {
+		t.Fatalf("update missing: code=%d", rec.Code)
+	}
+}

internal/docs/search.go

@@ -0,0 +1,262 @@
+package docs
+
+import (
+	"net/http"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// Search snippet shaping.
+const (
+	// ftsMinRunes is the shortest query the trigram FTS index can match. Shorter
+	// queries (common for 2-character Chinese words) fall back to a LIKE scan.
+	ftsMinRunes = 3
+
+	// snippetContext is how many runes of context to show on each side of the
+	// matched term in a result snippet.
+	snippetContext = 28
+
+	// maxSearchResults caps how many hits we return — plenty for a personal
+	// corpus, and keeps the response small.
+	maxSearchResults = 50
+
+	// hlStart/hlEnd wrap the matched span in a snippet. They're control-character
+	// sentinels that never occur in real text, so the client can split on them to
+	// highlight the match without escaping user content.
+	hlStart = "\x01"
+	hlEnd   = "\x02"
+)
+
+// searchResult is one hit: a document summary plus a highlighted snippet showing
+// where the query matched.
+type searchResult struct {
+	ID        string   `json:"id"`
+	Title     string   `json:"title"`
+	WordCount int      `json:"word_count"`
+	UpdatedAt string   `json:"updated_at"`
+	Snippet   string   `json:"snippet"`
+	Tags      []db.Tag `json:"tags"`
+}
+
+// SearchRoutes returns the router mounted at /api/search.
+func (h *Handler) SearchRoutes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.search)
+	return r
+}
+
+// search runs a cross-document full-text search for the local user. Queries of
+// three or more runes use the trigram FTS index (fast, ranked); shorter queries
+// fall back to a LIKE scan so 2-character Chinese words still resolve. Either way
+// the snippet is built in Go from the original text, for clean word boundaries
+// and a uniform highlight format.
+func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
+	q := strings.TrimSpace(r.URL.Query().Get("q"))
+	if q == "" {
+		httputil.WriteJSON(w, http.StatusOK, []searchResult{})
+		return
+	}
+
+	type row struct {
+		id, title, contentText, updatedAt string
+		wordCount                         int
+	}
+	var rows []row
+
+	if utf8.RuneCountInString(q) >= ftsMinRunes {
+		// Wrap the whole query as one FTS phrase (doubling embedded quotes), so
+		// special characters are treated literally and trigram does a contiguous
+		// substring match.
+		phrase := `"` + strings.ReplaceAll(q, `"`, `""`) + `"`
+		sqlRows, err := h.DB.Query(
+			`SELECT d.id, d.title, d.content_text, d.word_count, d.updated_at
+			   FROM documents_fts f
+			   JOIN documents d ON d.id = f.doc_id
+			  WHERE documents_fts MATCH ? AND d.user_id = ?
+			  ORDER BY rank
+			  LIMIT ?`,
+			phrase, db.LocalUserID, maxSearchResults,
+		)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		defer sqlRows.Close()
+		for sqlRows.Next() {
+			var rw row
+			if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil {
+				httputil.ServerError(w, err)
+				return
+			}
+			rows = append(rows, rw)
+		}
+		if err := sqlRows.Err(); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+	} else {
+		// Short query: LIKE scan over title + body. Escape LIKE wildcards so a
+		// literal % or _ in the query matches itself.
+		like := "%" + escapeLike(q) + "%"
+		sqlRows, err := h.DB.Query(
+			`SELECT id, title, content_text, word_count, updated_at
+			   FROM documents
+			  WHERE user_id = ?
+			    AND (title LIKE ? ESCAPE '\' OR content_text LIKE ? ESCAPE '\')
+			  ORDER BY updated_at DESC
+			  LIMIT ?`,
+			db.LocalUserID, like, like, maxSearchResults,
+		)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		defer sqlRows.Close()
+		for sqlRows.Next() {
+			var rw row
+			if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil {
+				httputil.ServerError(w, err)
+				return
+			}
+			rows = append(rows, rw)
+		}
+		if err := sqlRows.Err(); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+	}
+
+	out := make([]searchResult, 0, len(rows))
+	ids := make([]string, 0, len(rows))
+	for _, rw := range rows {
+		out = append(out, searchResult{
+			ID:        rw.id,
+			Title:     rw.title,
+			WordCount: rw.wordCount,
+			UpdatedAt: rw.updatedAt,
+			Snippet:   buildSnippet(rw.title, rw.contentText, q),
+		})
+		ids = append(ids, rw.id)
+	}
+
+	byDoc, err := h.tagsByDoc(ids)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	for i := range out {
+		out[i].Tags = byDoc[out[i].ID]
+		if out[i].Tags == nil {
+			out[i].Tags = []db.Tag{}
+		}
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// escapeLike escapes the LIKE metacharacters (% and _) and the escape character
+// itself so the query is matched literally. Pairs with `ESCAPE '\'`.
+func escapeLike(s string) string {
+	r := strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`)
+	return r.Replace(s)
+}
+
+// buildSnippet returns a short excerpt around the first case-insensitive match of
+// query, with the matched span wrapped in the hl sentinels. It prefers a body
+// match (with surrounding context); if the query only appears in the title it
+// highlights the title instead; otherwise it shows the body's opening so a result
+// always shows something. Windowing is rune-aware so CJK is never split
+// mid-character.
+func buildSnippet(title, body, query string) string {
+	runes := []rune(body)
+	qLen := utf8.RuneCountInString(query)
+	if idx := runeIndexFold(runes, query); idx >= 0 {
+		start := idx - snippetContext
+		if start < 0 {
+			start = 0
+		}
+		end := idx + qLen + snippetContext
+		if end > len(runes) {
+			end = len(runes)
+		}
+		var b strings.Builder
+		if start > 0 {
+			b.WriteString("…")
+		}
+		b.WriteString(string(runes[start:idx]))
+		b.WriteString(hlStart)
+		b.WriteString(string(runes[idx : idx+qLen]))
+		b.WriteString(hlEnd)
+		b.WriteString(string(runes[idx+qLen : end]))
+		if end < len(runes) {
+			b.WriteString("…")
+		}
+		return b.String()
+	}
+
+	// Body had no literal match (title-only hit, or an FTS span the literal scan
+	// can't reproduce). Highlight the title if the query is there.
+	tRunes := []rune(title)
+	if idx := runeIndexFold(tRunes, query); idx >= 0 {
+		return string(tRunes[:idx]) + hlStart + string(tRunes[idx:idx+qLen]) + hlEnd + string(tRunes[idx+qLen:])
+	}
+
+	// Last resort: the body's opening as plain context.
+	return clip(runes, 0, 2*snippetContext+qLen)
+}
+
+// clip returns runes[start:start+n] (bounded), with a trailing ellipsis when the
+// body continues. Used for the no-direct-match fallback.
+func clip(runes []rune, start, n int) string {
+	if start >= len(runes) {
+		return ""
+	}
+	end := start + n
+	trailing := ""
+	if end < len(runes) {
+		trailing = "…"
+	} else {
+		end = len(runes)
+	}
+	return string(runes[start:end]) + trailing
+}
+
+// runeIndexFold finds the first index (in runes) where query occurs in runes,
+// case-insensitively. Returns -1 if absent. Simple O(n*m) scan — fine for
+// single-document snippet building.
+func runeIndexFold(runes []rune, query string) int {
+	q := []rune(strings.ToLower(query))
+	if len(q) == 0 {
+		return -1
+	}
+	lower := make([]rune, len(runes))
+	for i, r := range runes {
+		lower[i] = toLowerRune(r)
+	}
+	for i := 0; i+len(q) <= len(lower); i++ {
+		match := true
+		for j := 0; j < len(q); j++ {
+			if lower[i+j] != q[j] {
+				match = false
+				break
+			}
+		}
+		if match {
+			return i
+		}
+	}
+	return -1
+}
+
+// toLowerRune lowercases ASCII letters (the only case-bearing script here); CJK
+// and other runes pass through unchanged.
+func toLowerRune(r rune) rune {
+	if r >= 'A' && r <= 'Z' {
+		return r + ('a' - 'A')
+	}
+	return r
+}

internal/docs/search_test.go

@@ -0,0 +1,111 @@
+package docs
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestSearch(t *testing.T) {
+	srv := newFullServer(t)
+
+	createDoc(t, srv, "My Essay", "The quick brown fox jumps over the lazy dog")
+	createDoc(t, srv, "我的日记", "今天天气很好，我去公园散步，心情非常愉快")
+	createDoc(t, srv, "Notes", "groceries and errands for the weekend")
+
+	search := func(q string) []searchResult {
+		t.Helper()
+		rec := do(t, srv, http.MethodGet, "/search?q="+urlQuery(q), "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("search %q: %d %s", q, rec.Code, rec.Body)
+		}
+		var out []searchResult
+		if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+			t.Fatalf("decode search %q: %v", q, err)
+		}
+		return out
+	}
+
+	// English, ≥3 chars → FTS path. Snippet wraps the match in sentinels.
+	res := search("quick")
+	if len(res) != 1 || res[0].Title != "My Essay" {
+		t.Fatalf("english search: %+v", res)
+	}
+	if !strings.Contains(res[0].Snippet, hlStart+"quick"+hlEnd) {
+		t.Fatalf("snippet not highlighted: %q", res[0].Snippet)
+	}
+
+	// Chinese, ≥3 chars → FTS path (trigram handles CJK).
+	res = search("天气很好")
+	if len(res) != 1 || res[0].Title != "我的日记" {
+		t.Fatalf("chinese fts search: %+v", res)
+	}
+	if !strings.Contains(res[0].Snippet, hlStart+"天气很好"+hlEnd) {
+		t.Fatalf("cjk snippet not highlighted: %q", res[0].Snippet)
+	}
+
+	// 2-character Chinese word → LIKE fallback (below the trigram minimum).
+	res = search("公园")
+	if len(res) != 1 || res[0].Title != "我的日记" {
+		t.Fatalf("cjk short (LIKE) search: %+v", res)
+	}
+	if !strings.Contains(res[0].Snippet, hlStart+"公园"+hlEnd) {
+		t.Fatalf("short cjk snippet not highlighted: %q", res[0].Snippet)
+	}
+
+	// Title-only match still returns the doc, highlighting the title.
+	res = search("Notes")
+	if len(res) != 1 || res[0].Title != "Notes" {
+		t.Fatalf("title search: %+v", res)
+	}
+
+	// Case-insensitive.
+	if got := search("QUICK"); len(got) != 1 {
+		t.Fatalf("case-insensitive search: %+v", got)
+	}
+
+	// No match → empty (non-nil) array.
+	if got := search("zzzznotthere"); len(got) != 0 {
+		t.Fatalf("expected no results, got %+v", got)
+	}
+
+	// Empty query → empty array, no error.
+	rec := do(t, srv, http.MethodGet, "/search?q=", "")
+	if rec.Code != http.StatusOK || strings.TrimSpace(rec.Body.String()) != "[]" {
+		t.Fatalf("empty query: %d %s", rec.Code, rec.Body)
+	}
+
+	// An edit re-indexes via the update trigger: the old term stops matching, the
+	// new term starts.
+	res = search("quick")
+	docID := res[0].ID
+	body := `{"content":"{}","content_text":"the slow purple turtle ambles along","word_count":6}`
+	do(t, srv, http.MethodPut, "/docs/"+docID, body)
+	if got := search("quick"); len(got) != 0 {
+		t.Fatalf("stale term still matches after edit: %+v", got)
+	}
+	if got := search("purple turtle"); len(got) != 1 || got[0].ID != docID {
+		t.Fatalf("new term not indexed after edit: %+v", got)
+	}
+}
+
+// urlQuery percent-encodes a search term for the query string.
+func urlQuery(s string) string {
+	var b strings.Builder
+	for _, r := range []byte(s) {
+		if r == ' ' {
+			b.WriteByte('+')
+		} else if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') {
+			b.WriteByte(r)
+		} else {
+			b.WriteString(percentByte(r))
+		}
+	}
+	return b.String()
+}
+
+func percentByte(b byte) string {
+	const hex = "0123456789ABCDEF"
+	return string([]byte{'%', hex[b>>4], hex[b&0xf]})
+}

internal/docs/tags.go

@@ -0,0 +1,304 @@
+package docs
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// validTagColors is the palette a tag may use, mirrored from the design tokens.
+// An unknown color on input is coerced to rose so the UI always has a token.
+var validTagColors = map[string]bool{
+	db.TagColorRose: true, db.TagColorMint: true, db.TagColorPeach: true,
+	db.TagColorLavender: true, db.TagColorSky: true, db.TagColorHoney: true,
+}
+
+func normalizeColor(c string) string {
+	if validTagColors[c] {
+		return c
+	}
+	return db.TagColorRose
+}
+
+// TagRoutes returns the router mounted at /api/tags for tag management (the
+// roster the writer creates and recolors), separate from the per-document
+// assignment routes registered on the docs router.
+func (h *Handler) TagRoutes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.listTags)
+	r.Post("/", h.createTag)
+	r.Patch("/{id}", h.updateTag)
+	r.Delete("/{id}", h.deleteTag)
+	return r
+}
+
+// registerTagRoutes adds the per-document tag assignment routes onto the docs
+// sub-router so they resolve under /api/docs/{id}/tags.
+func (h *Handler) registerTagRoutes(r chi.Router) {
+	r.Post("/{id}/tags", h.assignTag)
+	r.Delete("/{id}/tags/{tagId}", h.unassignTag)
+}
+
+// listTags returns the user's tags alphabetically, each with the number of
+// documents that wear it (so the sidebar can show counts and hide empties later
+// if desired).
+func (h *Handler) listTags(w http.ResponseWriter, r *http.Request) {
+	rows, err := h.DB.Query(
+		`SELECT t.id, t.name, t.color, COUNT(dt.doc_id)
+		   FROM tags t
+		   LEFT JOIN document_tags dt ON dt.tag_id = t.id
+		  WHERE t.user_id = ?
+		  GROUP BY t.id
+		  ORDER BY t.name COLLATE NOCASE`,
+		db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+
+	out := []db.Tag{} // non-nil so an empty roster serializes as []
+	for rows.Next() {
+		var t db.Tag
+		if err := rows.Scan(&t.ID, &t.Name, &t.Color, &t.DocCount); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		out = append(out, t)
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+type tagRequest struct {
+	Name  string `json:"name"`
+	Color string `json:"color"`
+}
+
+// createTag adds a tag. It's idempotent on (user, name): re-creating an existing
+// tag returns it unchanged rather than erroring, so the client can "create or
+// reuse" in one call. Recoloring is done via updateTag.
+func (h *Handler) createTag(w http.ResponseWriter, r *http.Request) {
+	var req tagRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		badRequest(w, "invalid JSON body")
+		return
+	}
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		badRequest(w, "tag name is required")
+		return
+	}
+
+	var t db.Tag
+	err := h.DB.QueryRow(
+		`INSERT INTO tags (user_id, name, color) VALUES (?, ?, ?)
+		 ON CONFLICT(user_id, name) DO UPDATE SET name = excluded.name
+		 RETURNING id, name, color`,
+		db.LocalUserID, name, normalizeColor(req.Color),
+	).Scan(&t.ID, &t.Name, &t.Color)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusCreated, t)
+}
+
+// updateTag renames and/or recolors a tag. Both fields optional via pointers so
+// a recolor needn't resend the name.
+func (h *Handler) updateTag(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+
+	var req struct {
+		Name  *string `json:"name"`
+		Color *string `json:"color"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		badRequest(w, "invalid JSON body")
+		return
+	}
+
+	var namePtr, colorPtr any
+	if req.Name != nil {
+		n := strings.TrimSpace(*req.Name)
+		if n == "" {
+			badRequest(w, "tag name cannot be empty")
+			return
+		}
+		namePtr = n
+	}
+	if req.Color != nil {
+		colorPtr = normalizeColor(*req.Color)
+	}
+
+	res, err := h.DB.Exec(
+		`UPDATE tags
+		    SET name  = COALESCE(?, name),
+		        color = COALESCE(?, color)
+		  WHERE id = ? AND user_id = ?`,
+		namePtr, colorPtr, id, db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFoundMsg(w, "tag not found")
+		return
+	}
+
+	var t db.Tag
+	if err := h.DB.QueryRow(
+		`SELECT id, name, color FROM tags WHERE id = ? AND user_id = ?`,
+		id, db.LocalUserID,
+	).Scan(&t.ID, &t.Name, &t.Color); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, t)
+}
+
+// deleteTag removes a tag; its document assignments cascade away via the FK.
+func (h *Handler) deleteTag(w http.ResponseWriter, r *http.Request) {
+	res, err := h.DB.Exec(
+		`DELETE FROM tags WHERE id = ? AND user_id = ?`,
+		chi.URLParam(r, "id"), db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFoundMsg(w, "tag not found")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// assignTag attaches a tag to a document. Both must belong to the local user;
+// the assignment is idempotent (re-assigning is a no-op, not an error).
+func (h *Handler) assignTag(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+
+	var req struct {
+		TagID string `json:"tag_id"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		badRequest(w, "invalid JSON body")
+		return
+	}
+	if req.TagID == "" {
+		badRequest(w, "tag_id is required")
+		return
+	}
+
+	// Verify both the doc and the tag belong to the user before linking, so a
+	// stray id can't cross-link another account's rows.
+	if !h.ownsDoc(docID) {
+		notFound(w)
+		return
+	}
+	if !h.ownsTag(req.TagID) {
+		notFoundMsg(w, "tag not found")
+		return
+	}
+
+	if _, err := h.DB.Exec(
+		`INSERT INTO document_tags (doc_id, tag_id) VALUES (?, ?)
+		 ON CONFLICT(doc_id, tag_id) DO NOTHING`,
+		docID, req.TagID,
+	); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// unassignTag detaches a tag from a document.
+func (h *Handler) unassignTag(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+	tagID := chi.URLParam(r, "tagId")
+
+	if !h.ownsDoc(docID) {
+		notFound(w)
+		return
+	}
+	if _, err := h.DB.Exec(
+		`DELETE FROM document_tags WHERE doc_id = ? AND tag_id = ?`,
+		docID, tagID,
+	); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// ownsDoc reports whether a document belongs to the local user.
+func (h *Handler) ownsDoc(docID string) bool {
+	var exists bool
+	_ = h.DB.QueryRow(
+		`SELECT EXISTS(SELECT 1 FROM documents WHERE id = ? AND user_id = ?)`,
+		docID, db.LocalUserID,
+	).Scan(&exists)
+	return exists
+}
+
+// ownsTag reports whether a tag belongs to the local user.
+func (h *Handler) ownsTag(tagID string) bool {
+	var exists bool
+	_ = h.DB.QueryRow(
+		`SELECT EXISTS(SELECT 1 FROM tags WHERE id = ? AND user_id = ?)`,
+		tagID, db.LocalUserID,
+	).Scan(&exists)
+	return exists
+}
+
+// tagsByDoc loads the tags for a set of documents in one query and groups them
+// by doc id. Used to decorate the document list and search results without an
+// N+1 of per-doc queries. Returns an empty (non-nil) map when ids is empty.
+func (h *Handler) tagsByDoc(ids []string) (map[string][]db.Tag, error) {
+	out := map[string][]db.Tag{}
+	if len(ids) == 0 {
+		return out, nil
+	}
+
+	// Build the IN (?, ?, …) placeholder list.
+	ph := strings.TrimSuffix(strings.Repeat("?,", len(ids)), ",")
+	args := make([]any, 0, len(ids)+1)
+	for _, id := range ids {
+		args = append(args, id)
+	}
+	args = append(args, db.LocalUserID)
+
+	rows, err := h.DB.Query(
+		`SELECT dt.doc_id, t.id, t.name, t.color
+		   FROM document_tags dt
+		   JOIN tags t ON t.id = dt.tag_id
+		  WHERE dt.doc_id IN (`+ph+`) AND t.user_id = ?
+		  ORDER BY t.name COLLATE NOCASE`,
+		args...,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var docID string
+		var t db.Tag
+		if err := rows.Scan(&docID, &t.ID, &t.Name, &t.Color); err != nil {
+			return nil, err
+		}
+		out[docID] = append(out[docID], t)
+	}
+	return out, rows.Err()
+}

internal/docs/tags_test.go

@@ -0,0 +1,167 @@
+package docs
+
+import (
+	"encoding/json"
+	"net/http"
+	"path/filepath"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// newFullServer mounts the document, tag, and search routers under the same base
+// paths as the real server (/docs, /tags, /search) so tests can exercise the
+// cross-router flows (create a doc, tag it, list, search).
+func newFullServer(t *testing.T) http.Handler {
+	t.Helper()
+	database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { database.Close() })
+
+	h := New(database)
+	r := chi.NewRouter()
+	r.Mount("/docs", h.Routes())
+	r.Mount("/tags", h.TagRoutes())
+	r.Mount("/search", h.SearchRoutes())
+	return r
+}
+
+// createDoc makes a document with the given title/body and returns its id.
+func createDoc(t *testing.T, srv http.Handler, title, text string) string {
+	t.Helper()
+	rec := do(t, srv, http.MethodPost, "/docs", "")
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create doc: %d %s", rec.Code, rec.Body)
+	}
+	var d db.Document
+	_ = json.Unmarshal(rec.Body.Bytes(), &d)
+
+	body, _ := json.Marshal(map[string]any{
+		"title": title, "content": "{}", "content_text": text, "word_count": 1,
+	})
+	rec = do(t, srv, http.MethodPut, "/docs/"+d.ID, string(body))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("save doc: %d %s", rec.Code, rec.Body)
+	}
+	return d.ID
+}
+
+func TestTagLifecycle(t *testing.T) {
+	srv := newFullServer(t)
+
+	// Empty roster serializes as [].
+	rec := do(t, srv, http.MethodGet, "/tags", "")
+	if rec.Code != http.StatusOK || rec.Body.String() == "null\n" {
+		t.Fatalf("empty tags: %d %s", rec.Code, rec.Body)
+	}
+
+	// Create a tag.
+	rec = do(t, srv, http.MethodPost, "/tags", `{"name":"日记","color":"lavender"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create tag: %d %s", rec.Code, rec.Body)
+	}
+	var tag db.Tag
+	_ = json.Unmarshal(rec.Body.Bytes(), &tag)
+	if tag.ID == "" || tag.Name != "日记" || tag.Color != "lavender" {
+		t.Fatalf("bad created tag: %+v", tag)
+	}
+
+	// Re-creating the same name is idempotent (returns the same id, keeps color).
+	rec = do(t, srv, http.MethodPost, "/tags", `{"name":"日记","color":"sky"}`)
+	var again db.Tag
+	_ = json.Unmarshal(rec.Body.Bytes(), &again)
+	if again.ID != tag.ID || again.Color != "lavender" {
+		t.Fatalf("create not idempotent: %+v vs %+v", again, tag)
+	}
+
+	// Unknown color is coerced to rose.
+	rec = do(t, srv, http.MethodPost, "/tags", `{"name":"work","color":"chartreuse"}`)
+	var work db.Tag
+	_ = json.Unmarshal(rec.Body.Bytes(), &work)
+	if work.Color != "rose" {
+		t.Fatalf("unknown color not coerced: %+v", work)
+	}
+
+	// Empty name is rejected.
+	if rec = do(t, srv, http.MethodPost, "/tags", `{"name":"  "}`); rec.Code != http.StatusBadRequest {
+		t.Fatalf("empty name should be 400: %d", rec.Code)
+	}
+
+	// Recolor + rename via PATCH.
+	rec = do(t, srv, http.MethodPatch, "/tags/"+tag.ID, `{"color":"honey"}`)
+	var recolored db.Tag
+	_ = json.Unmarshal(rec.Body.Bytes(), &recolored)
+	if recolored.Color != "honey" || recolored.Name != "日记" {
+		t.Fatalf("patch clobbered/failed: %+v", recolored)
+	}
+
+	// Assign both tags to a document.
+	docID := createDoc(t, srv, "My Journal", "today was a good day")
+	if rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/tags", `{"tag_id":"`+tag.ID+`"}`); rec.Code != http.StatusNoContent {
+		t.Fatalf("assign tag: %d %s", rec.Code, rec.Body)
+	}
+	// Re-assigning is idempotent.
+	if rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/tags", `{"tag_id":"`+tag.ID+`"}`); rec.Code != http.StatusNoContent {
+		t.Fatalf("re-assign tag: %d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/tags", `{"tag_id":"`+work.ID+`"}`); rec.Code != http.StatusNoContent {
+		t.Fatalf("assign 2nd tag: %d", rec.Code)
+	}
+
+	// The doc list now carries both tags, ordered by name.
+	rec = do(t, srv, http.MethodGet, "/docs", "")
+	var docs []docSummary
+	_ = json.Unmarshal(rec.Body.Bytes(), &docs)
+	if len(docs) != 1 || len(docs[0].Tags) != 2 {
+		t.Fatalf("doc list tags: %+v", docs)
+	}
+
+	// Tag list reports doc counts.
+	rec = do(t, srv, http.MethodGet, "/tags", "")
+	var roster []db.Tag
+	_ = json.Unmarshal(rec.Body.Bytes(), &roster)
+	var found bool
+	for _, rt := range roster {
+		if rt.ID == tag.ID {
+			found = true
+			if rt.DocCount != 1 {
+				t.Fatalf("expected doc_count 1, got %d", rt.DocCount)
+			}
+		}
+	}
+	if !found {
+		t.Fatalf("tag missing from roster: %+v", roster)
+	}
+
+	// Unassign one tag.
+	if rec = do(t, srv, http.MethodDelete, "/docs/"+docID+"/tags/"+work.ID, ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("unassign: %d", rec.Code)
+	}
+	rec = do(t, srv, http.MethodGet, "/docs", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &docs)
+	if len(docs[0].Tags) != 1 || docs[0].Tags[0].ID != tag.ID {
+		t.Fatalf("after unassign: %+v", docs[0].Tags)
+	}
+
+	// Deleting a tag cascades its assignments away.
+	if rec = do(t, srv, http.MethodDelete, "/tags/"+tag.ID, ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("delete tag: %d", rec.Code)
+	}
+	rec = do(t, srv, http.MethodGet, "/docs", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &docs)
+	if len(docs[0].Tags) != 0 {
+		t.Fatalf("tag delete did not cascade: %+v", docs[0].Tags)
+	}
+
+	// Assigning a non-existent tag 404s; tagging a non-existent doc 404s.
+	if rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/tags", `{"tag_id":"nope"}`); rec.Code != http.StatusNotFound {
+		t.Fatalf("assign unknown tag: %d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodPost, "/docs/nope/tags", `{"tag_id":"`+work.ID+`"}`); rec.Code != http.StatusNotFound {
+		t.Fatalf("assign to unknown doc: %d", rec.Code)
+	}
+}

internal/docs/versions.go

@@ -0,0 +1,246 @@
+package docs
+
+import (
+	"database/sql"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// Version-history tuning.
+const (
+	// autoSnapshotInterval is the minimum gap between background ('auto')
+	// snapshots. Auto-save fires every ~1.5s; without a floor we'd store a
+	// version per keystroke-burst. A few minutes keeps history useful for
+	// recovery without unbounded growth.
+	autoSnapshotInterval = 3 * time.Minute
+
+	// maxAutoVersions caps how many 'auto' snapshots we retain per document.
+	// 'manual' and 'pre_restore' versions are never pruned — they're explicit
+	// restore points the writer (or a restore) deliberately created.
+	maxAutoVersions = 40
+)
+
+// versionRoutes registers the history endpoints on the docs sub-router. Paths
+// resolve to /api/docs/{id}/versions...
+func (h *Handler) versionRoutes(r chi.Router) {
+	r.Get("/{id}/versions", h.listVersions)
+	r.Post("/{id}/versions", h.createVersion)   // explicit "save a restore point"
+	r.Get("/{id}/versions/{vid}", h.getVersion) // full body for preview
+	r.Post("/{id}/versions/{vid}/restore", h.restoreVersion)
+}
+
+// listVersions returns the document's snapshots, newest first, without the heavy
+// content fields (those load on preview/restore).
+func (h *Handler) listVersions(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+
+	// Scope through the documents table so a snapshot is only visible to the
+	// owner of its parent document.
+	rows, err := h.DB.Query(
+		`SELECT v.id, v.doc_id, v.title, v.word_count, v.kind, v.created_at
+		   FROM document_versions v
+		   JOIN documents d ON d.id = v.doc_id
+		  WHERE v.doc_id = ? AND d.user_id = ?
+		  ORDER BY v.created_at DESC`,
+		docID, db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+
+	out := []db.DocumentVersion{} // non-nil so an empty history serializes as []
+	for rows.Next() {
+		var v db.DocumentVersion
+		if err := rows.Scan(&v.ID, &v.DocID, &v.Title, &v.WordCount, &v.Kind, &v.CreatedAt); err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		out = append(out, v)
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// getVersion returns one snapshot in full (including content) for preview.
+func (h *Handler) getVersion(w http.ResponseWriter, r *http.Request) {
+	v, err := h.fetchVersion(chi.URLParam(r, "id"), chi.URLParam(r, "vid"))
+	if errors.Is(err, sql.ErrNoRows) {
+		notFoundMsg(w, "version not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, v)
+}
+
+// createVersion takes an explicit, user-requested ('manual') restore point from
+// the document's current saved state.
+func (h *Handler) createVersion(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+
+	doc, err := h.fetch(docID)
+	if errors.Is(err, sql.ErrNoRows) {
+		notFound(w)
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	v, err := h.insertVersion(doc, db.VersionKindManual)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusCreated, v)
+}
+
+// restoreVersion copies a snapshot back onto the live document. Before
+// overwriting, it captures the current state as a 'pre_restore' version so the
+// restore is itself undoable. Returns the restored document.
+func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+	vid := chi.URLParam(r, "vid")
+
+	v, err := h.fetchVersion(docID, vid)
+	if errors.Is(err, sql.ErrNoRows) {
+		notFoundMsg(w, "version not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	current, err := h.fetch(docID)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if _, err := h.insertVersion(current, db.VersionKindPreRestore); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	res, err := h.DB.Exec(
+		`UPDATE documents
+		    SET title = ?, content = ?, content_text = ?, word_count = ?,
+		        updated_at = CURRENT_TIMESTAMP
+		  WHERE id = ? AND user_id = ?`,
+		v.Title, v.Content, v.ContentText, v.WordCount, docID, db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFound(w)
+		return
+	}
+
+	doc, err := h.fetch(docID)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, doc)
+}
+
+// maybeAutoSnapshot records a throttled background snapshot of the just-saved
+// document. It no-ops when the newest snapshot is younger than
+// autoSnapshotInterval, or when the body is unchanged since the last snapshot,
+// so an idle or rename-only save costs nothing. Best-effort: callers log but do
+// not fail the save if this errors. Prunes old 'auto' versions on success.
+func (h *Handler) maybeAutoSnapshot(doc db.Document) error {
+	var (
+		lastAt   time.Time
+		lastText string
+		hasPrev  bool
+	)
+	err := h.DB.QueryRow(
+		`SELECT created_at, content_text FROM document_versions
+		  WHERE doc_id = ? ORDER BY created_at DESC LIMIT 1`,
+		doc.ID,
+	).Scan(&lastAt, &lastText)
+	switch {
+	case errors.Is(err, sql.ErrNoRows):
+		hasPrev = false
+	case err != nil:
+		return err
+	default:
+		hasPrev = true
+	}
+
+	if hasPrev {
+		if lastText == doc.ContentText {
+			return nil // nothing meaningful changed
+		}
+		if time.Since(lastAt) < autoSnapshotInterval {
+			return nil // too soon; let edits accumulate
+		}
+	}
+
+	if _, err := h.insertVersion(doc, db.VersionKindAuto); err != nil {
+		return err
+	}
+	return h.pruneAutoVersions(doc.ID)
+}
+
+// insertVersion writes a snapshot row of the given kind and returns it (without
+// the heavy content fields, matching the list shape).
+func (h *Handler) insertVersion(doc db.Document, kind string) (db.DocumentVersion, error) {
+	var v db.DocumentVersion
+	err := h.DB.QueryRow(
+		`INSERT INTO document_versions (doc_id, title, content, content_text, word_count, kind)
+		 VALUES (?, ?, ?, ?, ?, ?)
+		 RETURNING id, doc_id, title, word_count, kind, created_at`,
+		doc.ID, doc.Title, doc.Content, doc.ContentText, doc.WordCount, kind,
+	).Scan(&v.ID, &v.DocID, &v.Title, &v.WordCount, &v.Kind, &v.CreatedAt)
+	return v, err
+}
+
+// pruneAutoVersions trims a document's 'auto' snapshots to the newest
+// maxAutoVersions, leaving 'manual' and 'pre_restore' restore points intact.
+func (h *Handler) pruneAutoVersions(docID string) error {
+	_, err := h.DB.Exec(
+		`DELETE FROM document_versions
+		  WHERE doc_id = ? AND kind = 'auto'
+		    AND id NOT IN (
+		        SELECT id FROM document_versions
+		         WHERE doc_id = ? AND kind = 'auto'
+		         ORDER BY created_at DESC LIMIT ?
+		    )`,
+		docID, docID, maxAutoVersions,
+	)
+	return err
+}
+
+// fetchVersion loads one full snapshot, scoped to its owner via the parent doc.
+func (h *Handler) fetchVersion(docID, vid string) (db.DocumentVersion, error) {
+	var v db.DocumentVersion
+	err := h.DB.QueryRow(
+		`SELECT v.id, v.doc_id, v.title, v.content, v.content_text, v.word_count, v.kind, v.created_at
+		   FROM document_versions v
+		   JOIN documents d ON d.id = v.doc_id
+		  WHERE v.id = ? AND v.doc_id = ? AND d.user_id = ?`,
+		vid, docID, db.LocalUserID,
+	).Scan(
+		&v.ID, &v.DocID, &v.Title, &v.Content, &v.ContentText,
+		&v.WordCount, &v.Kind, &v.CreatedAt,
+	)
+	return v, err
+}

internal/docs/versions_test.go

@@ -0,0 +1,107 @@
+package docs
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// newDoc creates a document and returns its id.
+func newDoc(t *testing.T, srv http.Handler) string {
+	t.Helper()
+	rec := do(t, srv, http.MethodPost, "/", "")
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create doc: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var d db.Document
+	if err := json.Unmarshal(rec.Body.Bytes(), &d); err != nil {
+		t.Fatalf("decode doc: %v", err)
+	}
+	return d.ID
+}
+
+func listVersions(t *testing.T, srv http.Handler, id string) []db.DocumentVersion {
+	t.Helper()
+	rec := do(t, srv, http.MethodGet, "/"+id+"/versions", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("list versions: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var vs []db.DocumentVersion
+	if err := json.Unmarshal(rec.Body.Bytes(), &vs); err != nil {
+		t.Fatalf("decode versions: %v", err)
+	}
+	return vs
+}
+
+func TestVersionLifecycle(t *testing.T) {
+	srv := newTestServer(t)
+	id := newDoc(t, srv)
+
+	// A bare rename (no content) must not snapshot.
+	do(t, srv, http.MethodPut, "/"+id, `{"title":"Just A Name"}`)
+	if vs := listVersions(t, srv, id); len(vs) != 0 {
+		t.Fatalf("rename should not snapshot, got %d", len(vs))
+	}
+
+	// First real body save takes one auto snapshot (no prior version to throttle).
+	body := `{"content":"{\"type\":\"doc\"}","content_text":"first draft","word_count":2}`
+	do(t, srv, http.MethodPut, "/"+id, body)
+	vs := listVersions(t, srv, id)
+	if len(vs) != 1 || vs[0].Kind != db.VersionKindAuto {
+		t.Fatalf("expected 1 auto version, got %+v", vs)
+	}
+	// List view omits heavy content fields.
+	if vs[0].Content != "" {
+		t.Fatalf("list should omit content, got %q", vs[0].Content)
+	}
+
+	// A near-immediate second save is throttled (no new auto version).
+	do(t, srv, http.MethodPut, "/"+id, `{"content":"{\"type\":\"doc\"}","content_text":"first draft v2","word_count":3}`)
+	if vs := listVersions(t, srv, id); len(vs) != 1 {
+		t.Fatalf("second save within interval should be throttled, got %d", len(vs))
+	}
+
+	// Manual snapshot always records, capturing current saved state.
+	rec := do(t, srv, http.MethodPost, "/"+id+"/versions", "")
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("manual snapshot: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var manual db.DocumentVersion
+	_ = json.Unmarshal(rec.Body.Bytes(), &manual)
+	if manual.Kind != db.VersionKindManual {
+		t.Fatalf("expected manual kind, got %q", manual.Kind)
+	}
+
+	// Mutate the live doc, then restore the manual snapshot.
+	do(t, srv, http.MethodPut, "/"+id, `{"content":"{\"type\":\"doc\"}","content_text":"ruined everything","word_count":2}`)
+	rec = do(t, srv, http.MethodPost, "/"+id+"/versions/"+manual.ID+"/restore", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("restore: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var restored db.Document
+	_ = json.Unmarshal(rec.Body.Bytes(), &restored)
+	if restored.ContentText != "first draft v2" {
+		t.Fatalf("restore did not bring back snapshot text: %q", restored.ContentText)
+	}
+
+	// Restore left a pre_restore safety copy, so the bad state is itself recoverable.
+	var foundPreRestore bool
+	for _, v := range listVersions(t, srv, id) {
+		if v.Kind == db.VersionKindPreRestore {
+			foundPreRestore = true
+		}
+	}
+	if !foundPreRestore {
+		t.Fatal("restore should record a pre_restore safety snapshot")
+	}
+}
+
+func TestVersionNotFound(t *testing.T) {
+	srv := newTestServer(t)
+	id := newDoc(t, srv)
+	if rec := do(t, srv, http.MethodGet, "/"+id+"/versions/nope", ""); rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404 for unknown version, got %d", rec.Code)
+	}
+}

internal/httputil/json.go

@@ -0,0 +1,37 @@
+// Package httputil holds the small HTTP response helpers shared by every API
+// handler package (docs, suggestions, vocab, …). Keeping them in one place means
+// JSON encoding and — crucially — error handling behave identically everywhere:
+// internal errors are logged in full but never leaked to the client.
+package httputil
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+)
+
+// WriteJSON encodes v as the response body with the given status code.
+func WriteJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// ErrorJSON sends a {"error": msg} body with the given status. The message is
+// caller-chosen and safe to show the client.
+func ErrorJSON(w http.ResponseWriter, status int, msg string) {
+	WriteJSON(w, status, map[string]string{"error": msg})
+}
+
+// BadRequest is the common 400 shorthand.
+func BadRequest(w http.ResponseWriter, msg string) {
+	ErrorJSON(w, http.StatusBadRequest, msg)
+}
+
+// ServerError logs the real error (with full detail, for the operator) and
+// returns a generic 500 to the client — raw database/internal errors must never
+// reach the browser, where they leak schema and implementation details.
+func ServerError(w http.ResponseWriter, err error) {
+	log.Printf("internal error: %v", err)
+	ErrorJSON(w, http.StatusInternalServerError, "something went wrong")
+}

internal/images/handler.go

@@ -0,0 +1,132 @@
+// Package images implements a tiny content-addressed image store: writers upload
+// images from the editor, they're saved to disk under the configured directory,
+// and served back by hashed filename. Content addressing means the same image
+// pasted twice is stored once, and URLs are stable and cacheable forever.
+package images
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// maxUploadBytes caps a single image at 10 MiB — generous for a writing tool,
+// small enough to keep a careless paste from filling the disk.
+const maxUploadBytes = 10 << 20
+
+// extByContentType maps the image types we accept to a canonical extension. The
+// allowlist doubles as validation: anything not here is rejected.
+var extByContentType = map[string]string{
+	"image/png":     ".png",
+	"image/jpeg":    ".jpg",
+	"image/gif":     ".gif",
+	"image/webp":    ".webp",
+	"image/svg+xml": ".svg",
+}
+
+// Handler serves the upload + fetch endpoints, backed by a directory on disk.
+type Handler struct {
+	dir string
+}
+
+// New constructs a Handler, ensuring the storage directory exists.
+func New(dir string) (*Handler, error) {
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return nil, err
+	}
+	return &Handler{dir: dir}, nil
+}
+
+// Routes mounts the image endpoints. Mount under "/images" so the full paths are
+// POST /api/images (upload) and GET /api/images/{name} (fetch).
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Post("/", h.upload)
+	r.Get("/{name}", h.serve)
+	return r
+}
+
+// upload accepts a single multipart "image" field, sniffs and validates its
+// type, and writes it under a content hash so identical images dedupe. Responds
+// with the served URL the editor inserts.
+func (h *Handler) upload(w http.ResponseWriter, r *http.Request) {
+	r.Body = http.MaxBytesReader(w, r.Body, maxUploadBytes)
+	file, _, err := r.FormFile("image")
+	if err != nil {
+		http.Error(w, "expected an 'image' file field", http.StatusBadRequest)
+		return
+	}
+	defer file.Close()
+
+	data, err := io.ReadAll(file)
+	if err != nil {
+		http.Error(w, "could not read upload", http.StatusBadRequest)
+		return
+	}
+
+	// Trust a sniff over the client-declared type. SVG isn't reliably sniffable
+	// (DetectContentType returns text/plain or text/xml), so fall back to a
+	// lightweight tag check for it.
+	ct := http.DetectContentType(data)
+	ext, ok := extByContentType[ct]
+	if !ok {
+		if looksLikeSVG(data) {
+			ext, ok = ".svg", true
+		}
+	}
+	if !ok {
+		http.Error(w, "unsupported image type", http.StatusUnsupportedMediaType)
+		return
+	}
+
+	sum := sha256.Sum256(data)
+	name := hex.EncodeToString(sum[:])[:32] + ext
+	path := filepath.Join(h.dir, name)
+
+	// Skip the write if this exact content is already stored.
+	if _, statErr := os.Stat(path); errors.Is(statErr, os.ErrNotExist) {
+		if err := os.WriteFile(path, data, 0o644); err != nil {
+			http.Error(w, "could not store image", http.StatusInternalServerError)
+			return
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]string{"url": "/api/images/" + name})
+}
+
+// serve returns a stored image by its hashed filename. The filename is validated
+// to be a bare name (no path separators) so it can't escape the storage dir, and
+// served with a long-lived cache header since content-addressed URLs never change.
+func (h *Handler) serve(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	if name == "" || name != filepath.Base(name) || strings.ContainsAny(name, `/\`) {
+		http.NotFound(w, r)
+		return
+	}
+	path := filepath.Join(h.dir, filepath.Base(name))
+	if _, err := os.Stat(path); err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	http.ServeFile(w, r, path)
+}
+
+// looksLikeSVG does a cheap check for an <svg root tag near the start of the
+// file, since DetectContentType doesn't recognize SVG.
+func looksLikeSVG(data []byte) bool {
+	head := data
+	if len(head) > 512 {
+		head = head[:512]
+	}
+	return strings.Contains(strings.ToLower(string(head)), "<svg")
+}

internal/images/handler_test.go

@@ -0,0 +1,97 @@
+package images
+
+import (
+	"bytes"
+	"encoding/json"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// a 1x1 transparent PNG.
+var pngBytes = []byte{
+	0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+	0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
+	0x89, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x62, 0x00, 0x01, 0x00, 0x00,
+	0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae,
+	0x42, 0x60, 0x82,
+}
+
+func uploadReq(t *testing.T, field string, data []byte) *http.Request {
+	t.Helper()
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	fw, err := mw.CreateFormFile(field, "x.png")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fw.Write(data)
+	mw.Close()
+	req := httptest.NewRequest(http.MethodPost, "/", &buf)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	return req
+}
+
+func TestUploadAndServe(t *testing.T) {
+	h, err := New(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := h.Routes()
+
+	// Upload a PNG → expect a JSON url under /api/images/.
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, uploadReq(t, "image", pngBytes))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("upload code=%d body=%s", rec.Code, rec.Body)
+	}
+	var resp struct{ URL string }
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(resp.URL, "/api/images/") || !strings.HasSuffix(resp.URL, ".png") {
+		t.Fatalf("unexpected url %q", resp.URL)
+	}
+
+	// The same content uploaded again dedupes to the same URL.
+	rec2 := httptest.NewRecorder()
+	r.ServeHTTP(rec2, uploadReq(t, "image", pngBytes))
+	var resp2 struct{ URL string }
+	json.Unmarshal(rec2.Body.Bytes(), &resp2)
+	if resp2.URL != resp.URL {
+		t.Fatalf("expected dedup to same url, got %q vs %q", resp2.URL, resp.URL)
+	}
+
+	// Fetch it back.
+	name := strings.TrimPrefix(resp.URL, "/api/images/")
+	rec3 := httptest.NewRecorder()
+	r.ServeHTTP(rec3, httptest.NewRequest(http.MethodGet, "/"+name, nil))
+	if rec3.Code != http.StatusOK {
+		t.Fatalf("serve code=%d", rec3.Code)
+	}
+	if !bytes.Equal(rec3.Body.Bytes(), pngBytes) {
+		t.Fatal("served bytes differ from uploaded")
+	}
+}
+
+func TestUploadRejectsNonImage(t *testing.T) {
+	h, _ := New(t.TempDir())
+	r := h.Routes()
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, uploadReq(t, "image", []byte("this is plainly not an image at all")))
+	if rec.Code != http.StatusUnsupportedMediaType {
+		t.Fatalf("expected 415, got %d", rec.Code)
+	}
+}
+
+func TestServeMissing(t *testing.T) {
+	h, _ := New(t.TempDir())
+	r := h.Routes()
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/deadbeef.png", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", rec.Code)
+	}
+}

internal/lexicon/data.go

@@ -0,0 +1,38 @@
+// Package lexicon serves offline word lookups — a Chinese gloss, a definition,
+// and a list of synonyms for a single word — from public datasets compiled into
+// the binary. Definitions come from the Wordset dictionary (modern, concise
+// glosses with a part of speech and example, which read kindly for an ESL
+// writer); synonyms come from the Moby Thesaurus; the Chinese gloss comes from
+// ECDICT. All are gzipped JSON, decompressed lazily on first use so a writer who
+// never looks up a word pays nothing.
+package lexicon
+
+import _ "embed"
+
+// definitionsGz is the gzipped Wordset definitions map: word → [[pos, def,
+// example], …], lowercase keys. Built by the data-prep step (see commit notes).
+//
+//go:embed data/definitions.json.gz
+var definitionsGz []byte
+
+// synonymsGz is the gzipped Moby thesaurus map: headword → [synonym, …],
+// lowercase keys, capped per word to keep the popover (and the binary) small.
+//
+//go:embed data/synonyms.json.gz
+var synonymsGz []byte
+
+// glossGz is the gzipped English→Chinese gloss map: word → 中文 gloss, lowercase
+// keys. Built from ECDICT (scripts/build_gloss.py), filtered to common words so
+// an ESL writer who speaks Mandarin gets an instant translation on hover/lookup.
+//
+//go:embed data/gloss.json.gz
+var glossGz []byte
+
+// phoneticGz is the gzipped English-phonetic map: word → IPA, lowercase keys.
+// Built from ECDICT's phonetic column (scripts/build_phonetic.py). Shown beside
+// the read-aloud button so the writer — a Mandarin speaker learning English —
+// can see how to say the word. Ships with a small common-word seed; a full build
+// broadens coverage.
+//
+//go:embed data/phonetic.json.gz
+var phoneticGz []byte

internal/lexicon/handlers.go

@@ -0,0 +1,81 @@
+package lexicon
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// Handler serves the word-lookup endpoint backed by a single shared Lexicon.
+type Handler struct {
+	Lex *Lexicon
+}
+
+// New constructs a Handler with a fresh (lazily-loaded) Lexicon.
+func NewHandler() *Handler { return &Handler{Lex: New()} }
+
+// Routes returns the router mounted at /api/word. The word is a path segment so
+// "/api/word/happy" reads naturally; it's URL-decoded to tolerate the rare
+// punctuated token.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/{word}", h.lookup)
+	return r
+}
+
+// GlossRoutes returns the router mounted at /api/gloss — the lightweight
+// Chinese-only lookup behind the inline hover/select gloss. It shares the
+// Handler's Lexicon, so the datasets still load just once.
+func (h *Handler) GlossRoutes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/{word}", h.gloss)
+	return r
+}
+
+// lookup returns the definition + synonyms for one word. A word found in neither
+// dataset still returns 200 with empty lists, so the popover can show a friendly
+// "nothing found" rather than an error state.
+func (h *Handler) lookup(w http.ResponseWriter, r *http.Request) {
+	word := chi.URLParam(r, "word")
+	if decoded, err := url.PathUnescape(word); err == nil {
+		word = decoded
+	}
+
+	res, err := h.Lex.Lookup(word)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		_ = json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	// Word lookups are static for the life of the build; let the browser cache
+	// them so repeated right-clicks on the same word are instant.
+	w.Header().Set("Cache-Control", "public, max-age=86400")
+	_ = json.NewEncoder(w).Encode(res)
+}
+
+// gloss returns just the Chinese translation for one word. Like lookup, a miss
+// is a 200 with an empty gloss so the hover tooltip can quietly skip rather than
+// error.
+func (h *Handler) gloss(w http.ResponseWriter, r *http.Request) {
+	word := chi.URLParam(r, "word")
+	if decoded, err := url.PathUnescape(word); err == nil {
+		word = decoded
+	}
+
+	res, err := h.Lex.Gloss(word)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		_ = json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "public, max-age=86400")
+	_ = json.NewEncoder(w).Encode(res)
+}

internal/lexicon/lexicon.go

@@ -0,0 +1,258 @@
+package lexicon
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+	"sync"
+)
+
+// Meaning is one sense of a word: its part of speech, the gloss, and an optional
+// usage example. The frontend renders a few of these in the word popover.
+type Meaning struct {
+	PartOfSpeech string `json:"part_of_speech"`
+	Definition   string `json:"definition"`
+	Example      string `json:"example,omitempty"`
+}
+
+// Result is the full lookup for one word. Either list may be empty (the word
+// isn't a headword in that dataset); the frontend handles a partial or empty
+// result gracefully. Gloss is the Chinese translation (empty when the word isn't
+// in the gloss dataset) — shown first in the popover for the Mandarin-speaking
+// writer.
+type Result struct {
+	Word        string    `json:"word"`
+	Gloss       string    `json:"gloss"`
+	Phonetic    string    `json:"phonetic"` // IPA for the English word; "" when absent
+	Definitions []Meaning `json:"definitions"`
+	Synonyms    []string  `json:"synonyms"`
+}
+
+// GlossResult is the lightweight payload for the inline hover/select gloss: just
+// the word and its Chinese translation, no definitions or synonyms. Kept small
+// so the hover tooltip is instant and trivially cacheable.
+type GlossResult struct {
+	Word  string `json:"word"`
+	Gloss string `json:"gloss"`
+}
+
+// maxSynonyms caps how many synonyms we hand the popover, even though the dataset
+// stores up to ~50 per word — a long flat wall of words overwhelms more than it
+// helps, especially for an ESL reader scanning for the right fit.
+const maxSynonyms = 16
+
+// maxDefinitions caps the senses shown so the popover stays a glance, not an
+// essay.
+const maxDefinitions = 4
+
+// Lexicon holds the lazily-loaded datasets. The maps are populated once, on the
+// first Lookup, behind a sync.Once so startup stays instant and a load error is
+// remembered rather than retried on every request.
+type Lexicon struct {
+	once     sync.Once
+	loadErr  error
+	defs     map[string][][]string // word → [[pos, def, example], …]
+	synonyms map[string][]string   // word → [synonym, …]
+	gloss    map[string]string     // word → Chinese gloss
+	phonetic map[string]string     // word → IPA
+}
+
+// New returns a Lexicon. The datasets aren't read until the first Lookup.
+func New() *Lexicon { return &Lexicon{} }
+
+func (l *Lexicon) load() {
+	l.once.Do(func() {
+		if err := gunzipJSON(definitionsGz, &l.defs); err != nil {
+			l.loadErr = fmt.Errorf("load definitions: %w", err)
+			return
+		}
+		if err := gunzipJSON(synonymsGz, &l.synonyms); err != nil {
+			l.loadErr = fmt.Errorf("load synonyms: %w", err)
+			return
+		}
+		if err := gunzipJSON(glossGz, &l.gloss); err != nil {
+			l.loadErr = fmt.Errorf("load gloss: %w", err)
+			return
+		}
+		if err := gunzipJSON(phoneticGz, &l.phonetic); err != nil {
+			l.loadErr = fmt.Errorf("load phonetic: %w", err)
+			return
+		}
+	})
+}
+
+// Lookup returns the definition senses and synonyms for word. It first tries the
+// word as written (lowercased), then a few simple morphological reductions
+// (plurals, -ed/-ing/-ly) so "running" or "happily" still resolve. A word found
+// in neither dataset yields a Result with empty lists (not an error).
+func (l *Lexicon) Lookup(word string) (Result, error) {
+	l.load()
+	if l.loadErr != nil {
+		return Result{}, l.loadErr
+	}
+
+	norm := strings.ToLower(strings.TrimSpace(word))
+	res := Result{Word: word, Definitions: []Meaning{}, Synonyms: []string{}}
+	if norm == "" {
+		return res, nil
+	}
+
+	res.Gloss = lookupGloss(l.gloss, norm)
+	// Phonetic is a word→string map like the gloss, so the same de-inflecting
+	// candidate walk resolves "running" → "run", etc.
+	res.Phonetic = lookupGloss(l.phonetic, norm)
+
+	if raw := lookupDefs(l.defs, norm); raw != nil {
+		for _, m := range raw {
+			res.Definitions = append(res.Definitions, toMeaning(m))
+			if len(res.Definitions) >= maxDefinitions {
+				break
+			}
+		}
+	}
+
+	if syns := lookupSyns(l.synonyms, norm); syns != nil {
+		if len(syns) > maxSynonyms {
+			syns = syns[:maxSynonyms]
+		}
+		res.Synonyms = append(res.Synonyms, syns...)
+	}
+
+	return res, nil
+}
+
+// Gloss returns just the Chinese translation for word (empty when absent). This
+// is the fast path behind the inline hover/select gloss — it skips the
+// definition and synonym datasets entirely.
+func (l *Lexicon) Gloss(word string) (GlossResult, error) {
+	l.load()
+	if l.loadErr != nil {
+		return GlossResult{}, l.loadErr
+	}
+	norm := strings.ToLower(strings.TrimSpace(word))
+	return GlossResult{Word: word, Gloss: lookupGloss(l.gloss, norm)}, nil
+}
+
+// lookupGloss walks the candidate forms of a word and returns the first gloss
+// hit (so "running"/"studies" resolve via the same de-inflection as defs/syns).
+func lookupGloss(m map[string]string, word string) string {
+	if word == "" {
+		return ""
+	}
+	for _, c := range candidates(word) {
+		if v, ok := m[c]; ok {
+			return v
+		}
+	}
+	return ""
+}
+
+// lookupDefs / lookupSyns walk the candidate forms of a word and return the
+// first dataset hit. They're separate (rather than a generic helper) only
+// because the two maps have different value types.
+func lookupDefs(m map[string][][]string, word string) [][]string {
+	for _, c := range candidates(word) {
+		if v, ok := m[c]; ok {
+			return v
+		}
+	}
+	return nil
+}
+
+func lookupSyns(m map[string][]string, word string) []string {
+	for _, c := range candidates(word) {
+		if v, ok := m[c]; ok {
+			return v
+		}
+	}
+	return nil
+}
+
+// candidates returns the lemma forms to try, in priority order: the word itself,
+// then conservative de-inflections. This is deliberately lightweight — a full
+// stemmer would over-reduce ("business" → "busy") and surface wrong entries; a
+// handful of common English suffix rules covers the everyday cases without a
+// dependency. Duplicates are fine (map lookup is cheap); order is what matters.
+func candidates(word string) []string {
+	out := []string{word}
+	add := func(s string) {
+		if len(s) >= 2 && s != word {
+			out = append(out, s)
+		}
+	}
+
+	switch {
+	case strings.HasSuffix(word, "ies"): // studies → study
+		add(word[:len(word)-3] + "y")
+	case strings.HasSuffix(word, "es"): // boxes → box, wishes → wish
+		add(word[:len(word)-2])
+		add(word[:len(word)-1])
+	case strings.HasSuffix(word, "s"): // cats → cat
+		add(word[:len(word)-1])
+	}
+
+	if strings.HasSuffix(word, "ing") { // running → run, making → make
+		stem := word[:len(word)-3]
+		add(stem)
+		add(stem + "e")
+		add(undouble(stem))
+	}
+	if strings.HasSuffix(word, "ed") { // hoped → hope, stopped → stop
+		stem := word[:len(word)-2]
+		add(stem)
+		add(word[:len(word)-1])
+		add(undouble(stem))
+	}
+	if strings.HasSuffix(word, "ly") { // happily handled above via ies path? no — quickly → quick
+		add(word[:len(word)-2])
+	}
+	if strings.HasSuffix(word, "ily") { // happily → happy
+		add(word[:len(word)-3] + "y")
+	}
+
+	return out
+}
+
+// undouble collapses a doubled final consonant (stopp → stop, runn → run) so the
+// -ed/-ing stems of doubled-consonant verbs resolve to their base form.
+func undouble(stem string) string {
+	n := len(stem)
+	if n >= 2 && stem[n-1] == stem[n-2] {
+		return stem[:n-1]
+	}
+	return stem
+}
+
+// toMeaning maps a compact [pos, def, example] triple from the dataset onto the
+// JSON-friendly Meaning. The dataset always stores three elements, but we guard
+// the length so a malformed row can't panic.
+func toMeaning(m []string) Meaning {
+	var out Meaning
+	if len(m) > 0 {
+		out.PartOfSpeech = m[0]
+	}
+	if len(m) > 1 {
+		out.Definition = m[1]
+	}
+	if len(m) > 2 {
+		out.Example = m[2]
+	}
+	return out
+}
+
+// gunzipJSON decompresses gz and decodes the JSON into v.
+func gunzipJSON(gz []byte, v any) error {
+	r, err := gzip.NewReader(bytes.NewReader(gz))
+	if err != nil {
+		return err
+	}
+	defer r.Close()
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(data, v)
+}

internal/lexicon/lexicon_test.go

@@ -0,0 +1,118 @@
+package lexicon
+
+import "testing"
+
+func TestLookupKnownWord(t *testing.T) {
+	l := New()
+	res, err := l.Lookup("happy")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if len(res.Definitions) == 0 {
+		t.Errorf("expected definitions for %q, got none", "happy")
+	}
+	if len(res.Synonyms) == 0 {
+		t.Errorf("expected synonyms for %q, got none", "happy")
+	}
+	if len(res.Synonyms) > maxSynonyms {
+		t.Errorf("synonyms not capped: got %d, want <= %d", len(res.Synonyms), maxSynonyms)
+	}
+	if len(res.Definitions) > maxDefinitions {
+		t.Errorf("definitions not capped: got %d, want <= %d", len(res.Definitions), maxDefinitions)
+	}
+}
+
+func TestLookupMorphology(t *testing.T) {
+	l := New()
+	// Inflected forms should resolve to their base entry via candidates().
+	for _, w := range []string{"running", "studies", "boxes", "quickly", "stopped"} {
+		res, err := l.Lookup(w)
+		if err != nil {
+			t.Fatalf("Lookup(%q): %v", w, err)
+		}
+		if len(res.Definitions) == 0 && len(res.Synonyms) == 0 {
+			t.Errorf("expected some result for inflected %q, got nothing", w)
+		}
+	}
+}
+
+func TestLookupUnknownWord(t *testing.T) {
+	l := New()
+	res, err := l.Lookup("zzzxqqq")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if len(res.Definitions) != 0 || len(res.Synonyms) != 0 {
+		t.Errorf("expected empty result for nonsense word, got %+v", res)
+	}
+	// Empty result must still serialize as [] not null for the frontend.
+	if res.Definitions == nil || res.Synonyms == nil {
+		t.Errorf("empty slices must be non-nil for JSON []: %+v", res)
+	}
+}
+
+func TestGloss(t *testing.T) {
+	l := New()
+	// A common word carries a Chinese gloss...
+	res, err := l.Gloss("river")
+	if err != nil {
+		t.Fatalf("Gloss: %v", err)
+	}
+	if res.Word != "river" {
+		t.Errorf("Word = %q, want %q", res.Word, "river")
+	}
+	if res.Gloss == "" {
+		t.Errorf("expected a Chinese gloss for %q, got none", "river")
+	}
+	// ...and the inflected form resolves via the same de-inflection.
+	inflected, err := l.Gloss("rivers")
+	if err != nil {
+		t.Fatalf("Gloss(rivers): %v", err)
+	}
+	if inflected.Gloss == "" {
+		t.Errorf("expected a gloss for inflected %q, got none", "rivers")
+	}
+	// A nonsense word is a clean empty (not an error).
+	miss, err := l.Gloss("zzzxqqq")
+	if err != nil {
+		t.Fatalf("Gloss(miss): %v", err)
+	}
+	if miss.Gloss != "" {
+		t.Errorf("expected empty gloss for nonsense word, got %q", miss.Gloss)
+	}
+}
+
+func TestLookupIncludesGloss(t *testing.T) {
+	l := New()
+	res, err := l.Lookup("happy")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if res.Gloss == "" {
+		t.Errorf("expected Lookup to include a Chinese gloss for %q", "happy")
+	}
+}
+
+func TestCandidates(t *testing.T) {
+	cases := map[string]string{
+		"cats":    "cat",
+		"studies": "study",
+		"running": "run",
+		"hoped":   "hope",
+		"quickly": "quick",
+		"happily": "happy",
+	}
+	for word, want := range cases {
+		got := candidates(word)
+		found := false
+		for _, c := range got {
+			if c == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("candidates(%q) = %v, missing expected base %q", word, got, want)
+		}
+	}
+}

internal/llm/chat.go

@@ -0,0 +1,29 @@
+package llm
+
+import "context"
+
+// AskPetalMessages assembles the message array for one Ask Petal turn: the
+// suggestion-context system prompt followed by the (length-capped) client-side
+// conversation history. The backend is stateless, so the full history rides on
+// every request (spec: no server-side sessions).
+func AskPetalMessages(systemPrompt string, history []Message) []Message {
+	msgs := make([]Message, 0, len(history)+1)
+	msgs = append(msgs, Message{Role: "system", Content: systemPrompt})
+	msgs = append(msgs, TrimHistory(history)...)
+	return msgs
+}
+
+// StreamAskPetal opens an SSE-friendly token stream for an Ask Petal reply using
+// the conversational sampling parameters from the spec. The caller forwards the
+// returned chunks to the browser; the channel closes when generation ends.
+func StreamAskPetal(ctx context.Context, client LLMClient, systemPrompt string, history []Message) (<-chan string, error) {
+	return client.Stream(ctx, CompletionRequest{
+		Messages:          AskPetalMessages(systemPrompt, history),
+		MaxTokens:         512,
+		Temperature:       0.7,
+		RepetitionPenalty: 1.15,
+		TopP:              0.92,
+		Stop:              []string{"\n\n\n"},
+		Stream:            true,
+	})
+}

internal/llm/checkpoint.go

@@ -0,0 +1,232 @@
+package llm
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+// CheckpointInterval is the minimum time between grammar checkpoints for a
+// single document. The frontend debounces at 4s; this is the server-side floor
+// that protects the inference endpoint from rapid repeat checks.
+const CheckpointInterval = 30 * time.Second
+
+// checkpointMaxTokens caps the checkpoint's generated output. Each suggestion
+// echoes its original sentence, a replacement, and a friendly explanation, so
+// the full JSON for the prompt's "up to 5 issues" runs ~2,000 tokens on a long
+// document (measured ~2,007 for a 380-word doc). The old 1,024 cap truncated
+// the JSON mid-array — done_reason "length" — leaving an object that never
+// closed, so ParseCheckpoint found no parseable JSON and the pass 502'd on
+// every long doc. This is a ceiling, not a target: the model stops at its JSON
+// close well before it, so the headroom costs nothing on shorter docs.
+const checkpointMaxTokens = 4096
+
+// RawSuggestion is one item as the model emits it. Positions are resolved
+// server-side from Original; the frontend re-anchors by string at render time.
+type RawSuggestion struct {
+	Original    string `json:"original"`
+	Replacement string `json:"replacement"`
+	Explanation string `json:"explanation"`
+	Type        string `json:"type"`
+}
+
+// checkpointResponse is the top-level JSON shape the checkpoint prompt requests.
+type checkpointResponse struct {
+	Suggestions []RawSuggestion `json:"suggestions"`
+}
+
+// RunCheckpoint sends the grammar checkpoint and parses the JSON result. It
+// applies the latency-guard truncation and the checkpoint sampling parameters
+// from the spec.
+func RunCheckpoint(ctx context.Context, client LLMClient, contentText, tone string) ([]RawSuggestion, error) {
+	raw, err := client.Complete(ctx, CompletionRequest{
+		Messages:          CheckpointMessages(TruncateDoc(contentText), tone),
+		MaxTokens:         checkpointMaxTokens,
+		Temperature:       0.3,
+		RepetitionPenalty: 1.15,
+		TopP:              0.9,
+		Stop:              []string{"```", "\n\n\n\n"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ParseCheckpoint(raw)
+}
+
+// ParseCheckpoint extracts the suggestions array from a model response. Smaller
+// models sometimes wrap JSON in prose or markdown fences despite instructions,
+// so we salvage the outermost {...} object before decoding. When the model
+// truncates mid-array (it ran out of output budget) the outer object never
+// closes and won't parse — we then recover the suggestion objects that *did*
+// complete, so a long document still gets feedback instead of a hard failure.
+func ParseCheckpoint(raw string) ([]RawSuggestion, error) {
+	var suggestions []RawSuggestion
+	parsed := false
+	if jsonText := extractJSONObject(raw); jsonText != "" {
+		var resp checkpointResponse
+		if err := json.Unmarshal([]byte(jsonText), &resp); err == nil {
+			suggestions = resp.Suggestions
+			parsed = true
+		}
+	}
+	if !parsed {
+		// No closeable object, or it failed to decode (most often a truncated
+		// array). Salvage the individual suggestion objects that completed.
+		suggestions = salvageSuggestions(raw)
+		if suggestions == nil {
+			return nil, fmt.Errorf("checkpoint: no JSON object in model output: %q", truncateForError(raw))
+		}
+	}
+	// Drop items the model returned with an empty original — they can't be
+	// anchored — and normalize whitespace the model may have echoed.
+	out := suggestions[:0]
+	for _, s := range suggestions {
+		s.Original = strings.TrimSpace(s.Original)
+		s.Replacement = strings.TrimSpace(s.Replacement)
+		if s.Original == "" {
+			continue
+		}
+		// Drop no-ops: the model sometimes "flags" a correct sentence and echoes
+		// it verbatim as the replacement, producing a card whose before/after are
+		// identical and whose explanation says it's already fine — a suggestion
+		// that suggests nothing. Awareness-only families (voice) carry an empty
+		// replacement, so this only ever fires on the edit families.
+		if s.Replacement != "" && s.Original == s.Replacement {
+			continue
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// salvageSuggestions recovers as many complete suggestion objects as it can from
+// a response whose top-level JSON didn't parse — typically one truncated mid
+// "suggestions" array. It scans the array region for brace-balanced {...}
+// objects and keeps each that decodes into a RawSuggestion with a non-empty
+// original; the final, cut-off object simply never balances and is dropped.
+// Returns nil when there is no salvageable array (so the caller can error).
+func salvageSuggestions(raw string) []RawSuggestion {
+	key := strings.Index(raw, `"suggestions"`)
+	if key < 0 {
+		return nil
+	}
+	lb := strings.IndexByte(raw[key:], '[')
+	if lb < 0 {
+		return nil
+	}
+	rest := raw[key+lb+1:]
+	out := []RawSuggestion{}
+	for {
+		obj, end := firstBalancedObject(rest)
+		if end < 0 {
+			break
+		}
+		var s RawSuggestion
+		if err := json.Unmarshal([]byte(obj), &s); err == nil && strings.TrimSpace(s.Original) != "" {
+			out = append(out, s)
+		}
+		rest = rest[end:]
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// extractJSONObject returns the substring from the first '{' to its matching
+// closing '}', or "" if none. Tolerates fences/preamble around the object.
+func extractJSONObject(s string) string {
+	obj, _ := firstBalancedObject(s)
+	return obj
+}
+
+// firstBalancedObject returns the first brace-balanced {...} substring in s and
+// the index in s just past its closing brace, or ("", -1) if no object closes
+// (none present, or the only one is truncated). String contents — including
+// braces inside quoted values — are skipped so they can't unbalance the count.
+func firstBalancedObject(s string) (string, int) {
+	start := strings.IndexByte(s, '{')
+	if start < 0 {
+		return "", -1
+	}
+	depth := 0
+	inString := false
+	escaped := false
+	for i := start; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case escaped:
+			escaped = false
+		case c == '\\' && inString:
+			escaped = true
+		case c == '"':
+			inString = !inString
+		case inString:
+			// ignore braces inside strings
+		case c == '{':
+			depth++
+		case c == '}':
+			depth--
+			if depth == 0 {
+				return s[start : i+1], i + 1
+			}
+		}
+	}
+	return "", -1
+}
+
+func truncateForError(s string) string {
+	const max = 200
+	if len(s) > max {
+		return s[:max] + "…"
+	}
+	return s
+}
+
+// RateLimiter enforces a minimum interval between checkpoints per document.
+// Concurrency-safe; one instance is shared across requests.
+type RateLimiter struct {
+	mu       sync.Mutex
+	interval time.Duration
+	last     map[string]time.Time
+}
+
+// NewRateLimiter constructs a limiter with the given per-document minimum gap.
+func NewRateLimiter(interval time.Duration) *RateLimiter {
+	return &RateLimiter{interval: interval, last: make(map[string]time.Time)}
+}
+
+// Allow reports whether a checkpoint may run for docID now. When allowed it
+// records the time and returns (true, 0, recordedAt); when throttled it returns
+// (false, retryAfter, zero) where retryAfter is the wait until the next allowed
+// run. recordedAt lets a caller whose pass fails hand the exact timestamp to
+// Release so it rolls back only its own slot.
+func (rl *RateLimiter) Allow(docID string) (bool, time.Duration, time.Time) {
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+	now := time.Now()
+	if last, ok := rl.last[docID]; ok {
+		if elapsed := now.Sub(last); elapsed < rl.interval {
+			return false, rl.interval - elapsed, time.Time{}
+		}
+	}
+	rl.last[docID] = now
+	return true, 0, now
+}
+
+// Release rolls back the slot a prior Allow recorded for docID, but only if no
+// newer Allow has since claimed it. Called when an LLM pass fails: Allow runs
+// before the model call, so without this a failed checkpoint would hold the
+// per-document slot for the full interval and a retry (or the frontend's
+// auto-retry) would hit the throttle path and get the stale/empty set back
+// instead of re-running. `at` is the time the failed Allow returned.
+func (rl *RateLimiter) Release(docID string, at time.Time) {
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+	if last, ok := rl.last[docID]; ok && last.Equal(at) {
+		delete(rl.last, docID)
+	}
+}

internal/llm/checkpoint_test.go

@@ -0,0 +1,142 @@
+package llm
+
+import (
+	"testing"
+	"time"
+)
+
+func TestParseCheckpoint(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		want    int
+		wantErr bool
+	}{
+		{
+			name: "clean json",
+			raw:  `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"}]}`,
+			want: 1,
+		},
+		{
+			name: "wrapped in markdown fence",
+			raw:  "Here you go:\n```json\n{\"suggestions\":[{\"original\":\"a apple\",\"replacement\":\"an apple\",\"explanation\":\"use an before a vowel\",\"type\":\"grammar\"}]}\n```",
+			want: 1,
+		},
+		{
+			name: "empty suggestions",
+			raw:  `{"suggestions":[]}`,
+			want: 0,
+		},
+		{
+			name: "drops items with empty original",
+			raw:  `{"suggestions":[{"original":"","replacement":"x","explanation":"e","type":"grammar"},{"original":"teh","replacement":"the","explanation":"typo","type":"grammar"}]}`,
+			want: 1,
+		},
+		{
+			name:    "no json at all",
+			raw:     "I could not find any issues!",
+			wantErr: true,
+		},
+		{
+			// A correct sentence echoed verbatim as its own replacement is a card
+			// that suggests nothing — dropped. The second item is a real edit.
+			name: "drops no-op where replacement equals original",
+			raw:  `{"suggestions":[{"original":"It wasn't the most graceful morning.","replacement":"It wasn't the most graceful morning.","explanation":"used correctly here","type":"idiom"},{"original":"teh","replacement":"the","explanation":"typo","type":"grammar"}]}`,
+			want: 1,
+		},
+		{
+			// Whitespace-only difference is still a no-op once both are trimmed.
+			name: "drops no-op after whitespace trim",
+			raw:  `{"suggestions":[{"original":"the cat sat","replacement":"  the cat sat  ","explanation":"already fine","type":"grammar"}]}`,
+			want: 0,
+		},
+		{
+			// Awareness-only voice flags carry an empty replacement and must survive.
+			name: "keeps awareness-only flag with empty replacement",
+			raw:  `{"suggestions":[{"original":"a long run-on passage","replacement":"","explanation":"this drifts from your voice","type":"voice"}]}`,
+			want: 1,
+		},
+		{
+			name: "braces inside string values",
+			raw:  `{"suggestions":[{"original":"use {x}","replacement":"use x","explanation":"drop the braces","type":"clarity"}]}`,
+			want: 1,
+		},
+		{
+			// The bug that 502'd every long doc: the model hit num_predict and the
+			// JSON never closed. Two suggestions completed; the third is cut off.
+			// Salvage keeps the two that completed instead of failing outright.
+			name: "truncated mid-array salvages completed objects",
+			raw:  `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"},{"original":"a apple","replacement":"an apple","explanation":"use an before a vowel","type":"grammar"},{"original":"she relised","replacement":"she real`,
+			want: 2,
+		},
+		{
+			// A truncated array where even the first object is incomplete has
+			// nothing to salvage → still an error (the caller releases + retries).
+			name:    "truncated before any object closes",
+			raw:     `{"suggestions":[{"original":"It was a thursdy morning when Clara`,
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseCheckpoint(tt.raw)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got none")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(got) != tt.want {
+				t.Fatalf("got %d suggestions, want %d", len(got), tt.want)
+			}
+		})
+	}
+}
+
+func TestRateLimiter(t *testing.T) {
+	rl := NewRateLimiter(30 * time.Second)
+
+	ok, _, at := rl.Allow("doc1")
+	if !ok {
+		t.Fatal("first call should be allowed")
+	}
+	if ok, retry, _ := rl.Allow("doc1"); ok || retry <= 0 {
+		t.Fatalf("immediate second call should be throttled, got ok=%v retry=%v", ok, retry)
+	}
+	// A different document is independent.
+	if ok, _, _ := rl.Allow("doc2"); !ok {
+		t.Fatal("different doc should be allowed")
+	}
+
+	// Releasing doc1's slot (as a failed pass does) lets the next check re-run
+	// immediately instead of waiting out the interval.
+	rl.Release("doc1", at)
+	if ok, _, _ := rl.Allow("doc1"); !ok {
+		t.Fatal("after Release the next call should be allowed again")
+	}
+	// Release only rolls back its own slot: a stale timestamp must not evict the
+	// slot a newer Allow holds (so a late failure can't cancel a fresh in-flight
+	// check). doc2 still holds its slot from above; a zero-time Release is a no-op.
+	rl.Release("doc2", time.Time{})
+	if ok, _, _ := rl.Allow("doc2"); ok {
+		t.Fatal("stale Release must not free doc2's current slot")
+	}
+}
+
+func TestTruncateDoc(t *testing.T) {
+	short := "hello"
+	if got := TruncateDoc(short); got != short {
+		t.Fatalf("short doc should be unchanged")
+	}
+	long := make([]byte, maxDocChars+500)
+	for i := range long {
+		long[i] = 'a'
+	}
+	got := TruncateDoc(string(long))
+	if len(got) != maxDocChars {
+		t.Fatalf("truncated length = %d, want %d", len(got), maxDocChars)
+	}
+}

internal/llm/client.go

@@ -0,0 +1,110 @@
+// Package llm wraps the local inference endpoint behind a backend-agnostic
+// interface. Two concrete backends — vLLM (OpenAI-compatible) and Ollama
+// (native) — implement LLMClient; the rest of the app (the grammar checkpoint,
+// Ask Petal) calls the interface only and never knows which one is active.
+package llm
+
+import (
+	"context"
+	"time"
+
+	"gitea.parodia.dev/drwily/petal/internal/config"
+)
+
+// Message is one chat turn sent to the model.
+type Message struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+// CompletionRequest is the backend-neutral request shape. Each backend maps
+// these fields onto its own wire format (see the parameter cheatsheet in the
+// spec). Zero-valued sampling fields fall back to backend defaults.
+type CompletionRequest struct {
+	Messages          []Message
+	MaxTokens         int
+	Temperature       float64
+	RepetitionPenalty float64
+	TopP              float64
+	Stop              []string
+	Stream            bool
+}
+
+// LLMClient is the single surface handler code depends on.
+type LLMClient interface {
+	// Complete returns the full response in one shot (used for the checkpoint
+	// JSON, which we want whole before parsing).
+	Complete(ctx context.Context, req CompletionRequest) (string, error)
+	// Stream returns a channel of text chunks (used for Ask Petal SSE). The
+	// channel closes when generation ends; on a mid-stream error it closes
+	// early and the error is reported via the returned error of a future call.
+	Stream(ctx context.Context, req CompletionRequest) (<-chan string, error)
+}
+
+// Truncation caps. These guard checkpoint latency (prefill time scales with
+// input length), not the model window — Qwen 3.5 ships 256K, far larger.
+const (
+	// maxDocChars ~ 10,000 tokens at ~4 chars/token. Grammar checkpoint only;
+	// the voice pass sends the whole document uncut.
+	maxDocChars = 40000
+	// maxHistoryMsgs caps the rolling Ask Petal history (5 turns); oldest pairs
+	// drop first.
+	maxHistoryMsgs = 10
+)
+
+// TruncateDoc keeps the recent end of a document — the user is actively writing
+// there — when it exceeds the grammar-checkpoint latency cap. Most documents
+// fit uncut. The voice pass deliberately does NOT call this.
+func TruncateDoc(contentText string) string {
+	if len(contentText) > maxDocChars {
+		return contentText[len(contentText)-maxDocChars:]
+	}
+	return contentText
+}
+
+// TrimHistory keeps the most recent maxHistoryMsgs messages, dropping the
+// oldest first so a long Ask Petal chat stays within budget.
+func TrimHistory(msgs []Message) []Message {
+	if len(msgs) > maxHistoryMsgs {
+		return msgs[len(msgs)-maxHistoryMsgs:]
+	}
+	return msgs
+}
+
+// NewLLMClient selects a backend from config. LLM_CHAT_MODEL falls back to
+// LLM_MODEL here, in the factory, so handlers never deal with the fallback.
+func NewLLMClient(cfg *config.Config) LLMClient {
+	chatModel := cfg.LLMChatModel
+	if chatModel == "" {
+		chatModel = cfg.LLMModel
+	}
+	base := backend{
+		endpoint:        cfg.LLMEndpoint,
+		checkpointModel: cfg.LLMModel,
+		chatModel:       chatModel,
+		timeout:         cfg.LLMTimeout,
+	}
+	switch cfg.LLMBackend {
+	case "ollama":
+		return &OllamaClient{base}
+	default: // "vllm"
+		return &VLLMClient{base}
+	}
+}
+
+// backend holds the fields shared by both concrete clients.
+type backend struct {
+	endpoint        string
+	checkpointModel string // LLM_MODEL — small/fast checkpoint model
+	chatModel       string // LLM_CHAT_MODEL (or LLM_MODEL) — Ask Petal model
+	timeout         time.Duration
+}
+
+// model picks the right model id for a request. Streaming requests are Ask
+// Petal (chat); one-shot Complete calls are the grammar checkpoint.
+func (b backend) model(req CompletionRequest) string {
+	if req.Stream {
+		return b.chatModel
+	}
+	return b.checkpointModel
+}

internal/llm/collocation.go

@@ -0,0 +1,35 @@
+package llm
+
+import (
+	"context"
+	"time"
+)
+
+// CollocationInterval is the minimum gap between collocation passes for one
+// document. Like the voice pass it runs on an explicit user action ("Make it
+// sound natural") rather than a typing cadence, so this floor only guards the
+// inference endpoint against the button being mashed.
+const CollocationInterval = 25 * time.Second
+
+// RunCollocation sends the WHOLE document for a collocation pass — gentle
+// "natives usually say…" hints on non-native word pairings — and parses the JSON
+// result with the checkpoint's tolerant parser. It is deliberately NOT
+// TruncateDoc'd: like the voice pass it reads the whole document so the hints
+// reflect the full piece. Each flag carries a native replacement to apply.
+//
+// The tone argument is accepted for a uniform pass signature and passed through
+// to the prompt so a hint can prefer a register-appropriate pairing.
+func RunCollocation(ctx context.Context, client LLMClient, contentText, tone string) ([]RawSuggestion, error) {
+	raw, err := client.Complete(ctx, CompletionRequest{
+		Messages:          CollocationMessages(contentText, tone),
+		MaxTokens:         2048,
+		Temperature:       0.3,
+		RepetitionPenalty: 1.15,
+		TopP:              0.9,
+		Stop:              []string{"```", "\n\n\n\n"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ParseCheckpoint(raw)
+}

internal/llm/ollama.go

@@ -0,0 +1,131 @@
+package llm
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+)
+
+// OllamaClient talks to Ollama's native /api/chat endpoint. Selected when
+// LLM_BACKEND=ollama.
+type OllamaClient struct {
+	backend
+}
+
+// ollamaRequest mirrors Ollama's /api/chat body. Sampling parameters live under
+// "options" (see the cheatsheet in the spec).
+//
+// Think is sent false unconditionally: reasoning models (e.g. qwen3.5) otherwise
+// stream their chain-of-thought into a separate "thinking" field and can exhaust
+// num_predict before emitting any answer in "content" — leaving us an empty
+// response. We want direct output (structured JSON for the checkpoint, concise
+// prose for chat), not reasoning. Non-thinking models simply ignore the flag.
+type ollamaRequest struct {
+	Model    string        `json:"model"`
+	Messages []Message     `json:"messages"`
+	Stream   bool          `json:"stream"`
+	Think    bool          `json:"think"`
+	Options  ollamaOptions `json:"options"`
+}
+
+type ollamaOptions struct {
+	NumPredict    int      `json:"num_predict"`
+	Temperature   float64  `json:"temperature"`
+	RepeatPenalty float64  `json:"repeat_penalty"`
+	TopP          float64  `json:"top_p"`
+	Stop          []string `json:"stop,omitempty"`
+}
+
+func (c *OllamaClient) body(req CompletionRequest) ollamaRequest {
+	return ollamaRequest{
+		Model:    c.model(req),
+		Messages: req.Messages,
+		Stream:   req.Stream,
+		Options: ollamaOptions{
+			NumPredict:    req.MaxTokens,
+			Temperature:   req.Temperature,
+			RepeatPenalty: req.RepetitionPenalty,
+			TopP:          req.TopP,
+			Stop:          req.Stop,
+		},
+	}
+}
+
+// Complete sends a non-streaming request and returns the full message content.
+func (c *OllamaClient) Complete(ctx context.Context, req CompletionRequest) (string, error) {
+	req.Stream = false
+	ctx, cancel := context.WithTimeout(ctx, c.timeout)
+	defer cancel()
+	resp, err := c.post(ctx, c.body(req))
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", httpError("ollama", resp)
+	}
+
+	var out struct {
+		Message struct {
+			Content string `json:"content"`
+		} `json:"message"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		return "", fmt.Errorf("ollama: decode response: %w", err)
+	}
+	return out.Message.Content, nil
+}
+
+// Stream sends a streaming request. Ollama emits newline-delimited JSON objects;
+// we forward each message.content and stop when done:true.
+func (c *OllamaClient) Stream(ctx context.Context, req CompletionRequest) (<-chan string, error) {
+	req.Stream = true
+	resp, err := c.post(ctx, c.body(req))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		defer resp.Body.Close()
+		return nil, httpError("ollama", resp)
+	}
+
+	ch := make(chan string)
+	go func() {
+		defer close(ch)
+		defer resp.Body.Close()
+		sc := bufio.NewScanner(resp.Body)
+		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+		for sc.Scan() {
+			line := sc.Bytes()
+			if len(line) == 0 {
+				continue
+			}
+			var chunk struct {
+				Message struct {
+					Content string `json:"content"`
+				} `json:"message"`
+				Done bool `json:"done"`
+			}
+			if err := json.Unmarshal(line, &chunk); err != nil {
+				continue
+			}
+			if chunk.Message.Content != "" {
+				select {
+				case ch <- chunk.Message.Content:
+				case <-ctx.Done():
+					return
+				}
+			}
+			if chunk.Done {
+				return
+			}
+		}
+	}()
+	return ch, nil
+}
+
+func (c *OllamaClient) post(ctx context.Context, body any) (*http.Response, error) {
+	return postJSON(ctx, c.endpoint+"/api/chat", body)
+}

internal/llm/prompts.go

@@ -0,0 +1,236 @@
+package llm
+
+import "fmt"
+
+// checkpointSystemPrompt is the grammar-checkpoint instruction. It asks for
+// strict JSON (no fences, no preamble) so Complete's output parses directly.
+const checkpointSystemPrompt = `You are a warm, encouraging writing assistant helping someone who speaks English as a second language. ` +
+	`Analyze the text below and identify up to 5 issues: grammar errors, unnatural phrasing, ` +
+	`incorrect idiom usage, or unclear sentences that are common ESL patterns.
+
+Be specific, friendly, and explain WHY each suggestion improves the writing.%s
+
+Respond ONLY with valid JSON. No preamble, no markdown fences. Format:
+{
+  "suggestions": [
+    {
+      "original": "exact text from the document that needs fixing",
+      "replacement": "corrected version",
+      "explanation": "friendly one-sentence explanation",
+      "type": "grammar|phrasing|idiom|clarity"
+    }
+  ]
+}
+
+If the writing looks good, return: {"suggestions": []}`
+
+// toneGuidance returns a sentence steering the checkpoint toward the writer's
+// chosen tone, or "" for the neutral default. The clause is appended to the
+// checkpoint instructions so the model's phrasing suggestions fit the target
+// register (e.g. an academic essay vs a casual journal). Unknown values fall
+// back to no steering, so a stray tone string is harmless.
+func toneGuidance(tone string) string {
+	clause, ok := map[string]string{
+		"academic":     "formal, academic, and objective — suited to a school essay or research paper",
+		"professional": "polished and professional — suited to a workplace email or report",
+		"casual":       "relaxed, friendly, and conversational",
+		"humorous":     "light, playful, and good-humored",
+		"creative":     "vivid, expressive, and imaginative — suited to a story or personal narrative",
+		"persuasive":   "confident and persuasive — suited to an argument or opinion piece",
+	}[tone]
+	if !ok {
+		return ""
+	}
+	return "\n\nThe writer wants this document to read as " + clause + ". When phrasing could " +
+		"be improved, prefer suggestions that fit that tone, and gently flag wording that clashes with it."
+}
+
+// CheckpointMessages builds the message array for a grammar checkpoint over the
+// given (already-truncated) document text, steered toward the document's tone.
+func CheckpointMessages(contentText, tone string) []Message {
+	return []Message{
+		{Role: "system", Content: fmt.Sprintf(checkpointSystemPrompt, toneGuidance(tone))},
+		{Role: "user", Content: contentText},
+	}
+}
+
+// voiceSystemPrompt drives the Tier-1 voice-consistency pass. It is a distinct
+// pass from the grammar checkpoint (spec: "do not bundle them") — the model
+// reads the whole document to learn the writer's natural voice, then flags
+// passages that read as tonally out of place. `replacement` is null: these are
+// awareness-only, with no correction to apply.
+const voiceSystemPrompt = `You are a warm, encouraging writing assistant helping someone who speaks English as a second language. ` +
+	`You are reviewing a COMPLETE document for VOICE CONSISTENCY only — not grammar.
+
+Read the whole document to learn the writer's natural voice, then identify any passages (2 or more sentences) ` +
+	`that feel tonally inconsistent with the surrounding writing — unusually formal, unusually polished, or phrased ` +
+	`in a way that differs from the writer's established voice elsewhere in the document. These often signal text ` +
+	`that was paraphrased too closely from another source. Do not flag the first paragraph (there is no baseline yet). ` +
+	`Do not flag grammar or spelling mistakes — only voice.
+
+Respond ONLY with valid JSON. No preamble, no markdown fences. Format:
+{
+  "suggestions": [
+    {
+      "original": "exact passage from the document that feels inconsistent",
+      "replacement": null,
+      "explanation": "friendly one-sentence note, e.g. 'This passage sounds more formal than the rest of your writing — worth reviewing.'",
+      "type": "voice"
+    }
+  ]
+}
+
+If the voice is consistent throughout, return: {"suggestions": []}`
+
+// VoiceMessages builds the message array for a voice-consistency pass. Unlike
+// the checkpoint, the caller passes the WHOLE document (no truncation) — voice
+// consistency is judged against the established voice everywhere else.
+func VoiceMessages(contentText string) []Message {
+	return []Message{
+		{Role: "system", Content: voiceSystemPrompt},
+		{Role: "user", Content: contentText},
+	}
+}
+
+// collocationSystemPrompt drives the collocation coach — the single most
+// valuable polish for an ESL writer. It flags word PAIRINGS that are not wrong,
+// just non-native ("do a decision" → "make a decision", "strong rain" → "heavy
+// rain"), and explicitly DEFERS real grammar/spelling errors to the grammar
+// checkpoint so the two families don't overlap. Every explanation is framed as a
+// warm "natives usually say…" note with a short Mandarin gloss — never
+// "error/wrong" — because these are stylistic, not mistakes. It is a distinct
+// pass from the grammar checkpoint (do not bundle them). `replacement` carries
+// the natural pairing the writer can accept in one tap.
+const collocationSystemPrompt = `You are a warm, encouraging writing assistant helping someone who speaks English as a second language. ` +
+	`You are reviewing a COMPLETE document for COLLOCATIONS only — the natural word pairings native speakers use.
+
+A collocation is a pair or short group of words that native speakers habitually say together. ESL writers ` +
+	`often choose words that are grammatically correct but sound non-native: "do a decision" instead of "make a decision", ` +
+	`"strong rain" instead of "heavy rain", "say a joke" instead of "tell a joke". These are NOT grammar mistakes — they ` +
+	`are just not what a native speaker would naturally say.
+
+Identify up to 5 such non-native word pairings. For each, give the natural pairing a native speaker would use. ` +
+	`Be gentle and specific. Do NOT flag grammar errors, spelling mistakes, or unclear sentences — those are handled ` +
+	`elsewhere. Only flag word pairings that are correct but sound non-native.%s
+
+Phrase every explanation warmly as "Natives usually say…" and include a brief Simplified Chinese gloss in parentheses. ` +
+	`Never use the words "error", "wrong", or "mistake" — these are friendly polish, not corrections.
+
+Respond ONLY with valid JSON. No preamble, no markdown fences. Format:
+{
+  "suggestions": [
+    {
+      "original": "exact word pairing from the document",
+      "replacement": "the natural native pairing",
+      "explanation": "friendly note, e.g. 'Natives usually say \"make a decision\" rather than \"do a decision\" (native usage / 地道说法).'",
+      "type": "collocation"
+    }
+  ]
+}
+
+If every pairing already sounds natural, return: {"suggestions": []}`
+
+// CollocationMessages builds the message array for a collocation pass over the
+// WHOLE document (no truncation), gently steered toward the document's tone so a
+// hint can prefer a register-appropriate pairing.
+func CollocationMessages(contentText, tone string) []Message {
+	return []Message{
+		{Role: "system", Content: fmt.Sprintf(collocationSystemPrompt, toneGuidance(tone))},
+		{Role: "user", Content: contentText},
+	}
+}
+
+// askPetalSystemTemplate is the Ask Petal tutor prompt. The suggestion context
+// is interpolated in; the user's own messages are appended after this system
+// turn by the caller.
+const askPetalSystemTemplate = `You are Petal, a warm and patient English writing tutor helping someone who is learning English ` +
+	`as a second language. You are currently discussing a specific writing suggestion.
+
+Suggestion context:
+- Original text: "%s"
+- Suggested replacement: "%s"
+- Issue type: %s
+- Initial explanation: "%s"
+- Surrounding paragraph: "%s"
+
+The user wants to understand this suggestion better. Detect the language of the user's message ` +
+	`and respond in that same language. If they write in Mandarin Chinese, respond entirely in ` +
+	`Mandarin. If they write in English, respond in English. Never mix languages in a single response.
+
+Explain clearly and kindly. Use simple language appropriate to the user's message. Give examples ` +
+	`when helpful. If they ask "why" (or "为什么"), explain the grammar rule or idiom behind it. ` +
+	`If they suggest an alternative phrasing, evaluate it honestly.
+
+Keep responses concise (2-4 sentences). This is a chat, not an essay. Be encouraging — ` +
+	`learning a language is hard and they're doing great.`
+
+// AskPetalSystemPrompt fills the tutor prompt with one suggestion's context.
+func AskPetalSystemPrompt(original, replacement, suggestionType, explanation, paragraph string) string {
+	return fmt.Sprintf(askPetalSystemTemplate, original, replacement, suggestionType, explanation, paragraph)
+}
+
+// rewriteSystemTemplate drives the "say it more naturally" / tone-rewrite tool.
+// The writer selects a passage and picks a style; the model rewrites that
+// passage in place. The instruction is deliberately strict about returning ONLY
+// the rewritten passage so the result can be dropped straight into the editor —
+// no quotes, no preamble, no commentary to strip.
+const rewriteSystemTemplate = `You are Petal, a warm English writing assistant helping someone who speaks English ` +
+	`as a second language. Rewrite the passage the user sends so that it %s, while preserving its original ` +
+	`meaning. Fix any grammar mistakes and awkward phrasing along the way. Keep it about the same length — ` +
+	`do not add new ideas, explanations, or commentary.
+
+Respond with ONLY the rewritten passage. No quotation marks around it, no preamble, no notes — just the ` +
+	`rewritten English text, ready to drop back into the document.`
+
+// styleGuidance maps a rewrite style onto the clause describing the target
+// register. "natural" is the default "say it more naturally" action; the rest
+// mirror the document-tone vocabulary (see toneGuidance / the ToneSelect UI).
+// An unknown style falls back to the natural rewrite.
+func styleGuidance(style string) string {
+	switch style {
+	case "academic":
+		return "reads as formal, academic English suited to a school essay or research paper"
+	case "professional":
+		return "reads as polished, professional English suited to a workplace email or report"
+	case "casual":
+		return "sounds relaxed, friendly, and conversational"
+	case "humorous":
+		return "has a light, playful, good-humored tone"
+	case "creative":
+		return "is vivid, expressive, and imaginative"
+	case "persuasive":
+		return "is confident and persuasive"
+	default: // "natural"
+		return "sounds natural and fluent, the way a native English speaker would naturally say it"
+	}
+}
+
+// RewriteMessages builds the message array for a tone-rewrite: the styled system
+// instruction plus the passage to rewrite as the user turn.
+func RewriteMessages(text, style string) []Message {
+	return []Message{
+		{Role: "system", Content: fmt.Sprintf(rewriteSystemTemplate, styleGuidance(style))},
+		{Role: "user", Content: text},
+	}
+}
+
+// translateSystemPrompt drives the explanation translator: it renders a
+// suggestion's English explanation into Simplified Chinese so an ESL reader sees
+// the "why" in her first language. Strict about returning ONLY the translation
+// (no quotes, no pinyin, no English echo) so it can drop straight into the chat
+// bubble. Kept warm and plain — these are short, friendly one-liners.
+const translateSystemPrompt = `You are Petal, a warm writing assistant. Translate the English text the user ` +
+	`sends into natural, friendly Simplified Chinese (Mandarin). It is a short explanation of a writing ` +
+	`suggestion, written for a native Chinese speaker learning English.
+
+Respond with ONLY the Simplified Chinese translation. No quotation marks, no pinyin, no English, no preamble — ` +
+	`just the translated sentence.`
+
+// TranslateMessages builds the message array for translating one short English
+// explanation into Simplified Chinese.
+func TranslateMessages(text string) []Message {
+	return []Message{
+		{Role: "system", Content: translateSystemPrompt},
+		{Role: "user", Content: text},
+	}
+}

internal/llm/rewrite.go

@@ -0,0 +1,46 @@
+package llm
+
+import (
+	"context"
+	"strings"
+)
+
+// RewriteMaxRunes caps how much selected text a single rewrite will accept. A
+// rewrite is a focused "fix this sentence/paragraph" action, not a whole-doc
+// pass — bounding it keeps latency sane and the model on-task. The handler
+// rejects longer selections before calling the model.
+const RewriteMaxRunes = 2000
+
+// RunRewrite rewrites a selected passage in the requested style (e.g. "natural",
+// "academic"). It is a one-shot Complete — the result is shown as a preview the
+// writer accepts or discards, so we want the whole rewrite before rendering.
+func RunRewrite(ctx context.Context, client LLMClient, text, style string) (string, error) {
+	out, err := client.Complete(ctx, CompletionRequest{
+		Messages:          RewriteMessages(text, style),
+		MaxTokens:         1024,
+		Temperature:       0.7,
+		TopP:              0.9,
+		RepetitionPenalty: 1.1,
+	})
+	if err != nil {
+		return "", err
+	}
+	return cleanRewrite(out), nil
+}
+
+// cleanRewrite trims the model's output down to just the rewritten passage. The
+// prompt asks for no quotes or preamble, but small instruct models occasionally
+// wrap the answer in matching quotes — strip a single surrounding pair so the
+// text drops cleanly into the editor.
+func cleanRewrite(s string) string {
+	s = strings.TrimSpace(s)
+	if len(s) >= 2 {
+		first, last := s[0], s[len(s)-1]
+		if (first == '"' && last == '"') ||
+			(first == '\'' && last == '\'') ||
+			(strings.HasPrefix(s, "“") && strings.HasSuffix(s, "”")) {
+			s = strings.TrimSpace(strings.Trim(s, "\"'“”"))
+		}
+	}
+	return s
+}

internal/llm/translate.go

@@ -0,0 +1,23 @@
+package llm
+
+import (
+	"context"
+)
+
+// RunTranslate renders a short English explanation into Simplified Chinese. It
+// is a one-shot Complete (the result seeds the Ask Petal bubble), kept at a low
+// temperature so the translation is faithful rather than creative. Output is
+// trimmed of any stray surrounding quotes the model may add.
+func RunTranslate(ctx context.Context, client LLMClient, text string) (string, error) {
+	out, err := client.Complete(ctx, CompletionRequest{
+		Messages:          TranslateMessages(text),
+		MaxTokens:         512,
+		Temperature:       0.2,
+		TopP:              0.9,
+		RepetitionPenalty: 1.1,
+	})
+	if err != nil {
+		return "", err
+	}
+	return cleanRewrite(out), nil
+}

internal/llm/vllm.go

@@ -0,0 +1,156 @@
+package llm
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+)
+
+// VLLMClient talks to an OpenAI-compatible /v1/chat/completions endpoint
+// (vLLM's API server). It is the default backend.
+type VLLMClient struct {
+	backend
+}
+
+// vllmRequest is the OpenAI-compatible request body. repetition_penalty is a
+// vLLM extension to the OpenAI schema, which vLLM accepts.
+type vllmRequest struct {
+	Model             string    `json:"model"`
+	Messages          []Message `json:"messages"`
+	MaxTokens         int       `json:"max_tokens"`
+	Temperature       float64   `json:"temperature"`
+	RepetitionPenalty float64   `json:"repetition_penalty"`
+	TopP              float64   `json:"top_p"`
+	Stop              []string  `json:"stop,omitempty"`
+	Stream            bool      `json:"stream"`
+}
+
+func (c *VLLMClient) body(req CompletionRequest) vllmRequest {
+	return vllmRequest{
+		Model:             c.model(req),
+		Messages:          req.Messages,
+		MaxTokens:         req.MaxTokens,
+		Temperature:       req.Temperature,
+		RepetitionPenalty: req.RepetitionPenalty,
+		TopP:              req.TopP,
+		Stop:              req.Stop,
+		Stream:            req.Stream,
+	}
+}
+
+// Complete sends a non-streaming request and returns the full message content.
+func (c *VLLMClient) Complete(ctx context.Context, req CompletionRequest) (string, error) {
+	req.Stream = false
+	ctx, cancel := context.WithTimeout(ctx, c.timeout)
+	defer cancel()
+	resp, err := c.post(ctx, c.body(req))
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", httpError("vllm", resp)
+	}
+
+	var out struct {
+		Choices []struct {
+			Message struct {
+				Content string `json:"content"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		return "", fmt.Errorf("vllm: decode response: %w", err)
+	}
+	if len(out.Choices) == 0 {
+		return "", fmt.Errorf("vllm: empty choices in response")
+	}
+	return out.Choices[0].Message.Content, nil
+}
+
+// Stream sends a streaming request and emits delta content chunks on the
+// returned channel, which closes when the stream ends ([DONE]) or ctx is done.
+func (c *VLLMClient) Stream(ctx context.Context, req CompletionRequest) (<-chan string, error) {
+	req.Stream = true
+	resp, err := c.post(ctx, c.body(req))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		defer resp.Body.Close()
+		return nil, httpError("vllm", resp)
+	}
+
+	ch := make(chan string)
+	go func() {
+		defer close(ch)
+		defer resp.Body.Close()
+		sc := bufio.NewScanner(resp.Body)
+		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+		for sc.Scan() {
+			line := strings.TrimSpace(sc.Text())
+			if !strings.HasPrefix(line, "data:") {
+				continue
+			}
+			data := strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+			if data == "[DONE]" {
+				return
+			}
+			var chunk struct {
+				Choices []struct {
+					Delta struct {
+						Content string `json:"content"`
+					} `json:"delta"`
+				} `json:"choices"`
+			}
+			if err := json.Unmarshal([]byte(data), &chunk); err != nil {
+				continue // skip keep-alives / malformed frames
+			}
+			if len(chunk.Choices) == 0 {
+				continue
+			}
+			if text := chunk.Choices[0].Delta.Content; text != "" {
+				select {
+				case ch <- text:
+				case <-ctx.Done():
+					return
+				}
+			}
+		}
+	}()
+	return ch, nil
+}
+
+func (c *VLLMClient) post(ctx context.Context, body any) (*http.Response, error) {
+	return postJSON(ctx, c.endpoint+"/v1/chat/completions", body)
+}
+
+// --- shared HTTP helpers (used by both backends) ---------------------------
+
+// llmHTTP has no client-level timeout: Complete bounds itself with a context
+// deadline (LLM_TIMEOUT), and streaming requests must stay open as long as the
+// model is generating. Cancellation flows through the request context.
+var llmHTTP = &http.Client{}
+
+func postJSON(ctx context.Context, url string, body any) (*http.Response, error) {
+	buf, err := json.Marshal(body)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(buf))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	return llmHTTP.Do(req)
+}
+
+func httpError(backend string, resp *http.Response) error {
+	b, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
+	return fmt.Errorf("%s: %s: %s", backend, resp.Status, strings.TrimSpace(string(b)))
+}

internal/llm/voice.go

@@ -0,0 +1,35 @@
+package llm
+
+import (
+	"context"
+	"time"
+)
+
+// VoiceInterval is the minimum gap between voice-consistency passes for one
+// document. The pass is whole-document and slow, and it runs on an explicit
+// user action rather than a typing cadence, so this floor only guards the
+// inference endpoint against the button being mashed.
+const VoiceInterval = 20 * time.Second
+
+// RunVoice sends the WHOLE document — deliberately NOT TruncateDoc'd, since
+// voice consistency is judged against the established voice everywhere else —
+// for a Tier-1 voice pass and parses the JSON result. It reuses the checkpoint's
+// tolerant parser and a larger token budget, since one pass may flag several
+// passages. Each flag carries a null replacement (awareness-only).
+// The tone argument is accepted for a uniform pass signature but ignored: voice
+// consistency is judged against the document's own established voice, not an
+// externally-chosen register.
+func RunVoice(ctx context.Context, client LLMClient, contentText, _ string) ([]RawSuggestion, error) {
+	raw, err := client.Complete(ctx, CompletionRequest{
+		Messages:          VoiceMessages(contentText),
+		MaxTokens:         2048,
+		Temperature:       0.3,
+		RepetitionPenalty: 1.15,
+		TopP:              0.9,
+		Stop:              []string{"```", "\n\n\n\n"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ParseCheckpoint(raw)
+}

internal/suggestions/chat.go

@@ -0,0 +1,127 @@
+package suggestions
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// chatRequest is the body the AskPetal panel posts: the full conversation so
+// far. The suggestion context is loaded server-side and never trusted from the
+// client (spec Note #10).
+type chatRequest struct {
+	Messages []llm.Message `json:"messages"`
+}
+
+// chat streams an Ask Petal conversational reply over SSE. It loads the
+// suggestion and its parent document's surrounding paragraph, injects them as
+// the tutor system prompt, then relays the model's tokens to the browser as
+// `data:` events. History persistence lives entirely in the client.
+func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
+	sugID := chi.URLParam(r, "id")
+
+	var body chatRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body")
+		return
+	}
+
+	// One query for the suggestion fields and the parent document's plain text,
+	// scoped to the local user so a stray id can't read another user's doc.
+	var (
+		original, replacement, explanation, typ string
+		fromPos                                 int
+		contentText                             string
+	)
+	err := h.DB.QueryRow(
+		`SELECT s.original, s.replacement, s.explanation, s.type, s.from_pos, d.content_text
+		   FROM suggestions s
+		   JOIN documents d ON d.id = s.doc_id
+		  WHERE s.id = ? AND d.user_id = ?`,
+		sugID, db.LocalUserID,
+	).Scan(&original, &replacement, &explanation, &typ, &fromPos, &contentText)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	paragraph := surroundingParagraph(contentText, fromPos)
+	systemPrompt := llm.AskPetalSystemPrompt(original, replacement, typ, explanation, paragraph)
+
+	// SSE requires an unbuffered, flushable writer. chi's middleware writers pass
+	// Flush through; bail with a plain error if somehow they don't.
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		httputil.ServerError(w, errors.New("streaming unsupported"))
+		return
+	}
+
+	ch, err := llm.StreamAskPetal(r.Context(), h.Client, systemPrompt, body.Messages)
+	if err != nil {
+		// The stream never opened (e.g. LLM unreachable) — a normal JSON error is
+		// still appropriate since we haven't written SSE headers yet.
+		httputil.ErrorJSON(w, http.StatusBadGateway, "chat failed: "+err.Error())
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no") // disable proxy buffering (e.g. nginx)
+	w.WriteHeader(http.StatusOK)
+	flusher.Flush()
+
+	for chunk := range ch {
+		writeSSE(w, "token", map[string]string{"text": chunk})
+		flusher.Flush()
+	}
+	// Signal a clean end so the client can stop reading without waiting on EOF.
+	writeSSE(w, "done", map[string]bool{"done": true})
+	flusher.Flush()
+}
+
+// writeSSE emits one named SSE event with a JSON data payload. JSON-encoding the
+// data keeps token text (which may contain newlines) from breaking SSE framing.
+func writeSSE(w http.ResponseWriter, event string, data any) {
+	payload, err := json.Marshal(data)
+	if err != nil {
+		return
+	}
+	_, _ = w.Write([]byte("event: " + event + "\ndata: "))
+	_, _ = w.Write(payload)
+	_, _ = w.Write([]byte("\n\n"))
+}
+
+// surroundingParagraph returns the paragraph of contentText containing the
+// plain-text offset from. Tiptap flattens blocks with blank-line separators, so
+// paragraphs are bounded by "\n\n". When the offset is unknown (original wasn't
+// located, from == -1) it falls back to the latency-capped document so the tutor
+// still has context to work with.
+func surroundingParagraph(contentText string, from int) string {
+	if from < 0 || from > len(contentText) {
+		return strings.TrimSpace(llm.TruncateDoc(contentText))
+	}
+	start := strings.LastIndex(contentText[:from], "\n\n")
+	if start < 0 {
+		start = 0
+	} else {
+		start += 2
+	}
+	end := len(contentText)
+	if rel := strings.Index(contentText[from:], "\n\n"); rel >= 0 {
+		end = from + rel
+	}
+	return strings.TrimSpace(contentText[start:end])
+}

internal/suggestions/chat_test.go

@@ -0,0 +1,148 @@
+package suggestions
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// streamClient serves a canned checkpoint (so a suggestion can be seeded through
+// the public /check route) and a fixed token stream for chat. It records the
+// last streamed request so a test can assert on the injected system context.
+type streamClient struct {
+	checkpoint string
+	tokens     []string
+	lastStream llm.CompletionRequest
+}
+
+func (c *streamClient) Complete(_ context.Context, _ llm.CompletionRequest) (string, error) {
+	return c.checkpoint, nil
+}
+
+func (c *streamClient) Stream(_ context.Context, req llm.CompletionRequest) (<-chan string, error) {
+	c.lastStream = req
+	ch := make(chan string)
+	go func() {
+		defer close(ch)
+		for _, t := range c.tokens {
+			ch <- t
+		}
+	}()
+	return ch, nil
+}
+
+func TestAskPetalChat(t *testing.T) {
+	client := &streamClient{
+		checkpoint: `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"}]}`,
+		tokens:     []string{"Because ", "\"I\" ", "takes ", "\"have\"."},
+	}
+	srv, docID, _ := newTestServer(t, client)
+
+	// Seed one suggestion via the checkpoint route, then grab its id.
+	do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	listed := do(t, srv, http.MethodGet, "/docs/"+docID+"/suggestions", "")
+	var sugs []db.Suggestion
+	if err := json.Unmarshal(listed.Body.Bytes(), &sugs); err != nil {
+		t.Fatalf("decode suggestions: %v", err)
+	}
+	if len(sugs) != 1 {
+		t.Fatalf("seed: want 1 suggestion, got %d", len(sugs))
+	}
+	sugID := sugs[0].ID
+
+	rec := do(t, srv, http.MethodPost, "/suggestions/"+sugID+"/chat",
+		`{"messages":[{"role":"user","content":"why is this wrong?"}]}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("chat: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "text/event-stream" {
+		t.Fatalf("chat: content-type=%q, want text/event-stream", ct)
+	}
+
+	// The streamed tokens should arrive concatenated across data: events, and the
+	// stream should terminate with a done event.
+	body := rec.Body.String()
+	got := collectSSEText(body)
+	if want := "Because \"I\" takes \"have\"."; got != want {
+		t.Fatalf("streamed text = %q, want %q", got, want)
+	}
+	if !strings.Contains(body, "event: done") {
+		t.Fatalf("chat stream missing done event:\n%s", body)
+	}
+
+	// Context injection: the system prompt (first message) must carry the
+	// suggestion's original text and the surrounding paragraph — loaded
+	// server-side, never from the client.
+	msgs := client.lastStream.Messages
+	if len(msgs) < 2 || msgs[0].Role != "system" {
+		t.Fatalf("expected a leading system message, got %+v", msgs)
+	}
+	sys := msgs[0].Content
+	if !strings.Contains(sys, "I has") {
+		t.Fatalf("system prompt missing original text:\n%s", sys)
+	}
+	if !strings.Contains(sys, "I has two apple.") {
+		t.Fatalf("system prompt missing surrounding paragraph:\n%s", sys)
+	}
+	// The client's user message rides after the system turn.
+	if last := msgs[len(msgs)-1]; last.Role != "user" || last.Content != "why is this wrong?" {
+		t.Fatalf("user message not forwarded: %+v", last)
+	}
+
+	// Chat sampling parameters from the spec.
+	if client.lastStream.MaxTokens != 512 || client.lastStream.Temperature != 0.7 {
+		t.Fatalf("unexpected chat params: %+v", client.lastStream)
+	}
+}
+
+func TestAskPetalChatNotFound(t *testing.T) {
+	client := &streamClient{checkpoint: `{"suggestions":[]}`}
+	srv, _, _ := newTestServer(t, client)
+	rec := do(t, srv, http.MethodPost, "/suggestions/does-not-exist/chat",
+		`{"messages":[{"role":"user","content":"hi"}]}`)
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("want 404 for unknown suggestion, got %d", rec.Code)
+	}
+}
+
+func TestSurroundingParagraph(t *testing.T) {
+	text := "First paragraph here.\n\nThe target sentence lives here.\n\nThird paragraph."
+	from := strings.Index(text, "target")
+	got := surroundingParagraph(text, from)
+	if got != "The target sentence lives here." {
+		t.Fatalf("paragraph = %q", got)
+	}
+
+	// Unknown offset falls back to the (trimmed) document.
+	if got := surroundingParagraph(text, -1); !strings.Contains(got, "First paragraph") {
+		t.Fatalf("fallback paragraph = %q", got)
+	}
+}
+
+// collectSSEText concatenates the JSON text fields from every `event: token`
+// frame in an SSE body.
+func collectSSEText(body string) string {
+	var b strings.Builder
+	for _, frame := range strings.Split(body, "\n\n") {
+		if !strings.Contains(frame, "event: token") {
+			continue
+		}
+		for _, line := range strings.Split(frame, "\n") {
+			data, ok := strings.CutPrefix(line, "data: ")
+			if !ok {
+				continue
+			}
+			var payload struct {
+				Text string `json:"text"`
+			}
+			_ = json.Unmarshal([]byte(data), &payload)
+			b.WriteString(payload.Text)
+		}
+	}
+	return b.String()
+}

internal/suggestions/handlers.go

@@ -0,0 +1,593 @@
+// Package suggestions implements the grammar-checkpoint endpoint and the
+// accept/dismiss surface for LLM-proposed edits. Checkpoints run a single LLM
+// pass over a document and persist the resulting pending suggestions; the
+// frontend re-anchors each one by its `original` string at render time, so the
+// stored positions are advisory only (spec Note #6).
+package suggestions
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// Handler holds the dependencies for the checkpoint + suggestion routes. The
+// grammar checkpoint and the voice pass each get their own per-document rate
+// limiter — they are independent passes with different cadences.
+type Handler struct {
+	DB               *db.DB
+	Client           llm.LLMClient
+	Limit            *llm.RateLimiter // grammar checkpoint floor
+	VoiceLimit       *llm.RateLimiter // voice-consistency floor
+	CollocationLimit *llm.RateLimiter // collocation-coach floor
+}
+
+// New constructs a Handler with per-document checkpoint, voice, and collocation
+// rate limiters.
+func New(database *db.DB, client llm.LLMClient) *Handler {
+	return &Handler{
+		DB:               database,
+		Client:           client,
+		Limit:            llm.NewRateLimiter(llm.CheckpointInterval),
+		VoiceLimit:       llm.NewRateLimiter(llm.VoiceInterval),
+		CollocationLimit: llm.NewRateLimiter(llm.CollocationInterval),
+	}
+}
+
+// RegisterDocRoutes adds the document-scoped routes (check + voice + list) onto
+// the existing /api/docs router so they share its base path.
+func (h *Handler) RegisterDocRoutes(r chi.Router) {
+	r.Post("/{id}/check", h.check)
+	r.Post("/{id}/mechanics", h.mechanics)
+	r.Post("/{id}/voice", h.voice)
+	r.Post("/{id}/collocation", h.collocation)
+	r.Post("/{id}/rewrite", h.rewrite)
+	r.Get("/{id}/suggestions", h.listForDoc)
+}
+
+// Routes returns the router mounted at /api/suggestions for per-suggestion
+// actions.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Post("/{id}/accept", h.accept)
+	r.Post("/{id}/dismiss", h.dismiss)
+	r.Post("/{id}/chat", h.chat)
+	r.Post("/{id}/translate", h.translate)
+	return r
+}
+
+// check runs a grammar checkpoint over the document. Fast, typing-cadence pass.
+// The deterministic mechanics family is owned by a separate pass (see mechanics),
+// detected client-side; a grammar checkpoint leaves those flags untouched.
+func (h *Handler) check(w http.ResponseWriter, r *http.Request) {
+	h.runPass(w, r, h.Limit, llm.RunCheckpoint, grammarScope)
+}
+
+// mechanicsFinding is one deterministic, rule-based fix detected client-side (see
+// web Companion/prose.ts). Detection lives in the frontend — the same rules that
+// power the companion's prose notes — so the server only persists these; it does
+// not compute them. Offsets are exact plaintext spans from the detector.
+type mechanicsFinding struct {
+	From        int    `json:"from"`
+	To          int    `json:"to"`
+	Original    string `json:"original"`
+	Replacement string `json:"replacement"`
+	Explanation string `json:"explanation"`
+}
+
+// maxMechanicsFindings caps a single submission so a runaway client can't flood
+// the table; far above any realistic count for one document.
+const maxMechanicsFindings = 500
+
+// mechanics persists the client-detected deterministic fixes as the 'mechanics'
+// family and returns the document's unified pending set. Free and not rate-
+// limited — it runs alongside the grammar checkpoint. It mirrors a single LLM
+// family: it replaces only the pending mechanics rows, honours actioned-
+// suppression, and (unlike the LLM passes) keeps the detector's exact offsets
+// rather than re-locating by string, which matters when the same word repeats.
+func (h *Handler) mechanics(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+
+	// Confirm the document exists (and is the local user's) for clean 404s.
+	var exists bool
+	err := h.DB.QueryRow(
+		`SELECT EXISTS(SELECT 1 FROM documents WHERE id = ? AND user_id = ?)`,
+		docID, db.LocalUserID,
+	).Scan(&exists)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if !exists {
+		httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
+		return
+	}
+
+	var body struct {
+		Findings []mechanicsFinding `json:"findings"`
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&body); err != nil {
+		httputil.BadRequest(w, "invalid request body")
+		return
+	}
+	if len(body.Findings) > maxMechanicsFindings {
+		body.Findings = body.Findings[:maxMechanicsFindings]
+	}
+
+	if err := h.replaceMechanics(docID, body.Findings); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := h.fetchPending(docID)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// replaceMechanics swaps the document's pending mechanics rows for the supplied
+// findings in one transaction, leaving the LLM families and actioned rows
+// untouched. Findings the user already accepted or dismissed are suppressed (the
+// detector has no memory between runs), and malformed spans are skipped.
+func (h *Handler) replaceMechanics(docID string, findings []mechanicsFinding) error {
+	tx, err := h.DB.Begin()
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback()
+
+	if _, err := tx.Exec(
+		`DELETE FROM suggestions WHERE doc_id = ? AND status = ? AND type = ?`,
+		docID, db.SuggestionStatusPending, db.SuggestionTypeMechanics,
+	); err != nil {
+		return err
+	}
+
+	sup, err := buildSuppressor(tx, docID)
+	if err != nil {
+		return err
+	}
+
+	for _, f := range findings {
+		if f.From < 0 || f.To <= f.From || strings.TrimSpace(f.Original) == "" {
+			continue // malformed span — the client re-anchors by string anyway
+		}
+		if sup.suppressed(f.Original, f.Replacement) {
+			continue
+		}
+		if _, err := tx.Exec(
+			`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			docID, f.From, f.To, f.Original, f.Replacement, f.Explanation, db.SuggestionTypeMechanics,
+		); err != nil {
+			return err
+		}
+	}
+
+	return tx.Commit()
+}
+
+// voice runs a Tier-1 voice-consistency pass over the whole document. Slow,
+// explicit-action pass; replaces only the pending voice flags.
+func (h *Handler) voice(w http.ResponseWriter, r *http.Request) {
+	h.runPass(w, r, h.VoiceLimit, llm.RunVoice, voiceScope)
+}
+
+// collocation runs the collocation coach over the whole document, flagging
+// non-native word pairings. Explicit-action pass; replaces only the pending
+// collocation flags.
+func (h *Handler) collocation(w http.ResponseWriter, r *http.Request) {
+	h.runPass(w, r, h.CollocationLimit, llm.RunCollocation, collocationScope)
+}
+
+// pass is the signature shared by the grammar checkpoint and the voice pass:
+// given the document text and the document's tone it returns the model's raw
+// suggestions. The voice pass ignores tone (see llm.RunVoice).
+type pass func(ctx context.Context, client llm.LLMClient, contentText, tone string) ([]llm.RawSuggestion, error)
+
+// runPass is the shared body for both LLM passes. It loads the document text,
+// enforces the pass's per-document rate limit, runs the model, swaps in the
+// fresh batch scoped to this family, and returns the document's FULL pending set
+// (both families) so the client always renders a unified picture.
+func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.RateLimiter, run pass, scope pendingScope) {
+	docID := chi.URLParam(r, "id")
+
+	var contentText, tone string
+	err := h.DB.QueryRow(
+		`SELECT content_text, tone FROM documents WHERE id = ? AND user_id = ?`,
+		docID, db.LocalUserID,
+	).Scan(&contentText, &tone)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	// Nothing to analyze on an empty document — skip the LLM round-trip.
+	if strings.TrimSpace(contentText) == "" {
+		httputil.WriteJSON(w, http.StatusOK, []db.Suggestion{})
+		return
+	}
+
+	ok, _, slotAt := limiter.Allow(docID)
+	if !ok {
+		// Throttled: return the existing pending set unchanged rather than an
+		// error, so the frontend keeps showing current suggestions.
+		existing, err := h.fetchPending(docID)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		httputil.WriteJSON(w, http.StatusOK, existing)
+		return
+	}
+
+	raw, err := run(r.Context(), h.Client, contentText, tone)
+	if err != nil {
+		// Allow ran before the model call, so a failed pass would otherwise hold
+		// the per-document slot for the full interval — stranding the frontend's
+		// auto-retry on the throttle path. Release it so a retry can re-run.
+		limiter.Release(docID, slotAt)
+		httputil.ErrorJSON(w, http.StatusBadGateway, "llm pass failed: "+err.Error())
+		return
+	}
+
+	if err := h.replacePending(docID, contentText, raw, scope); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	// Return the unified pending set (grammar + voice), not just this batch, so
+	// a grammar check never drops the voice highlights from the client and the
+	// throttle path above stays consistent with the success path.
+	out, err := h.fetchPending(docID)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// pendingScope describes how one LLM pass touches the shared suggestions table:
+// which family of pending rows it replaces, and the type to stamp on the rows it
+// inserts. The grammar checkpoint and voice pass each own a disjoint family, so
+// running one never disturbs the other's pending flags.
+type pendingScope struct {
+	deleteWhere string // extra WHERE clause scoping the DELETE to this family
+	forceType   string // if set, every inserted row gets this type; else normalizeType
+}
+
+var (
+	// grammarScope owns the grammar/phrasing/idiom/clarity flags — everything but
+	// the other self-owned families (voice, collocation, mechanics), which run on
+	// their own cadence/pass and must survive a grammar checkpoint. Notably the
+	// deterministic mechanics pass writes its rows in the same /check request just
+	// before this DELETE runs, so excluding it here is what keeps them alive.
+	grammarScope = pendingScope{deleteWhere: "type NOT IN ('voice','collocation','mechanics')", forceType: ""}
+	// voiceScope owns the voice flags only.
+	voiceScope = pendingScope{deleteWhere: "type = 'voice'", forceType: db.SuggestionTypeVoice}
+	// collocationScope owns the collocation flags only.
+	collocationScope = pendingScope{deleteWhere: "type = 'collocation'", forceType: db.SuggestionTypeCollocation}
+)
+
+// replacePending swaps a document's pending suggestions within one family for a
+// fresh batch in a single transaction. Accepted/rejected suggestions and the
+// other family's pending rows are left untouched.
+//
+// Suggestions touching a sentence the user already settled are suppressed from
+// the fresh batch (see suppressor): not just the identical edit re-proposed, but
+// reversals and re-polishing of the model's own just-accepted output — the
+// "fickle, keeps going back and forth on a few sentences" behavior. The model has
+// no memory between passes, so without this it re-opens resolved sentences every
+// checkpoint.
+func (h *Handler) replacePending(docID, contentText string, raw []llm.RawSuggestion, scope pendingScope) error {
+	tx, err := h.DB.Begin()
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback()
+
+	if _, err := tx.Exec(
+		`DELETE FROM suggestions WHERE doc_id = ? AND status = ? AND `+scope.deleteWhere,
+		docID, db.SuggestionStatusPending,
+	); err != nil {
+		return err
+	}
+
+	sup, err := buildSuppressor(tx, docID)
+	if err != nil {
+		return err
+	}
+
+	for _, s := range raw {
+		if sup.suppressed(s.Original, s.Replacement) {
+			continue
+		}
+		typ := scope.forceType
+		if typ == "" {
+			typ = normalizeType(s.Type)
+		}
+		from, to := locate(contentText, s.Original)
+		if _, err := tx.Exec(
+			`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			docID, from, to, s.Original, s.Replacement, s.Explanation, typ,
+		); err != nil {
+			return err
+		}
+	}
+
+	return tx.Commit()
+}
+
+// dedupQuoteReplacer folds every straight/curly single- and double-quote variant
+// (and backtick/acute accent) onto one canonical character. The editor and the
+// model both rewrite quotes between passes — a sentence accepted with "…" comes
+// back flagged with '…' — so without folding, byte-identical text reads as a
+// different edit and the suppression below misses it. (This normalization is for
+// dedup ONLY; the frontend still anchors on the verbatim `original`.)
+var dedupQuoteReplacer = strings.NewReplacer(
+	"‘", "'", "’", "'", "‚", "'", "‛", "'", // single curly
+	"“", "'", "”", "'", "„", "'", "″", "'", // double curly
+	"\"", "'", "`", "'", "´", "'", // straight double, backtick, acute
+)
+
+// normalizeForDedup canonicalizes a string for suppression comparisons: quotes
+// folded (above) and runs of whitespace collapsed to single spaces (so a reflowed
+// paragraph still matches). Used only to decide what to suppress, never to alter
+// stored or rendered text.
+func normalizeForDedup(s string) string {
+	return strings.Join(strings.Fields(dedupQuoteReplacer.Replace(s)), " ")
+}
+
+// suppressor decides which fresh suggestions to drop because the user has already
+// settled the sentence they touch. The model has no memory between passes, so on
+// every checkpoint it re-examines the current text and proposes edits — including
+// ones that re-open a sentence the user already resolved. Three families of those
+// are suppressed (all compared under normalizeForDedup):
+//
+//   - pairs: the identical edit, re-proposed verbatim (the original "accept it,
+//     then it nags again" case; also covers a silent no-op accept that left the
+//     text unchanged).
+//   - actionedOrig: any edit whose original is a span the user already accepted or
+//     dismissed an edit on — "you already decided about this exact sentence."
+//   - acceptedRepl: any edit whose original is text the user accepted AS a
+//     replacement — i.e. the model re-touching its own just-accepted output, which
+//     is how the reversals and endless re-polishing arise (accept "due to the
+//     rain", next pass proposes changing "due to the rain" back). Guarded to
+//     multi-word spans so word-level fixes aren't swept up as collateral.
+//   - acceptedReplList holds the same accepted replacements for a containment
+//     check: the model evades the exact acceptedRepl match by re-flagging a
+//     *sub-clause* of an accepted sentence (flag "she was…due to the rain" instead
+//     of the whole sentence). When one of the new original / an accepted
+//     replacement contains the other and the shorter side is substantial
+//     (>= minContainWords words), it's the same settled span and is dropped.
+type suppressor struct {
+	pairs            map[string]struct{}
+	actionedOrig     map[string]struct{}
+	acceptedRepl     map[string]struct{}
+	acceptedReplList []string
+}
+
+// minContainWords is the floor for the containment check: the shorter of the two
+// spans must be at least this many words before a substring relationship counts
+// as "the same settled text." High enough that an incidental common phrase ("the
+// rain") can't suppress an unrelated sentence, low enough to catch a re-flagged
+// clause.
+const minContainWords = 4
+
+// suppressed reports whether a fresh suggestion should be dropped as already
+// settled. An empty original is never suppressed here (it can't anchor anyway and
+// is dropped upstream).
+func (s suppressor) suppressed(original, replacement string) bool {
+	o := normalizeForDedup(original)
+	if o == "" {
+		return false
+	}
+	if _, ok := s.pairs[o+"\x00"+normalizeForDedup(replacement)]; ok {
+		return true
+	}
+	if _, ok := s.actionedOrig[o]; ok {
+		return true
+	}
+	if strings.ContainsRune(o, ' ') {
+		if _, ok := s.acceptedRepl[o]; ok {
+			return true
+		}
+	}
+	// Containment: the model re-flagged a sub-clause of (or a window around) an
+	// accepted span. Suppress when one contains the other and the shorter side is
+	// a substantial multi-word run.
+	for _, r := range s.acceptedReplList {
+		shorter, longer := o, r
+		if len(r) < len(o) {
+			shorter, longer = r, o
+		}
+		if len(strings.Fields(shorter)) >= minContainWords && strings.Contains(longer, shorter) {
+			return true
+		}
+	}
+	return false
+}
+
+// buildSuppressor loads the document's accepted/rejected edits and indexes them
+// into the three suppression families described on suppressor.
+func buildSuppressor(tx *sql.Tx, docID string) (suppressor, error) {
+	rows, err := tx.Query(
+		`SELECT original, replacement, status FROM suggestions
+		  WHERE doc_id = ? AND status IN (?, ?)`,
+		docID, db.SuggestionStatusAccepted, db.SuggestionStatusRejected,
+	)
+	if err != nil {
+		return suppressor{}, err
+	}
+	defer rows.Close()
+
+	s := suppressor{
+		pairs:        make(map[string]struct{}),
+		actionedOrig: make(map[string]struct{}),
+		acceptedRepl: make(map[string]struct{}),
+	}
+	for rows.Next() {
+		var original, replacement, status string
+		if err := rows.Scan(&original, &replacement, &status); err != nil {
+			return suppressor{}, err
+		}
+		o := normalizeForDedup(original)
+		r := normalizeForDedup(replacement)
+		s.pairs[o+"\x00"+r] = struct{}{}
+		if o != "" {
+			s.actionedOrig[o] = struct{}{}
+		}
+		if status == db.SuggestionStatusAccepted && r != "" {
+			s.acceptedRepl[r] = struct{}{}
+			s.acceptedReplList = append(s.acceptedReplList, r)
+		}
+	}
+	return s, rows.Err()
+}
+
+// listForDoc returns the document's current pending suggestions (used when the
+// editor loads a document, before any new checkpoint fires).
+func (h *Handler) listForDoc(w http.ResponseWriter, r *http.Request) {
+	out, err := h.fetchPending(chi.URLParam(r, "id"))
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+func (h *Handler) fetchPending(docID string) ([]db.Suggestion, error) {
+	rows, err := h.DB.Query(
+		`SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at
+		   FROM suggestions
+		  WHERE doc_id = ? AND status = ?
+		  ORDER BY from_pos ASC, created_at ASC`,
+		docID, db.SuggestionStatusPending,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := []db.Suggestion{}
+	for rows.Next() {
+		var s db.Suggestion
+		if err := rows.Scan(
+			&s.ID, &s.DocID, &s.FromPos, &s.ToPos, &s.Original, &s.Replacement,
+			&s.Explanation, &s.Type, &s.Status, &s.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		out = append(out, s)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return dedupeSpans(out), nil
+}
+
+// dedupeSpans resolves collisions between the deterministic mechanics family and
+// the LLM families: when a mechanics finding and an LLM suggestion fight over the
+// same characters, mechanics wins and the LLM card is dropped. Its span is exact
+// (the detector matched it), whereas the LLM positions are only advisory
+// (re-anchored by string at render), so the precise fix should own the span.
+//
+// This deliberately does NOT dedupe LLM-vs-LLM overlaps: voice (awareness-only,
+// no replacement) and collocation legitimately co-occupy the same span, and that
+// is intended. Suggestions that never anchored (from_pos < 0) occupy no real span
+// and are always kept.
+func dedupeSpans(in []db.Suggestion) []db.Suggestion {
+	type span struct{ from, to int }
+	var claimed []span
+	for _, s := range in {
+		if s.Type == db.SuggestionTypeMechanics && s.FromPos >= 0 {
+			claimed = append(claimed, span{s.FromPos, s.ToPos})
+		}
+	}
+	if len(claimed) == 0 {
+		return in
+	}
+
+	out := make([]db.Suggestion, 0, len(in))
+	for _, s := range in {
+		if s.Type != db.SuggestionTypeMechanics && s.FromPos >= 0 {
+			overlaps := false
+			for _, sp := range claimed {
+				if s.FromPos < sp.to && sp.from < s.ToPos {
+					overlaps = true
+					break
+				}
+			}
+			if overlaps {
+				continue // an exact mechanics fix owns these characters
+			}
+		}
+		out = append(out, s)
+	}
+	return out
+}
+
+// accept marks a suggestion accepted (the client applies the replacement text).
+func (h *Handler) accept(w http.ResponseWriter, r *http.Request) {
+	h.setStatus(w, r, db.SuggestionStatusAccepted)
+}
+
+// dismiss marks a suggestion rejected.
+func (h *Handler) dismiss(w http.ResponseWriter, r *http.Request) {
+	h.setStatus(w, r, db.SuggestionStatusRejected)
+}
+
+func (h *Handler) setStatus(w http.ResponseWriter, r *http.Request, status string) {
+	res, err := h.DB.Exec(
+		`UPDATE suggestions SET status = ? WHERE id = ? AND status = ?`,
+		status, chi.URLParam(r, "id"), db.SuggestionStatusPending,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		httputil.ErrorJSON(w, http.StatusNotFound, "pending suggestion not found")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// locate finds the plaintext offsets of original within contentText. Returns
+// (-1, -1) when not found; the frontend anchors by string regardless, so a miss
+// here is non-fatal.
+func locate(contentText, original string) (int, int) {
+	idx := strings.Index(contentText, original)
+	if idx < 0 {
+		return -1, -1
+	}
+	return idx, idx + len(original)
+}
+
+// normalizeType maps the model's type string onto a valid suggestion type,
+// defaulting unknown values to grammar so a stray label never trips the CHECK.
+func normalizeType(t string) string {
+	switch strings.ToLower(strings.TrimSpace(t)) {
+	case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity, db.SuggestionTypeCollocation:
+		return strings.ToLower(strings.TrimSpace(t))
+	default:
+		return db.SuggestionTypeGrammar
+	}
+}

internal/suggestions/handlers_test.go

@@ -0,0 +1,473 @@
+package suggestions
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// stubClient returns a canned checkpoint response; it never touches the network.
+type stubClient struct {
+	response string
+	calls    int
+}
+
+func (s *stubClient) Complete(_ context.Context, _ llm.CompletionRequest) (string, error) {
+	s.calls++
+	return s.response, nil
+}
+
+func (s *stubClient) Stream(_ context.Context, _ llm.CompletionRequest) (<-chan string, error) {
+	ch := make(chan string)
+	close(ch)
+	return ch, nil
+}
+
+// newTestServer wires a real DB, a seeded document, and the suggestion routes
+// (both the doc-scoped and the per-suggestion mounts) onto one router.
+func newTestServer(t *testing.T, client llm.LLMClient) (http.Handler, string, *Handler) {
+	t.Helper()
+	database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { database.Close() })
+
+	// Seed a document with some content to check.
+	var docID string
+	err = database.QueryRow(
+		`INSERT INTO documents (user_id, content_text) VALUES (?, ?) RETURNING id`,
+		db.LocalUserID, "I has two apple.",
+	).Scan(&docID)
+	if err != nil {
+		t.Fatalf("seed doc: %v", err)
+	}
+
+	h := New(database, client)
+	r := chi.NewRouter()
+	r.Route("/docs", func(dr chi.Router) { h.RegisterDocRoutes(dr) })
+	r.Mount("/suggestions", h.Routes())
+	return r, docID, h
+}
+
+func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	} else {
+		r = httptest.NewRequest(method, path, nil)
+	}
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, r)
+	return rec
+}
+
+func TestCheckpointFlow(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[
+		{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"},
+		{"original":"two apple","replacement":"two apples","explanation":"plural noun","type":"grammar"}
+	]}`}
+	srv, docID, _ := newTestServer(t, client)
+
+	// Run a checkpoint → two pending suggestions, with positions located.
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("want 2 suggestions, got %d: %+v", len(got), got)
+	}
+	if got[0].Original != "I has" || got[0].FromPos != 0 {
+		t.Fatalf("first suggestion anchoring wrong: %+v", got[0])
+	}
+	if got[0].Status != db.SuggestionStatusPending {
+		t.Fatalf("new suggestion should be pending: %+v", got[0])
+	}
+
+	// Listing returns the same pending set.
+	rec = do(t, srv, http.MethodGet, "/docs/"+docID+"/suggestions", "")
+	var listed []db.Suggestion
+	_ = json.Unmarshal(rec.Body.Bytes(), &listed)
+	if len(listed) != 2 {
+		t.Fatalf("list pending: want 2, got %d", len(listed))
+	}
+
+	// Accept the first, dismiss the second.
+	if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/accept", ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("accept: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[1].ID+"/dismiss", ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("dismiss: code=%d body=%s", rec.Code, rec.Body)
+	}
+
+	// Pending list is now empty (accepted/dismissed are excluded).
+	rec = do(t, srv, http.MethodGet, "/docs/"+docID+"/suggestions", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &listed)
+	if len(listed) != 0 {
+		t.Fatalf("pending after resolve: want 0, got %d", len(listed))
+	}
+
+	// Re-accepting an already-resolved suggestion 404s.
+	if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/accept", ""); rec.Code != http.StatusNotFound {
+		t.Fatalf("re-accept: want 404, got %d", rec.Code)
+	}
+}
+
+// TestResolvedSuggestionsNotReproposed proves a checkpoint won't re-nag a
+// sentence the user already accepted or dismissed: the model returns the same
+// raw batch on the next pass (it has no memory), but the resolved edits are
+// suppressed. This is the "accept it, then it nags again moments later" bug.
+func TestResolvedSuggestionsNotReproposed(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[
+		{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"},
+		{"original":"two apple","replacement":"two apples","explanation":"plural noun","type":"grammar"}
+	]}`}
+	srv, docID, h := newTestServer(t, client)
+	// Zero the checkpoint floor so the second pass runs instead of being throttled.
+	h.Limit = llm.NewRateLimiter(0)
+
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	var got []db.Suggestion
+	_ = json.Unmarshal(rec.Body.Bytes(), &got)
+	if len(got) != 2 {
+		t.Fatalf("first pass: want 2, got %d", len(got))
+	}
+
+	// Accept one, dismiss the other.
+	do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/accept", "")
+	do(t, srv, http.MethodPost, "/suggestions/"+got[1].ID+"/dismiss", "")
+
+	// Second checkpoint returns the identical raw batch — both must be suppressed.
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("second check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var again []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &again); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(again) != 0 {
+		t.Fatalf("resolved suggestions should not be re-proposed, got %d: %+v", len(again), again)
+	}
+}
+
+// TestFickleEditsSuppressed proves the suppressor kills the "keeps going back and
+// forth on a few sentences" behavior seen live on the Missing Key doc: a later
+// pass that (a) reverses an edit the user just accepted — even with the editor's
+// double→single quote churn that defeats a byte-exact match — or (b) re-polishes
+// the model's own accepted output. A genuinely new edit on a fresh sentence still
+// survives.
+func TestFickleEditsSuppressed(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[
+		{"original":"He left \"early,\" because of the rain.","replacement":"He left \"early,\" due to the rain.","explanation":"smoother","type":"phrasing"},
+		{"original":"The cat always have a calm face.","replacement":"The cat always has a calm face.","explanation":"agreement","type":"grammar"}
+	]}`}
+	srv, docID, h := newTestServer(t, client)
+	h.Limit = llm.NewRateLimiter(0)
+
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	var got []db.Suggestion
+	_ = json.Unmarshal(rec.Body.Bytes(), &got)
+	if len(got) != 2 {
+		t.Fatalf("first pass: want 2, got %d", len(got))
+	}
+	for _, s := range got {
+		do(t, srv, http.MethodPost, "/suggestions/"+s.ID+"/accept", "")
+	}
+
+	// Reversal of the first accept (note the " → ' quote churn) and a re-polish of
+	// the second accept must both be dropped; only the unrelated edit survives.
+	client.response = `{"suggestions":[
+		{"original":"He left 'early,' due to the rain.","replacement":"He left 'early,' because of the rain.","explanation":"reverts the accepted edit","type":"phrasing"},
+		{"original":"The cat always has a calm face.","replacement":"The cat always seems to have a calm face.","explanation":"re-polishes accepted output","type":"phrasing"},
+		{"original":"due to the rain","replacement":"because of the rain","explanation":"sub-clause reversal of the accepted span","type":"phrasing"},
+		{"original":"She drived home.","replacement":"She drove home.","explanation":"past tense","type":"grammar"}
+	]}`
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	var again []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &again); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(again) != 1 || again[0].Original != "She drived home." {
+		t.Fatalf("want only the new edit to survive, got %d: %+v", len(again), again)
+	}
+}
+
+// TestVoicePassCoexists proves the voice pass and the grammar checkpoint own
+// disjoint pending families: running one never wipes the other's flags, and
+// each endpoint returns the unified pending set.
+func TestVoicePassCoexists(t *testing.T) {
+	// One client serves both passes; the prompt distinguishes them but the stub
+	// just echoes whatever we set before each call.
+	client := &switchClient{}
+	srv, docID, h := newTestServer(t, client)
+	// Zero the voice floor so the test can re-run the pass without waiting out
+	// the real 20s interval; the family-scoping logic is what's under test here.
+	h.VoiceLimit = llm.NewRateLimiter(0)
+
+	// Grammar checkpoint first → one grammar flag.
+	client.response = `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"agreement","type":"grammar"}]}`
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+
+	// Voice pass next → one voice flag (null replacement). It must NOT remove the
+	// grammar flag; the response is the unified set of both.
+	client.response = `{"suggestions":[{"original":"two apple","replacement":null,"explanation":"sounds more formal","type":"voice"}]}`
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/voice", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("voice: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("voice response should carry both families, got %d: %+v", len(got), got)
+	}
+	var grammar, voice *db.Suggestion
+	for i := range got {
+		switch got[i].Type {
+		case db.SuggestionTypeGrammar:
+			grammar = &got[i]
+		case db.SuggestionTypeVoice:
+			voice = &got[i]
+		}
+	}
+	if grammar == nil || voice == nil {
+		t.Fatalf("want one grammar + one voice flag, got %+v", got)
+	}
+	if voice.Replacement != "" {
+		t.Fatalf("voice flag should have empty replacement, got %q", voice.Replacement)
+	}
+
+	// A fresh voice pass that finds nothing replaces only the voice flag; the
+	// grammar one survives.
+	client.response = `{"suggestions":[]}`
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/voice", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("second voice: code=%d body=%s", rec.Code, rec.Body)
+	}
+	_ = json.Unmarshal(rec.Body.Bytes(), &got)
+	if len(got) != 1 || got[0].Type != db.SuggestionTypeGrammar {
+		t.Fatalf("after clearing voice, only the grammar flag should remain, got %+v", got)
+	}
+}
+
+// TestCollocationPassCoexists proves the collocation coach is a third
+// independent family: it never wipes grammar or voice pending flags, a grammar
+// checkpoint never wipes its flags, and each endpoint returns the unified set.
+func TestCollocationPassCoexists(t *testing.T) {
+	client := &switchClient{}
+	srv, docID, h := newTestServer(t, client)
+	// Zero the floors so the test can re-run passes without waiting them out.
+	h.Limit = llm.NewRateLimiter(0)
+	h.VoiceLimit = llm.NewRateLimiter(0)
+	h.CollocationLimit = llm.NewRateLimiter(0)
+
+	// Grammar + voice first, so all three families are exercised.
+	client.response = `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"agreement","type":"grammar"}]}`
+	if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", ""); rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	client.response = `{"suggestions":[{"original":"two apple","replacement":null,"explanation":"sounds formal","type":"voice"}]}`
+	if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/voice", ""); rec.Code != http.StatusOK {
+		t.Fatalf("voice: code=%d body=%s", rec.Code, rec.Body)
+	}
+
+	// Collocation pass → a third flag (with a replacement). It must keep the
+	// grammar and voice flags; the response is the unified set of all three.
+	client.response = `{"suggestions":[{"original":"two apple","replacement":"two apples","explanation":"Natives usually say…","type":"collocation"}]}`
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/collocation", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("collocation: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	byType := map[string]bool{}
+	for _, s := range got {
+		byType[s.Type] = true
+	}
+	if !byType[db.SuggestionTypeGrammar] || !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] {
+		t.Fatalf("collocation response should carry all three families, got %+v", got)
+	}
+
+	// A grammar checkpoint must NOT wipe the voice or collocation flags.
+	client.response = `{"suggestions":[]}`
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("second check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	_ = json.Unmarshal(rec.Body.Bytes(), &got)
+	byType = map[string]bool{}
+	for _, s := range got {
+		byType[s.Type] = true
+	}
+	if byType[db.SuggestionTypeGrammar] {
+		t.Fatalf("grammar flag should have cleared, got %+v", got)
+	}
+	if !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] {
+		t.Fatalf("grammar checkpoint wiped a sibling family, got %+v", got)
+	}
+}
+
+// switchClient returns a response that can be swapped between calls.
+type switchClient struct {
+	response string
+	calls    int
+}
+
+func (s *switchClient) Complete(_ context.Context, _ llm.CompletionRequest) (string, error) {
+	s.calls++
+	return s.response, nil
+}
+
+func (s *switchClient) Stream(_ context.Context, _ llm.CompletionRequest) (<-chan string, error) {
+	ch := make(chan string)
+	close(ch)
+	return ch, nil
+}
+
+func TestCheckpointRateLimit(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"x","type":"grammar"}]}`}
+	srv, docID, _ := newTestServer(t, client)
+
+	// First check runs the model.
+	do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	// Immediate second check is throttled — returns the existing set without
+	// hitting the model again.
+	do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if client.calls != 1 {
+		t.Fatalf("rate limit should suppress the second model call, got %d calls", client.calls)
+	}
+}
+
+// postMechanics submits a deterministic-findings batch (as the client's prose
+// detector would) and returns the unified pending set.
+func postMechanics(t *testing.T, srv http.Handler, docID, findingsJSON string) []db.Suggestion {
+	t.Helper()
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/mechanics", `{"findings":`+findingsJSON+`}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("mechanics: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return got
+}
+
+// TestMechanicsPersistsFindings proves the endpoint persists client-detected
+// findings as a 'mechanics' family with the exact offsets the client supplied,
+// and that a later grammar checkpoint leaves them untouched (own family).
+func TestMechanicsPersistsFindings(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[]}`}
+	srv, docID, _ := newTestServer(t, client)
+
+	got := postMechanics(t, srv, docID, `[
+		{"from":0,"to":1,"original":"i","replacement":"I","explanation":"capitalize I"},
+		{"from":6,"to":13,"original":"the the","replacement":"the","explanation":"doubled word"}
+	]`)
+	var mech []db.Suggestion
+	for _, s := range got {
+		if s.Type == db.SuggestionTypeMechanics {
+			mech = append(mech, s)
+		}
+	}
+	if len(mech) != 2 {
+		t.Fatalf("want 2 mechanics findings, got %d: %+v", len(mech), got)
+	}
+	// The client's exact offsets are preserved verbatim.
+	for _, s := range mech {
+		if s.Original == "the the" && (s.FromPos != 6 || s.ToPos != 13) {
+			t.Errorf("offsets not preserved: %+v", s)
+		}
+	}
+
+	// A grammar checkpoint must not wipe the mechanics family.
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var after []db.Suggestion
+	_ = json.Unmarshal(rec.Body.Bytes(), &after)
+	count := 0
+	for _, s := range after {
+		if s.Type == db.SuggestionTypeMechanics {
+			count++
+		}
+	}
+	if count != 2 {
+		t.Fatalf("grammar checkpoint disturbed the mechanics family: got %d, want 2", count)
+	}
+}
+
+// TestMechanicsWinsSpanCollision proves that when a mechanics finding and an LLM
+// grammar suggestion claim overlapping characters, the LLM card is dropped from
+// the response and the exact mechanics fix owns the span.
+func TestMechanicsWinsSpanCollision(t *testing.T) {
+	// LLM grammar suggestion covers "the the cat", overlapping the mechanics
+	// "the the" finding at [0,7].
+	client := &stubClient{response: `{"suggestions":[
+		{"original":"the the cat","replacement":"the cat","explanation":"wordy","type":"grammar"}
+	]}`}
+	srv, docID, h := newTestServer(t, client)
+	if _, err := h.DB.Exec(`UPDATE documents SET content_text = ? WHERE id = ?`, "the the cat sat", docID); err != nil {
+		t.Fatalf("set content: %v", err)
+	}
+
+	// Persist the mechanics finding, then run the grammar pass.
+	postMechanics(t, srv, docID, `[{"from":0,"to":7,"original":"the the","replacement":"the","explanation":"doubled word"}]`)
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	for _, s := range got {
+		if s.Type == db.SuggestionTypeGrammar {
+			t.Fatalf("overlapping grammar card should have been dropped in favor of mechanics, got %+v", got)
+		}
+	}
+	if len(got) != 1 || got[0].Type != db.SuggestionTypeMechanics {
+		t.Fatalf("want sole mechanics finding, got %+v", got)
+	}
+}
+
+// TestMechanicsActionedSuppression proves a dismissed mechanics fix is not
+// re-proposed on the next submission of the same finding.
+func TestMechanicsActionedSuppression(t *testing.T) {
+	client := &stubClient{response: `{"suggestions":[]}`}
+	srv, docID, _ := newTestServer(t, client)
+
+	findings := `[{"from":6,"to":13,"original":"the the","replacement":"the","explanation":"doubled word"}]`
+	got := postMechanics(t, srv, docID, findings)
+	if len(got) != 1 {
+		t.Fatalf("want 1 finding, got %+v", got)
+	}
+	// Dismiss it, then resubmit the same finding — it must stay suppressed.
+	do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/dismiss", "")
+	again := postMechanics(t, srv, docID, findings)
+	if len(again) != 0 {
+		t.Fatalf("dismissed mechanics fix should not reappear, got %+v", again)
+	}
+}

internal/suggestions/rewrite.go

@@ -0,0 +1,77 @@
+package suggestions
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// rewriteRequest is the body the selection bubble posts: the selected passage
+// and the target style ("natural", "academic", …). The text is the client's
+// live selection — unlike a checkpoint, there is nothing to anchor server-side,
+// so the rewrite is stateless and never persisted (the editor applies it
+// directly, and the version history captures the resulting document change).
+type rewriteRequest struct {
+	Text  string `json:"text"`
+	Style string `json:"style"`
+}
+
+type rewriteResponse struct {
+	Rewrite string `json:"rewrite"`
+}
+
+// rewrite runs a one-shot tone-rewrite over a selected passage and returns the
+// rewritten text for the editor to preview. The document id scopes the request
+// to the owner (and reserves room to feed document context to the model later),
+// even though the passage itself rides in the body.
+func (h *Handler) rewrite(w http.ResponseWriter, r *http.Request) {
+	docID := chi.URLParam(r, "id")
+
+	var body rewriteRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body")
+		return
+	}
+
+	text := strings.TrimSpace(body.Text)
+	if text == "" {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "no text to rewrite")
+		return
+	}
+	if len([]rune(text)) > llm.RewriteMaxRunes {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "selection too long to rewrite")
+		return
+	}
+
+	// Scope to the owner so a stray id can't drive rewrites against another
+	// user's document (and 404 cleanly when it doesn't exist).
+	var exists int
+	err := h.DB.QueryRow(
+		`SELECT 1 FROM documents WHERE id = ? AND user_id = ?`,
+		docID, db.LocalUserID,
+	).Scan(&exists)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := llm.RunRewrite(r.Context(), h.Client, text, body.Style)
+	if err != nil {
+		httputil.ErrorJSON(w, http.StatusBadGateway, "rewrite failed: "+err.Error())
+		return
+	}
+
+	httputil.WriteJSON(w, http.StatusOK, rewriteResponse{Rewrite: out})
+}

internal/suggestions/rewrite_test.go

@@ -0,0 +1,79 @@
+package suggestions
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+// recordingClient captures the last Complete request so the rewrite test can
+// assert the styled system prompt and the selected passage reached the model.
+type recordingClient struct {
+	response string
+	last     llm.CompletionRequest
+}
+
+func (c *recordingClient) Complete(_ context.Context, req llm.CompletionRequest) (string, error) {
+	c.last = req
+	return c.response, nil
+}
+
+func (c *recordingClient) Stream(_ context.Context, _ llm.CompletionRequest) (<-chan string, error) {
+	ch := make(chan string)
+	close(ch)
+	return ch, nil
+}
+
+func TestRewrite(t *testing.T) {
+	// The model wraps its answer in quotes; cleanRewrite should strip them.
+	client := &recordingClient{response: `"I have two apples."`}
+	srv, docID, _ := newTestServer(t, client)
+
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/rewrite",
+		`{"text":"I has two apple.","style":"academic"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("rewrite: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var resp rewriteResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.Rewrite != "I have two apples." {
+		t.Fatalf("rewrite = %q, want the de-quoted text", resp.Rewrite)
+	}
+
+	// The passage rode in as the user turn, and the style steered the system turn.
+	msgs := client.last.Messages
+	if len(msgs) != 2 || msgs[0].Role != "system" || msgs[1].Role != "user" {
+		t.Fatalf("unexpected message shape: %+v", msgs)
+	}
+	if msgs[1].Content != "I has two apple." {
+		t.Fatalf("passage not forwarded: %q", msgs[1].Content)
+	}
+	if !strings.Contains(msgs[0].Content, "academic") {
+		t.Fatalf("system prompt missing academic style guidance:\n%s", msgs[0].Content)
+	}
+}
+
+func TestRewriteEmptyText(t *testing.T) {
+	client := &recordingClient{response: "anything"}
+	srv, docID, _ := newTestServer(t, client)
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/rewrite", `{"text":"   ","style":"natural"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("empty text: want 400, got %d", rec.Code)
+	}
+}
+
+func TestRewriteUnknownDoc(t *testing.T) {
+	client := &recordingClient{response: "anything"}
+	srv, _, _ := newTestServer(t, client)
+	rec := do(t, srv, http.MethodPost, "/docs/does-not-exist/rewrite",
+		`{"text":"hello there","style":"natural"}`)
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("unknown doc: want 404, got %d", rec.Code)
+	}
+}

internal/suggestions/translate.go

@@ -0,0 +1,58 @@
+package suggestions
+
+import (
+	"database/sql"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+	"gitea.parodia.dev/drwily/petal/internal/llm"
+)
+
+type translateResponse struct {
+	Translation string `json:"translation"`
+}
+
+// translate renders a suggestion's English explanation into Simplified Chinese
+// for the Ask Petal bubble, so the ESL reader sees the "why" in her first
+// language instead of a second copy of the same English text. The explanation is
+// loaded server-side from the suggestion id (scoped to the local user) and never
+// trusted from the client, mirroring chat (spec Note #10).
+func (h *Handler) translate(w http.ResponseWriter, r *http.Request) {
+	sugID := chi.URLParam(r, "id")
+
+	var explanation string
+	err := h.DB.QueryRow(
+		`SELECT s.explanation
+		   FROM suggestions s
+		   JOIN documents d ON d.id = s.doc_id
+		  WHERE s.id = ? AND d.user_id = ?`,
+		sugID, db.LocalUserID,
+	).Scan(&explanation)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	explanation = strings.TrimSpace(explanation)
+	if explanation == "" {
+		httputil.WriteJSON(w, http.StatusOK, translateResponse{Translation: ""})
+		return
+	}
+
+	out, err := llm.RunTranslate(r.Context(), h.Client, explanation)
+	if err != nil {
+		httputil.ErrorJSON(w, http.StatusBadGateway, "translate failed: "+err.Error())
+		return
+	}
+
+	httputil.WriteJSON(w, http.StatusOK, translateResponse{Translation: out})
+}

internal/tts/handler.go

@@ -0,0 +1,264 @@
+// Package tts implements read-aloud: it proxies short passages to a local Piper
+// HTTP server (a fast, offline neural TTS), optionally transcodes Piper's WAV to
+// mp3/opus with ffmpeg, and serves the audio back to the editor. Synthesized
+// clips are content-addressed on disk so tapping the same word twice is instant
+// and never re-synthesizes. The feature is entirely optional: when TTS_ENDPOINT
+// is unset the route isn't mounted and the frontend falls back to the browser's
+// Web Speech API.
+package tts
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/config"
+)
+
+// maxTextBytes bounds a single synthesis request. Read-aloud is for a word or a
+// sentence or two, not whole documents; this keeps one tap from pinning Piper.
+const maxTextBytes = 4000
+
+// lengthScale slows Piper slightly below natural pace — a learner following along
+// with the words, mirroring the old utterance.rate = 0.95. Higher = slower.
+const lengthScale = 1.1
+
+// audioFormat describes one output encoding: the cache-file extension, the
+// response Content-Type, and the ffmpeg args that turn Piper's WAV (on stdin)
+// into this format (on stdout). A nil ffmpegArgs means "serve the WAV as-is".
+type audioFormat struct {
+	ext         string
+	contentType string
+	ffmpegArgs  []string
+}
+
+// formats maps the configured TTS_AUDIO_FORMAT to its encoding. mp3 is the safe
+// default (every browser plays it); opus is ~half the size for speech but has
+// patchier Safari support; wav skips ffmpeg entirely.
+var formats = map[string]audioFormat{
+	"wav": {ext: ".wav", contentType: "audio/wav"},
+	"mp3": {ext: ".mp3", contentType: "audio/mpeg",
+		ffmpegArgs: []string{"-f", "mp3", "-c:a", "libmp3lame", "-b:a", "64k", "-ac", "1"}},
+	"opus": {ext: ".opus", contentType: "audio/ogg",
+		ffmpegArgs: []string{"-f", "ogg", "-c:a", "libopus", "-b:a", "32k", "-ac", "1"}},
+}
+
+// route is the Piper instance and voice id serving one language. Each Piper
+// HTTP server loads exactly one model, so distinct languages mean distinct
+// endpoints (e.g. English on :5005, Chinese on :5006).
+type route struct {
+	endpoint string // Piper HTTP base URL (no trailing slash)
+	voice    string // Piper voice id (sent in the request; also part of the cache key)
+}
+
+// Handler proxies synthesis to Piper and caches the result on disk.
+type Handler struct {
+	routes   map[string]route // base language (e.g. "en", "zh") -> Piper instance
+	cacheDir string
+	format   audioFormat
+	client   *http.Client
+}
+
+// New builds a Handler from config. It returns (nil, false) when TTS_ENDPOINT is
+// unset, signalling main to skip mounting the route. An unknown TTS_AUDIO_FORMAT
+// falls back to mp3 rather than failing the whole server.
+func New(cfg *config.Config) (*Handler, bool) {
+	if strings.TrimSpace(cfg.TTSEndpoint) == "" {
+		return nil, false
+	}
+
+	format, ok := formats[strings.ToLower(strings.TrimSpace(cfg.TTSFormat))]
+	if !ok {
+		format = formats["mp3"]
+	}
+
+	// Map by base language so en-US, en-GB, etc. all resolve to the English
+	// instance (the client sends BCP-47 tags like the old Web Speech path did).
+	// A language is only routable when both its endpoint and voice are set;
+	// otherwise the client falls back to Web Speech for that language.
+	routes := map[string]route{}
+	if cfg.TTSVoiceEN != "" {
+		routes["en"] = route{strings.TrimRight(cfg.TTSEndpoint, "/"), cfg.TTSVoiceEN}
+	}
+	if cfg.TTSEndpointZH != "" && cfg.TTSVoiceZH != "" {
+		routes["zh"] = route{strings.TrimRight(cfg.TTSEndpointZH, "/"), cfg.TTSVoiceZH}
+	}
+
+	if err := os.MkdirAll(cfg.TTSCacheDir, 0o755); err != nil {
+		// A missing cache dir isn't fatal — synthesis still works, it just won't
+		// cache. Disable the feature only on endpoint absence, not this.
+		fmt.Fprintf(os.Stderr, "tts: cache dir %q: %v\n", cfg.TTSCacheDir, err)
+	}
+
+	return &Handler{
+		routes:   routes,
+		cacheDir: cfg.TTSCacheDir,
+		format:   format,
+		client:   &http.Client{Timeout: cfg.TTSTimeout},
+	}, true
+}
+
+// Routes mounts the synthesis endpoint. Mount under "/tts" so the full path is
+// POST /api/tts.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Post("/", h.synth)
+	return r
+}
+
+// synthRequest is the body the editor posts: a passage and the BCP-47 language
+// tag it's written in (e.g. "en-US", "zh-CN").
+type synthRequest struct {
+	Text string `json:"text"`
+	Lang string `json:"lang"`
+}
+
+// synth resolves a voice for the requested language, returns cached audio when
+// present, and otherwise asks Piper to synthesize, transcodes if configured,
+// caches, and serves. An unconfigured language yields 404 so the client can fall
+// back to Web Speech without treating it as an error.
+func (h *Handler) synth(w http.ResponseWriter, r *http.Request) {
+	var req synthRequest
+	// Cap the raw body generously above maxTextBytes to leave room for JSON
+	// framing and the lang field; the text itself is truncated after decoding.
+	if err := json.NewDecoder(io.LimitReader(r.Body, maxTextBytes+1024)).Decode(&req); err != nil {
+		http.Error(w, "invalid request body", http.StatusBadRequest)
+		return
+	}
+	text := strings.TrimSpace(req.Text)
+	if text == "" {
+		http.Error(w, "empty text", http.StatusBadRequest)
+		return
+	}
+	if len(text) > maxTextBytes {
+		// Trim back to the last valid rune boundary so we never hand Piper a
+		// half-encoded multibyte character (common with Chinese, 3 bytes/char).
+		text = text[:maxTextBytes]
+		for len(text) > 0 && !utf8.ValidString(text) {
+			text = text[:len(text)-1]
+		}
+	}
+
+	rt, ok := h.routes[baseLang(req.Lang)]
+	if !ok {
+		// No voice for this language — let the client fall back to Web Speech.
+		http.Error(w, "no voice for language", http.StatusNotFound)
+		return
+	}
+
+	// Content-addressed: identical (voice, text) → identical clip. The format
+	// extension keeps encodings from colliding in the same dir.
+	sum := sha256.Sum256([]byte(rt.voice + "\n" + text))
+	name := hex.EncodeToString(sum[:])[:32] + h.format.ext
+	path := filepath.Join(h.cacheDir, name)
+
+	if _, err := os.Stat(path); err == nil {
+		h.serve(w, r, path)
+		return
+	}
+
+	audio, err := h.synthesize(r.Context(), rt, text)
+	if err != nil {
+		http.Error(w, "synthesis failed", http.StatusBadGateway)
+		fmt.Fprintf(os.Stderr, "tts: synthesize: %v\n", err)
+		return
+	}
+
+	// Best-effort cache write via a temp file + rename so a concurrent reader
+	// never sees a half-written clip. A failed write just means no caching.
+	if h.cacheDir != "" {
+		tmp := path + ".tmp"
+		if err := os.WriteFile(tmp, audio, 0o644); err == nil {
+			_ = os.Rename(tmp, path)
+		}
+	}
+
+	w.Header().Set("Content-Type", h.format.contentType)
+	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	_, _ = w.Write(audio)
+}
+
+// serve streams a cached clip with a long-lived immutable cache header (the URL
+// is content-addressed, so the bytes never change for a given request).
+func (h *Handler) serve(w http.ResponseWriter, r *http.Request, path string) {
+	w.Header().Set("Content-Type", h.format.contentType)
+	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	http.ServeFile(w, r, path)
+}
+
+// synthesize POSTs to the route's Piper instance, then transcodes the returned
+// WAV when the configured format calls for it.
+func (h *Handler) synthesize(ctx context.Context, rt route, text string) ([]byte, error) {
+	body, _ := json.Marshal(map[string]any{
+		"text":         text,
+		"voice":        rt.voice,
+		"length_scale": lengthScale,
+	})
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, rt.endpoint+"/", bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+
+	resp, err := h.client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
+		return nil, fmt.Errorf("piper %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet)))
+	}
+	wav, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+
+	if h.format.ffmpegArgs == nil {
+		return wav, nil
+	}
+	return transcode(ctx, wav, h.format.ffmpegArgs)
+}
+
+// transcode pipes WAV bytes through ffmpeg (stdin → stdout) into the target
+// encoding. ffmpeg is assumed on PATH; an error here surfaces as a 502.
+func transcode(ctx context.Context, wav []byte, args []string) ([]byte, error) {
+	// Guard ffmpeg against a hang independent of the HTTP client timeout.
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	full := append([]string{"-hide_banner", "-loglevel", "error", "-i", "pipe:0"}, args...)
+	full = append(full, "pipe:1")
+	cmd := exec.CommandContext(ctx, "ffmpeg", full...)
+	cmd.Stdin = bytes.NewReader(wav)
+	var out, errBuf bytes.Buffer
+	cmd.Stdout = &out
+	cmd.Stderr = &errBuf
+	if err := cmd.Run(); err != nil {
+		return nil, fmt.Errorf("ffmpeg: %v: %s", err, strings.TrimSpace(errBuf.String()))
+	}
+	return out.Bytes(), nil
+}
+
+// baseLang reduces a BCP-47 tag to its primary subtag, lowercased: "en-US" → "en",
+// "zh-CN" → "zh", "" → "". Mirrors the client's pickVoice base-language matching.
+func baseLang(tag string) string {
+	tag = strings.ToLower(strings.TrimSpace(tag))
+	if i := strings.IndexAny(tag, "-_"); i >= 0 {
+		return tag[:i]
+	}
+	return tag
+}

internal/tts/handler_test.go

@@ -0,0 +1,170 @@
+package tts
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+// newStubPiper returns a fake Piper server that echoes a fixed WAV body and
+// records how many times it was called and the last request payload.
+func newStubPiper(t *testing.T, body []byte) (*httptest.Server, *int32, *synthEcho) {
+	t.Helper()
+	var calls int32
+	last := &synthEcho{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		var req map[string]any
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		last.voice, _ = req["voice"].(string)
+		last.text, _ = req["text"].(string)
+		w.Header().Set("Content-Type", "audio/wav")
+		_, _ = w.Write(body)
+	}))
+	t.Cleanup(srv.Close)
+	return srv, &calls, last
+}
+
+type synthEcho struct{ voice, text string }
+
+// newHandler builds a wav-format handler (no ffmpeg) pointed at a stub server.
+func newHandler(t *testing.T, endpoint string) *Handler {
+	t.Helper()
+	return &Handler{
+		routes:   map[string]route{"en": {strings.TrimRight(endpoint, "/"), "en_US-amy-medium"}},
+		cacheDir: t.TempDir(),
+		format:   formats["wav"],
+		client:   http.DefaultClient,
+	}
+}
+
+func post(t *testing.T, h *Handler, text, lang string) *httptest.ResponseRecorder {
+	t.Helper()
+	b, _ := json.Marshal(synthRequest{Text: text, Lang: lang})
+	req := httptest.NewRequest(http.MethodPost, "/", bytes.NewReader(b))
+	rr := httptest.NewRecorder()
+	h.synth(rr, req)
+	return rr
+}
+
+func TestSynthSuccessAndVoiceSelection(t *testing.T) {
+	wav := []byte("RIFF....fake-wav")
+	srv, calls, last := newStubPiper(t, wav)
+	h := newHandler(t, srv.URL)
+
+	rr := post(t, h, "hello there", "en-US")
+	if rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rr.Code)
+	}
+	if got := rr.Body.Bytes(); !bytes.Equal(got, wav) {
+		t.Fatalf("body = %q, want the piper wav", got)
+	}
+	if ct := rr.Header().Get("Content-Type"); ct != "audio/wav" {
+		t.Fatalf("content-type = %q, want audio/wav", ct)
+	}
+	if last.voice != "en_US-amy-medium" {
+		t.Fatalf("piper voice = %q, want en_US-amy-medium", last.voice)
+	}
+	if *calls != 1 {
+		t.Fatalf("piper calls = %d, want 1", *calls)
+	}
+}
+
+func TestRoutesByLanguageToSeparateInstances(t *testing.T) {
+	enSrv, enCalls, _ := newStubPiper(t, []byte("EN-wav"))
+	zhSrv, zhCalls, zhLast := newStubPiper(t, []byte("ZH-wav"))
+	h := &Handler{
+		routes: map[string]route{
+			"en": {strings.TrimRight(enSrv.URL, "/"), "en_US-amy-medium"},
+			"zh": {strings.TrimRight(zhSrv.URL, "/"), "zh_CN-huayan-medium"},
+		},
+		cacheDir: t.TempDir(),
+		format:   formats["wav"],
+		client:   http.DefaultClient,
+	}
+
+	if rr := post(t, h, "你好世界", "zh-CN"); rr.Code != http.StatusOK {
+		t.Fatalf("zh status = %d, want 200", rr.Code)
+	}
+	if *zhCalls != 1 || *enCalls != 0 {
+		t.Fatalf("calls en=%d zh=%d, want en=0 zh=1 (zh routed to zh instance)", *enCalls, *zhCalls)
+	}
+	if zhLast.voice != "zh_CN-huayan-medium" {
+		t.Fatalf("zh voice = %q, want zh_CN-huayan-medium", zhLast.voice)
+	}
+}
+
+func TestUnknownLanguageReturns404(t *testing.T) {
+	srv, calls, _ := newStubPiper(t, []byte("x"))
+	h := newHandler(t, srv.URL)
+
+	rr := post(t, h, "你好", "zh-CN") // only "en" is configured
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404", rr.Code)
+	}
+	if *calls != 0 {
+		t.Fatalf("piper calls = %d, want 0 (should not synthesize)", *calls)
+	}
+}
+
+func TestCacheHitSkipsPiper(t *testing.T) {
+	srv, calls, _ := newStubPiper(t, []byte("RIFF....fake-wav"))
+	h := newHandler(t, srv.URL)
+
+	if rr := post(t, h, "same words", "en-US"); rr.Code != http.StatusOK {
+		t.Fatalf("first status = %d, want 200", rr.Code)
+	}
+	if rr := post(t, h, "same words", "en-US"); rr.Code != http.StatusOK {
+		t.Fatalf("second status = %d, want 200", rr.Code)
+	}
+	if *calls != 1 {
+		t.Fatalf("piper calls = %d, want 1 (second served from cache)", *calls)
+	}
+}
+
+func TestEmptyTextReturns400(t *testing.T) {
+	srv, _, _ := newStubPiper(t, []byte("x"))
+	h := newHandler(t, srv.URL)
+
+	if rr := post(t, h, "   ", "en-US"); rr.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400", rr.Code)
+	}
+}
+
+func TestTextIsCapped(t *testing.T) {
+	srv, _, last := newStubPiper(t, []byte("x"))
+	h := newHandler(t, srv.URL)
+
+	long := strings.Repeat("a", maxTextBytes+500)
+	if rr := post(t, h, long, "en-US"); rr.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rr.Code)
+	}
+	if len(last.text) != maxTextBytes {
+		t.Fatalf("piper received %d chars, want capped to %d", len(last.text), maxTextBytes)
+	}
+}
+
+func TestBaseLang(t *testing.T) {
+	cases := map[string]string{"en-US": "en", "EN_gb": "en", "zh-CN": "zh", "en": "en", "": ""}
+	for in, want := range cases {
+		if got := baseLang(in); got != want {
+			t.Errorf("baseLang(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// ensure the stub's body is fully consumable (guards against the LimitReader cap
+// accidentally truncating a normal request body in synth()).
+func TestRequestBodyNotTruncated(t *testing.T) {
+	srv, _, last := newStubPiper(t, []byte("x"))
+	h := newHandler(t, srv.URL)
+	text := strings.Repeat("word ", 200) // ~1000 bytes, under the cap
+	post(t, h, text, "en-US")
+	if last.text != strings.TrimSpace(text) {
+		t.Fatalf("piper text length = %d, want %d", len(last.text), len(strings.TrimSpace(text)))
+	}
+}

internal/vocab/handlers.go

@@ -0,0 +1,307 @@
+package vocab
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// Word is one entry in the vocabulary garden: the looked-up word with its gloss,
+// phonetic, and the sentence it was met in, plus its spaced-repetition state.
+type Word struct {
+	ID           string     `json:"id"`
+	Word         string     `json:"word"`
+	Gloss        string     `json:"gloss"`
+	Definition   string     `json:"definition"` // English fallback meaning when there's no Chinese gloss
+	Phonetic     string     `json:"phonetic"`
+	Example      string     `json:"example"`
+	DocID        *string    `json:"doc_id"`
+	DueAt        time.Time  `json:"due_at"`
+	IntervalDays int        `json:"interval_days"`
+	Ease         float64    `json:"ease"`
+	Reps         int        `json:"reps"`
+	Lapses       int        `json:"lapses"`
+	LastReviewed *time.Time `json:"last_reviewed"`
+	CreatedAt    time.Time  `json:"created_at"`
+}
+
+// Handler owns the vocabulary-garden routes. Everything is scoped to the local
+// user while auth is deferred.
+type Handler struct {
+	DB *db.DB
+}
+
+func New(database *db.DB) *Handler { return &Handler{DB: database} }
+
+// Routes mounts the garden endpoints under /api/vocab.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)     // the whole garden
+	r.Get("/due", h.due)   // only the cards due for review now
+	r.Post("/", h.capture) // record/upsert a looked-up word
+	r.Post("/{id}/review", h.review)
+	r.Delete("/{id}", h.remove)
+	return r
+}
+
+const vocabColumns = `id, word, gloss, definition, phonetic, example, doc_id,
+	due_at, interval_days, ease, reps, lapses, last_reviewed, created_at`
+
+func scanWord(s interface {
+	Scan(dest ...any) error
+}) (Word, error) {
+	var w Word
+	err := s.Scan(
+		&w.ID, &w.Word, &w.Gloss, &w.Definition, &w.Phonetic, &w.Example, &w.DocID,
+		&w.DueAt, &w.IntervalDays, &w.Ease, &w.Reps, &w.Lapses, &w.LastReviewed, &w.CreatedAt,
+	)
+	return w, err
+}
+
+// list returns the full garden, newest blossoms first.
+func (h *Handler) list(w http.ResponseWriter, _ *http.Request) {
+	h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words
+		WHERE user_id = ? ORDER BY created_at DESC`, db.LocalUserID)
+}
+
+// due returns only the cards whose review time has arrived, soonest first.
+func (h *Handler) due(w http.ResponseWriter, _ *http.Request) {
+	h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words
+		WHERE user_id = ? AND due_at <= datetime('now') ORDER BY due_at ASC`, db.LocalUserID)
+}
+
+func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) {
+	rows, err := h.DB.Query(query, args...)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+	out := []Word{}
+	for rows.Next() {
+		word, err := scanWord(rows)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		out = append(out, word)
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+type captureRequest struct {
+	Word       string  `json:"word"`
+	Gloss      string  `json:"gloss"`
+	Definition string  `json:"definition"`
+	Phonetic   string  `json:"phonetic"`
+	Example    string  `json:"example"`
+	DocID      *string `json:"doc_id"`
+}
+
+// Field-length caps. The captured fields come from the offline lexicon and the
+// editor selection, not free-typed prose, so we clamp rather than reject — a
+// lookup should never fail because a definition ran long. Counts are runes so a
+// Chinese gloss isn't cut mid-character. The word is the upsert key, so an absurd
+// "word" is bounded too.
+const (
+	maxWordLen       = 128
+	maxGlossLen      = 512
+	maxDefinitionLen = 4096
+	maxPhoneticLen   = 256
+	maxExampleLen    = 4096
+)
+
+// clamp trims s to at most max runes (rune-safe so multibyte glosses survive).
+func clamp(s string, max int) string {
+	r := []rune(s)
+	if len(r) <= max {
+		return s
+	}
+	return string(r[:max])
+}
+
+// capture records a looked-up word. It's an idempotent upsert keyed on the word:
+// a new word lands due tomorrow (interval 1 day); an existing word keeps its
+// schedule untouched but refreshes its gloss/phonetic/example/doc_id so the most
+// recent context wins. Looking words up IS the data source — no extra effort.
+func (h *Handler) capture(w http.ResponseWriter, r *http.Request) {
+	var req captureRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+	// Normalize the same way the lexicon does (internal/lexicon: lower+trim) so
+	// the UNIQUE(user_id, word) upsert is genuinely idempotent — otherwise
+	// "Apple" at a sentence start and "apple" mid-line would create two separate
+	// cards on independent schedules.
+	word := clamp(strings.ToLower(strings.TrimSpace(req.Word)), maxWordLen)
+	if word == "" {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "word is required")
+		return
+	}
+	req.Gloss = clamp(req.Gloss, maxGlossLen)
+	req.Definition = clamp(req.Definition, maxDefinitionLen)
+	req.Phonetic = clamp(req.Phonetic, maxPhoneticLen)
+	req.Example = clamp(req.Example, maxExampleLen)
+
+	// A blank doc_id is the same as none; otherwise the word must belong to a
+	// document the user actually owns. Without this check a stale or forged id
+	// would hit the foreign key and leak a raw "FOREIGN KEY constraint" 500
+	// instead of a clean 400 (and, once auth lands, would let a word be attached
+	// to another user's document).
+	if req.DocID != nil {
+		if strings.TrimSpace(*req.DocID) == "" {
+			req.DocID = nil
+		} else {
+			var ok int
+			err := h.DB.QueryRow(
+				`SELECT 1 FROM documents WHERE id = ? AND user_id = ?`,
+				*req.DocID, db.LocalUserID,
+			).Scan(&ok)
+			if errors.Is(err, sql.ErrNoRows) {
+				httputil.ErrorJSON(w, http.StatusBadRequest, "unknown doc_id")
+				return
+			}
+			if err != nil {
+				httputil.ServerError(w, err)
+				return
+			}
+		}
+	}
+
+	// New rows start due tomorrow; ON CONFLICT refreshes context but leaves the
+	// schedule (due_at/reps/interval/ease) alone so re-looking-up a word never
+	// resets its progress.
+	_, err := h.DB.Exec(
+		`INSERT INTO vocab_words (user_id, word, gloss, definition, phonetic, example, doc_id, due_at, interval_days)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now', '+1 day'), 1)
+		 ON CONFLICT(user_id, word) DO UPDATE SET
+		   gloss      = excluded.gloss,
+		   definition = excluded.definition,
+		   phonetic   = excluded.phonetic,
+		   example    = CASE WHEN excluded.example != '' THEN excluded.example ELSE vocab_words.example END,
+		   doc_id     = COALESCE(excluded.doc_id, vocab_words.doc_id)`,
+		db.LocalUserID, word, req.Gloss, req.Definition, req.Phonetic, req.Example, req.DocID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := h.fetch(word)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusCreated, out)
+}
+
+// fetch loads one word row by its (user, word) key.
+func (h *Handler) fetch(word string) (Word, error) {
+	return scanWord(h.DB.QueryRow(
+		`SELECT `+vocabColumns+` FROM vocab_words WHERE user_id = ? AND word = ?`,
+		db.LocalUserID, word,
+	))
+}
+
+type reviewRequest struct {
+	Grade Grade `json:"grade"`
+}
+
+// review grades one card and reschedules it. The grade drives the SM-2-lite
+// scheduler; the new interval is applied as `due_at = now + interval days`.
+func (h *Handler) review(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	var req reviewRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+	if req.Grade != GradeAgain && req.Grade != GradeGood && req.Grade != GradeEasy {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "grade must be again, good, or easy")
+		return
+	}
+
+	// The grade is computed in Go (the SM-2-lite scheduler), so the read and the
+	// write must be one atomic unit: a bare SELECT-then-UPDATE could interleave
+	// with a concurrent review of the same card and lose an update. Wrap both in a
+	// transaction.
+	tx, err := h.DB.Begin()
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer tx.Rollback() // no-op once committed
+
+	var cur State
+	err = tx.QueryRow(
+		`SELECT reps, interval_days, ease, lapses FROM vocab_words WHERE id = ? AND user_id = ?`,
+		id, db.LocalUserID,
+	).Scan(&cur.Reps, &cur.Interval, &cur.Ease, &cur.Lapses)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "word not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	nxt := cur.next(req.Grade)
+	// `datetime('now', '+N days')` keeps the stored value in SQLite's canonical
+	// text format, matching CURRENT_TIMESTAMP and the due query's comparison.
+	offset := "+" + strconv.Itoa(nxt.Interval) + " days"
+	if _, err := tx.Exec(
+		`UPDATE vocab_words SET
+		   reps = ?, interval_days = ?, ease = ?, lapses = ?,
+		   last_reviewed = datetime('now'), due_at = datetime('now', ?)
+		 WHERE id = ? AND user_id = ?`,
+		nxt.Reps, nxt.Interval, nxt.Ease, nxt.Lapses, offset, id, db.LocalUserID,
+	); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := scanWord(tx.QueryRow(
+		`SELECT `+vocabColumns+` FROM vocab_words WHERE id = ? AND user_id = ?`, id, db.LocalUserID,
+	))
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if err := tx.Commit(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// remove deletes a word from the garden (e.g. the writer already knows it).
+func (h *Handler) remove(w http.ResponseWriter, r *http.Request) {
+	res, err := h.DB.Exec(
+		`DELETE FROM vocab_words WHERE id = ? AND user_id = ?`,
+		chi.URLParam(r, "id"), db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		httputil.ErrorJSON(w, http.StatusNotFound, "word not found")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/vocab/handlers_test.go

@@ -0,0 +1,249 @@
+package vocab
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+func newTestServer(t *testing.T) (http.Handler, *db.DB) {
+	t.Helper()
+	database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { database.Close() })
+	r := chi.NewRouter()
+	r.Mount("/vocab", New(database).Routes())
+	return r, database
+}
+
+func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	} else {
+		r = httptest.NewRequest(method, path, nil)
+	}
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, r)
+	return rec
+}
+
+// TestCaptureUpsertAndReview walks the garden lifecycle: capture a word (lands
+// in the future, not yet due), re-capture refreshes context without resetting
+// schedule, a forced-due word shows up in /due, a review reschedules it, and
+// delete removes it.
+func TestCaptureUpsertAndReview(t *testing.T) {
+	srv, database := newTestServer(t)
+
+	// Capture a new word → 201, due tomorrow (interval 1), not in /due yet.
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"serendipity","gloss":"机缘巧合","phonetic":"/ˌserənˈdɪpəti/","example":"What a serendipity."}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if w.ID == "" || w.Word != "serendipity" || w.Gloss != "机缘巧合" {
+		t.Fatalf("captured word wrong: %+v", w)
+	}
+	if w.IntervalDays != 1 || w.Reps != 0 {
+		t.Fatalf("new word should start at interval 1, reps 0: %+v", w)
+	}
+
+	// Not due yet (due tomorrow).
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	var due []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 0 {
+		t.Fatalf("freshly-captured word should not be due yet, got %d", len(due))
+	}
+
+	// Re-capture with a new gloss → still one row (idempotent upsert), refreshed.
+	rec = do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"serendipity","gloss":"意外的好运","phonetic":"/x/","example":""}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("re-capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("re-capture should not add a row, got %d", len(all))
+	}
+	if all[0].Gloss != "意外的好运" {
+		t.Fatalf("gloss should refresh on re-capture, got %q", all[0].Gloss)
+	}
+	if all[0].Example != "What a serendipity." {
+		t.Fatalf("empty example should not clobber the prior one, got %q", all[0].Example)
+	}
+
+	// Force it due now, then it appears in /due.
+	if _, err := database.Exec(`UPDATE vocab_words SET due_at = datetime('now','-1 hour')`); err != nil {
+		t.Fatalf("force due: %v", err)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 1 {
+		t.Fatalf("forced-due word should be in /due, got %d", len(due))
+	}
+
+	// Review "good" → reschedules forward (interval 3 = second ladder rung, since
+	// reps was 0 and a capture set interval 1 but reps 0; first good → rung 1 = 1).
+	rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"good"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("review: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var reviewed Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &reviewed)
+	if reviewed.Reps != 1 || reviewed.IntervalDays != 1 {
+		t.Fatalf("first good review should be reps 1, interval 1: %+v", reviewed)
+	}
+	if reviewed.LastReviewed == nil {
+		t.Fatalf("review should stamp last_reviewed")
+	}
+
+	// After a forward review it's no longer due.
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 0 {
+		t.Fatalf("reviewed word should leave /due, got %d", len(due))
+	}
+
+	// Bad grade → 400.
+	if rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"nope"}`); rec.Code != http.StatusBadRequest {
+		t.Fatalf("bad grade: want 400, got %d", rec.Code)
+	}
+
+	// Delete → 204, garden empty.
+	if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("delete: code=%d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNotFound {
+		t.Fatalf("re-delete: want 404, got %d", rec.Code)
+	}
+}
+
+// TestCaptureValidation rejects an empty word.
+func TestCaptureValidation(t *testing.T) {
+	srv, _ := newTestServer(t)
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"   "}`); rec.Code != http.StatusBadRequest {
+		t.Fatalf("empty word: want 400, got %d", rec.Code)
+	}
+}
+
+// TestCaptureStoresDefinitionFallback proves a word with an English definition
+// but no Chinese gloss still round-trips its definition, so review has a meaning
+// to reveal instead of a blank card.
+func TestCaptureStoresDefinitionFallback(t *testing.T) {
+	srv, _ := newTestServer(t)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"ineffable","definition":"too great to be expressed in words"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if w.Gloss != "" {
+		t.Fatalf("expected no gloss, got %q", w.Gloss)
+	}
+	if w.Definition != "too great to be expressed in words" {
+		t.Fatalf("definition not stored, got %q", w.Definition)
+	}
+}
+
+// TestCaptureCaseInsensitive proves "Apple" (sentence start) and "apple"
+// (mid-line) land in the SAME garden card — capture normalizes to lower+trim
+// like the lexicon, so the idempotent upsert isn't defeated by casing.
+func TestCaptureCaseInsensitive(t *testing.T) {
+	srv, _ := newTestServer(t)
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"Apple","gloss":"苹果"}`); rec.Code != http.StatusCreated {
+		t.Fatalf("capture Apple: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"  apple ","gloss":"苹果"}`); rec.Code != http.StatusCreated {
+		t.Fatalf("capture apple: code=%d body=%s", rec.Code, rec.Body)
+	}
+	rec := do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("Apple/apple should be one card, got %d", len(all))
+	}
+	if all[0].Word != "apple" {
+		t.Fatalf("word should be normalized to lowercase, got %q", all[0].Word)
+	}
+}
+
+// TestCaptureUnknownDocID rejects an unowned/stale doc_id with a clean 400
+// rather than letting it hit the foreign key and leak a raw 500.
+func TestCaptureUnknownDocID(t *testing.T) {
+	srv, _ := newTestServer(t)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"quixotic","gloss":"不切实际的","doc_id":"does-not-exist"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("unknown doc_id: want 400, got %d body=%s", rec.Code, rec.Body)
+	}
+	// A blank doc_id is treated as none, not an error.
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"limpid","gloss":"清澈的","doc_id":""}`); rec.Code != http.StatusCreated {
+		t.Fatalf("blank doc_id should be accepted as none: code=%d body=%s", rec.Code, rec.Body)
+	}
+}
+
+// TestCaptureClampsLongFields proves over-long fields are clamped (not rejected)
+// so a lookup never fails on length, and the word key stays bounded.
+func TestCaptureClampsLongFields(t *testing.T) {
+	srv, _ := newTestServer(t)
+	longWord := strings.Repeat("a", maxWordLen+50)
+	longDef := strings.Repeat("x", maxDefinitionLen+50)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"`+longWord+`","definition":"`+longDef+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if len([]rune(w.Word)) != maxWordLen {
+		t.Fatalf("word should clamp to %d runes, got %d", maxWordLen, len([]rune(w.Word)))
+	}
+	if len([]rune(w.Definition)) != maxDefinitionLen {
+		t.Fatalf("definition should clamp to %d runes, got %d", maxDefinitionLen, len([]rune(w.Definition)))
+	}
+}
+
+// TestDocLinkSurvivesDocDelete proves the ON DELETE SET NULL keeps a word in the
+// garden when its source document is removed.
+func TestDocLinkSurvivesDocDelete(t *testing.T) {
+	srv, database := newTestServer(t)
+	var docID string
+	if err := database.QueryRow(
+		`INSERT INTO documents (user_id, content_text) VALUES (?, 'hi') RETURNING id`, db.LocalUserID,
+	).Scan(&docID); err != nil {
+		t.Fatalf("seed doc: %v", err)
+	}
+	rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"ephemeral","gloss":"短暂的","doc_id":"`+docID+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if _, err := database.Exec(`DELETE FROM documents WHERE id = ?`, docID); err != nil {
+		t.Fatalf("delete doc: %v", err)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("word should survive doc deletion, got %d", len(all))
+	}
+	if all[0].DocID != nil {
+		t.Fatalf("doc_id should be nulled after doc delete, got %v", *all[0].DocID)
+	}
+}

internal/vocab/scheduler.go

@@ -0,0 +1,114 @@
+// Package vocab implements the vocabulary garden: it captures words the writer
+// looks up and schedules them for gentle spaced-repetition review. The scheduler
+// is a deliberately forgiving SM-2-lite / Leitner hybrid — no streaks to break,
+// no harsh resets beyond a single step back — because this is a confidence
+// builder, not a drill sergeant.
+package vocab
+
+import "math"
+
+// Grade is the writer's self-assessment after seeing a flashcard's answer.
+type Grade string
+
+const (
+	GradeAgain Grade = "again" // didn't recall it — show again soon
+	GradeGood  Grade = "good"  // recalled it — advance one rung
+	GradeEasy  Grade = "easy"  // knew it instantly — advance a little further
+)
+
+// ladder is the Leitner interval ladder in days for the first several successful
+// reviews: 1 → 3 → 7 → 16 → 35. Beyond the ladder, intervals grow by the card's
+// ease factor so well-known words drift far into the future.
+var ladder = []int{1, 3, 7, 16, 35}
+
+const (
+	minEase        = 1.3
+	maxEase        = 3.0  // ease ceiling — keeps "easy" from compounding growth without bound
+	startEase      = 2.5
+	easyBonus      = 1.3   // multiplier applied on top of a "good" step for "easy"
+	easeAgainDelta = -0.20 // ease nudged down on a lapse (still floored at minEase)
+	easeEasyDelta  = 0.15  // ease nudged up when a card feels easy
+
+	// maxInterval caps how far a card can drift into the future. Even a word
+	// graded "easy" many times resurfaces about once a year, so nothing silently
+	// leaves the garden forever (the whole point is to keep words in gentle
+	// rotation, not to retire them).
+	maxInterval = 365
+)
+
+// State is the spaced-repetition state of one card. It mirrors the scheduling
+// columns on vocab_words so a review is "load State → next(grade) → persist".
+type State struct {
+	Reps     int
+	Interval int // days until the next review
+	Ease     float64
+	Lapses   int
+}
+
+// next returns the card's state after a review with the given grade. It never
+// mutates the receiver. "again" steps the card back to a 1-day interval and
+// counts a lapse (but only nudges ease down, never wipes progress harshly);
+// "good" advances one rung of the ladder; "easy" advances a rung and a bit more.
+func (s State) next(grade Grade) State {
+	ease := s.Ease
+	if ease == 0 {
+		ease = startEase
+	}
+
+	switch grade {
+	case GradeAgain:
+		return State{
+			Reps:     0,
+			Interval: 1,
+			Ease:     clampEase(ease + easeAgainDelta),
+			Lapses:   s.Lapses + 1,
+		}
+	case GradeEasy:
+		ease = clampEase(ease + easeEasyDelta)
+		reps := s.Reps + 1
+		return State{
+			Reps:     reps,
+			Interval: clampInterval(int(math.Round(float64(goodInterval(reps, s.Interval, ease)) * easyBonus))),
+			Ease:     ease,
+			Lapses:   s.Lapses,
+		}
+	default: // GradeGood
+		reps := s.Reps + 1
+		return State{
+			Reps:     reps,
+			Interval: clampInterval(goodInterval(reps, s.Interval, ease)),
+			Ease:     ease,
+			Lapses:   s.Lapses,
+		}
+	}
+}
+
+// goodInterval returns the day-interval for a successful review: the explicit
+// ladder while it lasts, then geometric growth by ease once past it.
+func goodInterval(reps, prevInterval int, ease float64) int {
+	if reps >= 1 && reps <= len(ladder) {
+		return ladder[reps-1]
+	}
+	prev := prevInterval
+	if prev < ladder[len(ladder)-1] {
+		prev = ladder[len(ladder)-1]
+	}
+	return int(math.Round(float64(prev) * ease))
+}
+
+func clampEase(e float64) float64 {
+	if e < minEase {
+		return minEase
+	}
+	if e > maxEase {
+		return maxEase
+	}
+	return e
+}
+
+func clampInterval(d int) int {
+	if d > maxInterval {
+		return maxInterval
+	}
+	return d
+}

internal/vocab/scheduler_test.go

@@ -0,0 +1,88 @@
+package vocab
+
+import "testing"
+
+// TestLadderProgression walks a card up the Leitner ladder on repeated "good"
+// reviews: 1 → 3 → 7 → 16 → 35 days, then geometric growth by ease.
+func TestLadderProgression(t *testing.T) {
+	s := State{Ease: startEase}
+	want := []int{1, 3, 7, 16, 35}
+	for i, w := range want {
+		s = s.next(GradeGood)
+		if s.Interval != w {
+			t.Fatalf("rung %d: interval=%d, want %d", i, s.Interval, w)
+		}
+		if s.Reps != i+1 {
+			t.Fatalf("rung %d: reps=%d, want %d", i, s.Reps, i+1)
+		}
+	}
+	// Past the ladder it grows by ease (35 * 2.5 = 87.5 → 88).
+	s = s.next(GradeGood)
+	if s.Interval != 88 {
+		t.Fatalf("post-ladder interval=%d, want 88", s.Interval)
+	}
+}
+
+// TestAgainStepsBackGently proves a lapse resets to a 1-day interval and counts
+// a lapse, but only nudges ease down (never below the floor) — no harsh wipe.
+func TestAgainStepsBackGently(t *testing.T) {
+	s := State{Reps: 4, Interval: 35, Ease: startEase}
+	s = s.next(GradeAgain)
+	if s.Interval != 1 {
+		t.Fatalf("again interval=%d, want 1", s.Interval)
+	}
+	if s.Reps != 0 {
+		t.Fatalf("again reps=%d, want 0", s.Reps)
+	}
+	if s.Lapses != 1 {
+		t.Fatalf("again lapses=%d, want 1", s.Lapses)
+	}
+	if s.Ease != startEase+easeAgainDelta {
+		t.Fatalf("again ease=%v, want %v", s.Ease, startEase+easeAgainDelta)
+	}
+
+	// Ease never drops below the floor no matter how many lapses.
+	low := State{Ease: minEase}
+	for i := 0; i < 5; i++ {
+		low = low.next(GradeAgain)
+	}
+	if low.Ease < minEase {
+		t.Fatalf("ease fell below floor: %v", low.Ease)
+	}
+}
+
+// TestCapsBoundGrowth proves runaway "easy" grading can't push ease or the
+// interval past their ceilings, so a word always resurfaces within a year.
+func TestCapsBoundGrowth(t *testing.T) {
+	s := State{Ease: startEase}
+	for i := 0; i < 40; i++ {
+		s = s.next(GradeEasy)
+		if s.Ease > maxEase {
+			t.Fatalf("step %d: ease %v exceeded cap %v", i, s.Ease, maxEase)
+		}
+		if s.Interval > maxInterval {
+			t.Fatalf("step %d: interval %d exceeded cap %d", i, s.Interval, maxInterval)
+		}
+	}
+	// After enough "easy" reviews it should be pinned at the ceilings.
+	if s.Interval != maxInterval {
+		t.Fatalf("interval should saturate at %d, got %d", maxInterval, s.Interval)
+	}
+	if s.Ease != maxEase {
+		t.Fatalf("ease should saturate at %v, got %v", maxEase, s.Ease)
+	}
+}
+
+// TestEasyAdvancesFurther proves "easy" both bumps ease and lands a longer
+// interval than a plain "good" at the same rung.
+func TestEasyAdvancesFurther(t *testing.T) {
+	base := State{Reps: 2, Interval: 7, Ease: startEase}
+	good := base.next(GradeGood)
+	easy := base.next(GradeEasy)
+	if easy.Interval <= good.Interval {
+		t.Fatalf("easy interval %d should exceed good interval %d", easy.Interval, good.Interval)
+	}
+	if easy.Ease <= startEase {
+		t.Fatalf("easy should raise ease, got %v", easy.Ease)
+	}
+}

petal-spec.md

@@ -1,778 +0,0 @@
-# Petal — AI Writing Assistant
-## Project Specification for Claude Code
-
----
-
-## Overview
-
-Petal is a self-hosted, privacy-first writing editor for an ESL user. It replaces Grammarly with a warm, bubbly web app that combines Tiptap rich text editing, auto-save cloud storage, and periodic AI-powered grammar/ESL suggestions backed by a local vLLM inference endpoint.
-
-Single-user initially (wife's Authentik account). Deployed to `write.parodia.dev`.
-
----
-
-## Tech Stack
-
-| Layer | Choice | Why |
-|---|---|---|
-| Frontend | React + Vite | Tiptap is React-native; best extension ecosystem |
-| Editor | Tiptap v2 | ProseMirror with sane API; supports custom marks/decorations |
-| Styling | Tailwind v4 | Utility-first; pairs well with custom design tokens |
-| Backend | Go + chi | Consistent with rest of stack (PGX Comics, Veola) |
-| Database | SQLite (modernc — pure Go, no cgo) | Simple, single-binary friendly |
-| Spell check | nspell (JS, browser-side) | Zero latency, no backend call, loads hunspell dictionaries |
-| AI suggestions | vLLM HTTP endpoint | Already running; configurable model + base URL |
-| Auth | Authentik OIDC | Already running on parodia.dev |
-| Deployment | Docker, Traefik | Consistent with existing infra |
-
----
-
-## Design System
-
-**Aesthetic:** soft, warm, bubbly. The UI should feel like a cozy stationery app, not a productivity tool.
-
-### Color Palette
-```
---color-bg:           #FDF6F0   /* warm cream canvas */
---color-surface:      #FFFFFF   /* card/panel surfaces */
---color-surface-alt:  #FFF0F5   /* rose-tinted alt surface */
---color-border:       #F0E0EB   /* soft pink-grey border */
---color-text:         #3D2E39   /* warm dark plum, not harsh black */
---color-text-muted:   #9B8CA3   /* muted lavender-grey */
---color-accent:       #E8A0BF   /* soft rose — primary interactive */
---color-accent-hover: #D98AAF   /* slightly deeper on hover */
---color-mint:         #A8D8C8   /* suggestion type: grammar */
---color-peach:        #F4B8A0   /* suggestion type: phrasing */
---color-lavender:     #C5B4E8   /* suggestion type: idiom */
---color-sky:          #A8CCE8   /* suggestion type: clarity */
---color-honey:        #CE9B4F   /* suggestion type: voice — deepened amber for underline contrast on cream */
---color-success:      #8FCFA8   /* saved, accepted */
---color-shadow:       rgba(180, 130, 160, 0.12) /* warm-tinted shadow */
-```
-
-### Typography
-- **UI / Headings:** Nunito (Google Fonts) — rounded, bubbly, friendly
-- **Editor body:** Lora (Google Fonts) — warm serif, reads beautifully at paragraph length
-- **Monospace / data:** JetBrains Mono (used sparingly for word counts etc.)
-
-### Shape Language
-- Border radius: `16px` on cards, `24px` on modals, `999px` on buttons/pills, `12px` on input fields
-- Shadows: `0 4px 20px var(--color-shadow)` — soft, warm, lifted
-- Transitions: `200ms ease` across all interactive elements
-
-### Signature Element
-Suggestion decorations animate in with a gentle fade + slight upward float (translateY 4px → 0). The acceptance animation plays a tiny confetti burst (CSS only, 3–4 colored dots). The pulsing LLM checkpoint indicator is a soft rose dot that breathes (opacity 0.4 → 1 → 0.4 in 2s).
-
----
-
-## Directory Structure
-
-```
-petal/
-├── cmd/
-│   └── server/
-│       └── main.go              # Entry point; embeds /web/dist
-├── internal/
-│   ├── config/
-│   │   └── config.go            # Env var loading
-│   ├── db/
-│   │   ├── db.go                # SQLite init + migrations
-│   │   └── models.go            # Document, Suggestion, User types
-│   ├── auth/
-│   │   ├── oidc.go              # Authentik OIDC flow
-│   │   └── middleware.go        # Session auth middleware
-│   ├── docs/
-│   │   └── handlers.go          # Document CRUD handlers
-│   ├── plagiarism/
-│   │   ├── copyleaks.go         # Copyleaks API client
-│   │   └── voice.go             # Local LLM voice consistency check
-│   └── llm/
-│       ├── client.go            # LLMClient interface + factory function
-│       ├── vllm.go              # vLLM concrete implementation (OpenAI-compat)
-│       ├── ollama.go            # Ollama concrete implementation (native API)
-│       ├── checkpoint.go        # Checkpoint trigger + debounce logic
-│       └── prompts.go           # System prompts
-├── web/
-│   ├── src/
-│   │   ├── components/
-│   │   │   ├── Editor/
-│   │   │   │   ├── EditorCore.tsx        # Tiptap instance + config
-│   │   │   │   ├── SuggestionMark.tsx    # Custom Tiptap mark extension
-│   │   │   │   ├── SuggestionCard.tsx    # Hover card (suggestion + explanation)
-│   │   │   │   └── CheckpointIndicator.tsx
-│   │   │   ├── DocList/
-│   │   │   │   ├── DocList.tsx           # Document browser sidebar
-│   │   │   │   └── DocListItem.tsx
-│   │   │   ├── Toolbar/
-│   │   │   │   └── Toolbar.tsx           # Formatting toolbar
-│   │   │   └── StatusBar/
-│   │   │       └── StatusBar.tsx         # Word count, save status, checkpoint dot
-│   │   ├── hooks/
-│   │   │   ├── useAutoSave.ts            # Debounced save (1.5s)
-│   │   │   └── useCheckpoint.ts          # LLM checkpoint trigger (4s pause)
-│   │   ├── api/
-│   │   │   └── client.ts                 # Fetch wrappers for all API routes
-│   │   ├── App.tsx
-│   │   └── main.tsx
-│   ├── index.html
-│   ├── package.json
-│   ├── vite.config.ts
-│   └── tailwind.config.ts
-├── Dockerfile
-├── docker-compose.yml
-├── .env.example
-└── README.md
-```
-
----
-
-## Database Schema
-
-```sql
-CREATE TABLE users (
-    id          TEXT PRIMARY KEY,   -- Authentik subject claim
-    email       TEXT NOT NULL,
-    display_name TEXT,
-    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE documents (
-    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
-    user_id      TEXT NOT NULL REFERENCES users(id),
-    title        TEXT NOT NULL DEFAULT 'Untitled',
-    content      TEXT NOT NULL DEFAULT '{}',  -- Tiptap JSON
-    content_text TEXT NOT NULL DEFAULT '',    -- Plain text for LLM
-    word_count   INTEGER NOT NULL DEFAULT 0,
-    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at   DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE suggestions (
-    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
-    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-    from_pos     INTEGER NOT NULL,
-    to_pos       INTEGER NOT NULL,
-    original     TEXT NOT NULL,
-    replacement  TEXT NOT NULL,
-    explanation  TEXT NOT NULL,
-    type         TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice')),
-    status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')),
-    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE plagiarism_reports (
-    id              TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
-    doc_id          TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-    backend         TEXT NOT NULL DEFAULT 'copyleaks',
-    similarity_pct  REAL,                -- overall similarity score 0–100
-    status          TEXT NOT NULL DEFAULT 'pending'
-                    CHECK(status IN ('pending','complete','error')),
-    result_json     TEXT,                -- full Copyleaks response, stored raw
-    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_plagiarism_doc_id ON plagiarism_reports(doc_id);
-CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
-```
-
----
-
-## API Routes
-
-All routes under `/api/`. Auth middleware validates session cookie on all except `/api/auth/*`.
-
-```
-GET    /api/me                    → current user info
-POST   /api/auth/login            → redirect to Authentik
-GET    /api/auth/callback         → OIDC callback, set session cookie
-POST   /api/auth/logout           → clear session
-
-GET    /api/docs                  → list user's documents (id, title, word_count, updated_at)
-POST   /api/docs                  → create new document → returns full document
-GET    /api/docs/:id              → get document + pending suggestions
-PUT    /api/docs/:id              → update document content (auto-save endpoint)
-DELETE /api/docs/:id              → delete document
-
-POST   /api/docs/:id/check        → run grammar checkpoint (returns new suggestions)
-POST   /api/docs/:id/voice        → run voice-consistency pass (returns voice suggestions)
-
-POST   /api/docs/:id/plagiarism        → trigger Copyleaks check (returns report id)
-GET    /api/docs/:id/plagiarism/latest → get latest report for document
-PUT    /api/suggestions/:id       → update suggestion status (accepted/rejected)
-DELETE /api/docs/:id/suggestions  → clear all suggestions for a doc
-POST   /api/suggestions/:id/chat  → Ask Petal conversational follow-up (SSE stream)
-```
-
----
-
-## Plagiarism Detection
-
-### Architecture: Two Tiers
-
-**Tier 1 — Voice Consistency Check (local, LLM, separate pass)**
-The LLM reviews the document for passages that feel tonally inconsistent with the rest of her writing — formulaic phrasing, suspiciously polished sentences, register shifts. Surfaces these as a new suggestion type (`type: "voice"`) with a warm honey-amber decoration (`--color-honey`, distinct from the lavender used for `idiom`; deepened from a pale yellow so the underline stays legible against the cream canvas). This is not plagiarism detection; it's a writing consistency tool. It runs locally with no privacy cost and is useful for ESL writers who may have paraphrased too closely from a source.
-
-**This is a distinct pass from the grammar checkpoint — do not bundle them.** Voice-consistency detection is inherently whole-document (it compares a passage against the established voice *everywhere else*), so it needs the full document as context and the full window is available (see Context Window Management). That makes it too expensive to fire on the fast 4s checkpoint cadence. Run it instead either:
-- on a slow cadence (every 30–60s of idle), separate from the grammar checkpoint debounce, or
-- on an explicit "Check my voice" action in the toolbar.
-
-Send the full `content_text` (no trailing-window truncation — the model window is 256K, the document will fit). Use a higher `max_tokens` than the grammar checkpoint since it may flag several passages. The grammar checkpoint stays fast and local-context; voice runs slow and whole-document. Each uses the context size and cadence appropriate to its job.
-
-**Tier 2 — Academic Plagiarism Check (Copyleaks, opt-in, manual)**
-A dedicated "Check for plagiarism" button in the editor toolbar. On first use, shows a consent modal explaining that document text will be sent to Copyleaks servers for comparison against web and academic databases. User must explicitly confirm. After confirmation, preference is saved per-user and the modal does not reappear.
-
-Copyleaks checks against web content and academic paper databases — the same corpus type schools use with Turnitin. Not identical to Turnitin, but meaningful for pre-submission review.
-
-### Copyleaks Integration
-
-**Env vars:**
-```
-COPYLEAKS_ENABLED=false          # off by default
-COPYLEAKS_API_KEY=
-COPYLEAKS_EMAIL=                 # account email, required by their API
-```
-
-**API flow:**
-Copyleaks uses an async model — you submit text, get a scan ID, then poll or receive webhook callback when complete.
-
-```
-1. POST https://api.copyleaks.com/v3/education/submit/url/{scanId}
-   (or text submission endpoint)
-   → 201 Accepted, scanId stored in plagiarism_reports
-
-2. Copyleaks calls webhook: POST /api/webhooks/copyleaks
-   → Go handler updates plagiarism_reports with result_json + similarity_pct + status=complete
-
-3. Frontend polls GET /api/docs/:id/plagiarism/latest every 5s
-   while status=pending, renders results when complete
-```
-
-**Webhook endpoint:** `POST /api/webhooks/copyleaks` — must be publicly reachable (it is, via write.parodia.dev). No auth middleware on this route; validate using Copyleaks HMAC signature header instead.
-
-**Results display (`PlagiarismPanel` component):**
-- Slide-in right panel (same pattern as AskPetal expanded card but full height)
-- Top: large similarity percentage with color coding (green <15%, amber 15–30%, red >30%)
-- Below: list of matched sources with URL, matched percentage, and matched passage
-- Matched passages highlighted in the editor with a new red-tinted decoration type
-- "Last checked: X minutes ago" + "Re-check" button
-- Privacy reminder at panel footer: "Text was sent to Copyleaks for this check"
-
-### Voice Consistency Prompt Addition
-
-Add to the checkpoint system prompt (after existing ESL instructions):
-
-```
-Also identify any passages (2+ sentences) that feel tonally inconsistent with 
-the surrounding writing — unusually formal, unusually polished, or phrased in 
-a way that differs from the writer's established voice elsewhere in the document. 
-Flag these with type "voice". Do not flag the first paragraph (no baseline yet).
-```
-
-Return format addition:
-```json
-{ "original": "...", "replacement": null, "explanation": "This passage sounds more formal than the rest of your writing — worth reviewing.", "type": "voice" }
-```
-
-`replacement` is `null` for voice flags — there is no correction, just awareness. The frontend SuggestionCard handles `null` replacement by hiding the replacement row and showing only the explanation + Dismiss.
-
----
-
-## LLM Integration
-
-### Client Config (env vars)
-```
-LLM_BACKEND=vllm           # vllm | ollama — default: vllm
-LLM_ENDPOINT=http://192.168.x.x:8000   # vLLM default port 8000, Ollama default 11434
-LLM_MODEL=gemma4           # Checkpoint model — small, fast. Treat as config, never hardcode.
-LLM_CHAT_MODEL=gemma4      # Ask Petal model — can be much larger. Defaults to LLM_MODEL if unset.
-LLM_TIMEOUT=30s
-```
-
-**Model sizing guidance:**
-Checkpoint runs every 4 seconds while the user types — latency is UX. Keep `LLM_MODEL` at 4B–7B. Gemma4 is a solid default.
-
-Ask Petal is a deliberate conversational turn with small input context (~2,000 tokens) and short output (2–4 sentences). Since the user asks questions in Mandarin, `LLM_CHAT_MODEL` should be a Chinese-native model — **Qwen3.5 9B** is the right pick. Native Mandarin capability rather than learned multilingual coverage makes a real difference for grammar explanation quality. With 64GB VRAM you have plenty of headroom for a larger Qwen3 variant.
-
-If `LLM_CHAT_MODEL` is unset, fall back to `LLM_MODEL`. Single-model setups work fine.
-
-### Backend Abstraction
-
-Define a `LLMClient` interface in `internal/llm/client.go`. All handler code calls the interface only — never a concrete type directly.
-
-```go
-// internal/llm/client.go
-
-type Message struct {
-    Role    string `json:"role"`
-    Content string `json:"content"`
-}
-
-type CompletionRequest struct {
-    Messages          []Message
-    MaxTokens         int
-    Temperature       float64
-    RepetitionPenalty float64
-    TopP              float64
-    Stop              []string
-    Stream            bool
-}
-
-type LLMClient interface {
-    // Complete returns the full response in one shot (used for checkpoint JSON)
-    Complete(ctx context.Context, req CompletionRequest) (string, error)
-    // Stream returns a channel of text chunks (used for Ask Petal SSE)
-    Stream(ctx context.Context, req CompletionRequest) (<-chan string, error)
-}
-
-// Factory — selects backend from config
-func NewLLMClient(cfg *config.Config) LLMClient {
-    // LLM_CHAT_MODEL falls back to LLM_MODEL if unset
-    chatModel := cfg.LLMChatModel
-    if chatModel == "" {
-        chatModel = cfg.LLMModel
-    }
-    switch cfg.LLMBackend {
-    case "ollama":
-        return &OllamaClient{
-            endpoint:       cfg.LLMEndpoint,
-            checkpointModel: cfg.LLMModel,
-            chatModel:       chatModel,
-            timeout:         cfg.LLMTimeout,
-        }
-    default: // "vllm"
-        return &VLLMClient{
-            endpoint:        cfg.LLMEndpoint,
-            checkpointModel: cfg.LLMModel,
-            chatModel:       chatModel,
-            timeout:         cfg.LLMTimeout,
-        }
-    }
-}
-```
-
-**`internal/llm/vllm.go`** — OpenAI-compatible endpoint:
-```
-POST {endpoint}/v1/chat/completions
-Content-Type: application/json
-
-{
-  "model": "{model}",
-  "messages": [...],
-  "max_tokens": {MaxTokens},
-  "temperature": {Temperature},
-  "repetition_penalty": {RepetitionPenalty},
-  "top_p": {TopP},
-  "stop": [...],
-  "stream": {Stream}
-}
-```
-Streaming: SSE, parse `data:` lines, extract `choices[0].delta.content`, stop on `data: [DONE]`.
-
-**`internal/llm/ollama.go`** — Ollama native API:
-```
-POST {endpoint}/api/chat
-Content-Type: application/json
-
-{
-  "model": "{model}",
-  "messages": [...],
-  "stream": {Stream},
-  "options": {
-    "num_predict": {MaxTokens},
-    "temperature": {Temperature},
-    "repeat_penalty": {RepetitionPenalty},
-    "top_p": {TopP},
-    "stop": [...]
-  }
-}
-```
-Streaming: newline-delimited JSON objects, extract `message.content`, stop when `done: true`.
-
-**Parameter mapping cheatsheet:**
-
-| CompletionRequest field | vLLM key | Ollama key |
-|---|---|---|
-| `MaxTokens` | `max_tokens` | `options.num_predict` |
-| `Temperature` | `temperature` | `options.temperature` |
-| `RepetitionPenalty` | `repetition_penalty` | `options.repeat_penalty` |
-| `TopP` | `top_p` | `options.top_p` |
-| `Stop` | `stop` | `options.stop` |
-
-Both backends live behind the same interface — checkpoint.go and the Ask Petal handler call `client.Complete()` and `client.Stream()` with no awareness of which backend is active.
-
-### Checkpoint Logic
-- **Trigger:** user stops typing for 4 seconds (debounced in frontend via `useCheckpoint.ts`)
-- **Rate limit:** backend enforces minimum 30s between checks per document
-- **Payload:** full `content_text` of the document (not just the changed section — context matters for ESL)
-- **Max tokens:** 1024 (suggestions are structured JSON, should be compact)
-- **Visual feedback:** pulsing rose dot in StatusBar while check in flight
-
-### System Prompt
-```
-You are a warm, encouraging writing assistant helping someone who speaks English as a second language. 
-Analyze the text below and identify up to 5 issues: grammar errors, unnatural phrasing, 
-incorrect idiom usage, or unclear sentences that are common ESL patterns.
-
-Be specific, friendly, and explain WHY each suggestion improves the writing.
-
-Respond ONLY with valid JSON. No preamble, no markdown fences. Format:
-{
-  "suggestions": [
-    {
-      "original": "exact text from the document that needs fixing",
-      "replacement": "corrected version",
-      "explanation": "friendly one-sentence explanation",
-      "type": "grammar|phrasing|idiom|clarity"
-    }
-  ]
-}
-
-If the writing looks good, return: {"suggestions": []}
-```
-
-### Ask Petal: Conversational Follow-Up
-
-When a user doesn't understand a suggestion, they tap **"Ask Petal ✨"** inside the suggestion card. This opens a mini chat panel anchored to the suggestion card (expands downward, max-height 320px, scrollable). The conversation is maintained in React state — not persisted to the DB. Closing the card clears the history.
-
-**API route:** `POST /api/suggestions/:id/chat`
-
-**Request payload:**
-```json
-{
-  "messages": [
-    { "role": "user", "content": "why is this wrong?" }
-  ]
-}
-```
-
-**Server behavior:** The Go handler fetches the suggestion record (original, replacement, explanation, type) and the surrounding paragraph from the parent document's `content_text`. It injects these as system context, then appends the user's message history and streams the response back via SSE.
-
-**Response:** SSE stream, `data:` events containing response text chunks. Frontend accumulates into assistant message bubble.
-
-**Ask Petal System Prompt:**
-```
-You are Petal, a warm and patient English writing tutor helping someone who is learning English 
-as a second language. You are currently discussing a specific writing suggestion.
-
-Suggestion context:
-- Original text: "{{original}}"
-- Suggested replacement: "{{replacement}}"  
-- Issue type: {{type}}
-- Initial explanation: "{{explanation}}"
-- Surrounding paragraph: "{{paragraph}}"
-
-The user wants to understand this suggestion better. Detect the language of the user's message 
-and respond in that same language. If they write in Mandarin Chinese, respond entirely in 
-Mandarin. If they write in English, respond in English. Never mix languages in a single response.
-
-Explain clearly and kindly. Use simple language appropriate to the user's message. Give examples 
-when helpful. If they ask "why" (or "为什么"), explain the grammar rule or idiom behind it. 
-If they suggest an alternative phrasing, evaluate it honestly.
-
-Keep responses concise (2-4 sentences). This is a chat, not an essay. Be encouraging — 
-learning a language is hard and they're doing great.
-```
-
-**AskPetal Component (`web/src/components/Editor/AskPetal.tsx`):**
-- Renders inside the expanded SuggestionCard
-- Input field at bottom, message bubbles above (Petal messages: rose-tinted left-aligned; user messages: right-aligned lavender)
-- "Ask Petal ✨" trigger button is a small pill link below the suggestion explanation
-- Petal's first message pre-populates with the suggestion's explanation so context is immediate
-- Streaming response renders token-by-token into the latest assistant bubble
-- No conversation persistence — state lives in the SuggestionCard component
-
-### LLM Sampling Parameters & Stability
-
-vLLM is stateless per request. There are no server-side sessions — conversation history for Ask Petal is managed entirely at the app layer (client sends full message array each request). This is correct behavior; do not attempt to implement vLLM-side session persistence.
-
-**Checkpoint requests (structured JSON output):**
-```json
-{
-  "model": "${LLM_MODEL}",
-  "messages": [...],
-  "max_tokens": 1024,
-  "temperature": 0.3,
-  "repetition_penalty": 1.15,
-  "top_p": 0.9,
-  "stop": ["```", "\n\n\n\n"]
-}
-```
-
-**Ask Petal chat requests (conversational):**
-```json
-{
-  "model": "${LLM_MODEL}",
-  "messages": [...],
-  "max_tokens": 512,
-  "temperature": 0.7,
-  "repetition_penalty": 1.15,
-  "top_p": 0.92,
-  "stop": ["\n\n\n"]
-}
-```
-
-**Why these values:**
-- `temperature: 0.3` for checkpoint — low enough to produce structured JSON reliably, but not zero. Zero temperature means greedy decoding, which is paradoxically *more* prone to repetition loops in smaller models, not less.
-- `temperature: 0.7` for chat — conversational range; allows natural variation without going incoherent.
-- `repetition_penalty: 1.15` on both — primary defense against repetition breakdown. Applies a multiplicative penalty to already-seen tokens. 1.1–1.2 is the safe range; above 1.3 starts degrading output quality.
-- `stop` sequences — catches runaway generation before it fills the output buffer. Triple newline is a reliable signal the model has looped past the end of a coherent response.
-- `max_tokens: 512` for chat — enforces conciseness and prevents the model from rambling into a degraded state mid-response.
-
-### Context Window Management
-
-The model window is **not** the binding constraint here — Qwen 3.5 ships a 256K context window, and on a 64GB dual-GPU setup there is ample KV-cache headroom. The truncation caps below exist to protect **checkpoint latency** (prefill time scales with input length, and the grammar checkpoint must feel responsive), not memory. Documents will almost always fit uncut; the cap only fires on unusually long ones.
-
-**Grammar checkpoint** (fast, latency-sensitive — keep input modest):
-
-| Component | Token Budget |
-|---|---|
-| System prompt | ~300 |
-| Document text | ~10,000 (hard cap; trailing window) |
-| Response (JSON) | ~1,024 |
-| Buffer | rest of window (ample) |
-
-**Voice-consistency pass** (slow cadence — send the whole document, no trailing-window truncation; see Plagiarism Detection → Tier 1).
-
-**Ask Petal chat:**
-
-| Component | Token Budget |
-|---|---|
-| System prompt + suggestion context | ~600 |
-| Conversation history (rolling) | ~3,000 |
-| Latest user message | ~200 |
-| Response | ~512 |
-| Buffer | ~3,880 |
-
-**Truncation logic (implement in `internal/llm/client.go`):**
-
-```go
-const maxDocChars     = 40000 // ~10000 tokens at ~4 chars/token — grammar checkpoint only
-const maxHistoryMsgs  = 10    // 5 turns; drop oldest pairs first
-
-// Document truncation (grammar checkpoint) — keep the recent end (user is actively writing there).
-// The cap is a latency guard, not a window limit; the model window (256K) is far larger.
-// The voice-consistency pass does NOT apply this truncation — it sends the full content_text.
-if len(contentText) > maxDocChars {
-    contentText = contentText[len(contentText)-maxDocChars:]
-}
-
-// Conversation history truncation — drop oldest messages first
-if len(messages) > maxHistoryMsgs {
-    messages = messages[len(messages)-maxHistoryMsgs:]
-}
-```
-
-Always log a `WARN` when truncation fires so it's visible in production. Never fail silently.
-
-The Go handler receives the LLM suggestions (which reference `original` text strings) and records the plain-text offsets via `strings.Index(content_text, original)` as `from_pos` / `to_pos`. **These stored offsets are for server-side use only** (paragraph extraction for Ask Petal context) and are *not* ProseMirror positions — see Note #6. The frontend anchors decorations by searching the live document for the `original` string in ProseMirror coordinates at render time, not by trusting a numeric position. This is the single most important correctness detail in the suggestion pipeline; get it wrong and every multi-block document mis-renders.
-
----
-
-## Frontend: Tiptap Configuration
-
-### Extensions to enable
-```typescript
-StarterKit,              // Bold, italic, headings, lists, paragraphs
-Underline,
-TextAlign,
-Placeholder.configure({ placeholder: 'Start writing...' }),
-SpellChecker,            // Custom extension wrapping nspell
-SuggestionMark,          // Custom extension for AI suggestion decorations
-CharacterCount,          // For word count in StatusBar
-```
-
-### SuggestionMark Extension
-Custom Tiptap mark that:
-- Accepts `{ suggestionId, type }` attributes
-- **Anchors by string match, not stored position** — when suggestions arrive, walk the live ProseMirror document, find the `original` text in PM coordinates, and apply the mark over that range. Do not use the server's `from_pos`/`to_pos` (those are plain-text offsets, not PM positions — see Note #6). If `original` isn't found in the current document (already edited), skip that suggestion silently.
-- Renders as a colored underline (color varies by type using CSS vars)
-- On hover, shows `<SuggestionCard>` positioned absolutely above the text
-- SuggestionCard shows: original → replacement, explanation, Accept button, Dismiss button
-- Accept → calls `PUT /api/suggestions/:id` with `status: accepted`, applies replacement via Tiptap command
-- Dismiss → calls `PUT /api/suggestions/:id` with `status: rejected`, removes mark
-
-### useAutoSave Hook
-```typescript
-// Debounce 1500ms after last content change
-// Calls PUT /api/docs/:id with { content, content_text, word_count }
-// StatusBar shows: "Saving..." → "Saved just now" → fades to nothing after 3s
-```
-
-### useCheckpoint Hook
-```typescript
-// Debounce 4000ms after last content change
-// Fires POST /api/docs/:id/check
-// On response: dispatch suggestion decorations to Tiptap editor
-// Sets checkpointActive state → StatusBar indicator
-```
-
----
-
-## Layout
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  [🌸 Petal]    [New Doc]                    [User Avatar]   │  ← Header (48px)
-├──────────────┬──────────────────────────────────────────────┤
-│              │                                              │
-│  Doc List    │         Editor Canvas                        │
-│  (260px)     │         (centered, max-width 720px)          │
-│              │                                              │
-│  [Doc 1]     │    ┌─────────────────────────────┐          │
-│  [Doc 2]  ←  │    │  [B] [I] [U] [H1] [H2] [≡] │          │  ← Toolbar
-│  [Doc 3]     │    └─────────────────────────────┘          │
-│              │                                              │
-│  + New       │    Title (editable, large Nunito)            │
-│              │                                              │
-│              │    Body text in Lora...                      │
-│              │    ~~~~~~ suggestion underline ~~~~~~         │
-│              │                                              │
-│              │                                              │
-├──────────────┴──────────────────────────────────────────────┤
-│  342 words   ·   ● Checking...   ·   Saved just now         │  ← StatusBar (36px)
-└─────────────────────────────────────────────────────────────┘
-```
-
-Distraction-free mode: clicking into the editor collapses the doc list sidebar (slides left), expands editor canvas full width. Click outside canvas or press Escape to restore.
-
----
-
-## Environment Config
-
-```bash
-# .env.example
-
-# Server
-PORT=8080
-BASE_URL=https://write.parodia.dev
-SESSION_SECRET=change-me-to-random-64-char-string
-
-# Database
-DATABASE_PATH=/data/petal.db
-
-# Authentik OIDC
-AUTHENTIK_URL=https://auth.parodia.dev
-AUTHENTIK_CLIENT_ID=petal
-AUTHENTIK_CLIENT_SECRET=
-
-# LLM
-LLM_BACKEND=vllm               # vllm | ollama
-LLM_ENDPOINT=http://192.168.x.x:8000
-LLM_MODEL=gemma4               # Checkpoint: small and fast (4B–7B)
-LLM_CHAT_MODEL=qwen3.5:9b     # Ask Petal: Qwen3.5 9B recommended for native Mandarin support
-LLM_TIMEOUT=30s
-```
-
----
-
-## Dockerfile
-
-```dockerfile
-# Stage 1: Build frontend
-FROM node:22-alpine AS frontend
-WORKDIR /app/web
-COPY web/package*.json ./
-RUN npm ci
-COPY web/ ./
-RUN npm run build
-
-# Stage 2: Build Go binary
-FROM golang:1.23-alpine AS backend
-WORKDIR /app
-COPY go.* ./
-RUN go mod download
-COPY . .
-COPY --from=frontend /app/web/dist ./web/dist
-RUN CGO_ENABLED=0 go build -o petal ./cmd/server
-
-# Stage 3: Runtime
-FROM alpine:3.20
-RUN apk add --no-cache ca-certificates tzdata
-WORKDIR /app
-COPY --from=backend /app/petal .
-VOLUME ["/data"]
-EXPOSE 8080
-CMD ["./petal"]
-```
-
----
-
-## docker-compose.yml
-
-```yaml
-services:
-  petal:
-    image: petal:latest
-    restart: unless-stopped
-    volumes:
-      - petal_data:/data
-    env_file: .env
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.petal.rule=Host(`write.parodia.dev`)"
-      - "traefik.http.routers.petal.entrypoints=web-secure"
-      - "traefik.http.routers.petal.tls.certresolver=default"
-      - "traefik.http.services.petal.loadbalancer.server.port=8080"
-    networks:
-      - traefik
-
-volumes:
-  petal_data:
-
-networks:
-  traefik:
-    external: true
-```
-
----
-
-## v1 Scope (Ship This)
-
-- [x] Tiptap rich text editor (bold, italic, underline, headings H1/H2, ordered/unordered lists)
-- [x] Document list sidebar (create, rename, delete)
-- [x] Auto-save to SQLite (1.5s debounce)
-- [x] LLM checkpoint every 4s idle → inline suggestion decorations
-- [x] Suggestion hover card (replacement + explanation + accept/dismiss)
-- [x] nspell browser-side spell check (English dictionary)
-- [x] Word count + save status + checkpoint indicator in StatusBar
-- [x] Authentik OIDC auth
-- [x] Plagiarism check (two-tier: local voice consistency + opt-in Copyleaks academic check)
-- [x] Ask Petal conversational follow-up chat on any suggestion
-- [x] Distraction-free mode
-- [x] Soft/bubbly pastel design system
-- [x] Single Docker binary deployment to write.parodia.dev
-
-## Out of Scope for v1
-
-- Export to DOCX / PDF (v1.1)
-- Mobile layout (desktop first)
-- Real-time collaboration
-- Version history / change tracking
-- Multiple language support (English first)
-- Offline mode
-
----
-
-## Notes for Claude Code
-
-1. **Model names are always config values** — `LLM_MODEL` drives checkpoint, `LLM_CHAT_MODEL` drives Ask Petal. Both read from env vars. Never hardcode either. If `LLM_CHAT_MODEL` is unset, fall back to `LLM_MODEL` — handle this in the factory, not in individual handlers.
-2. **modernc sqlite** (`modernc.org/sqlite`) — pure Go, no cgo, no build friction.
-3. **Tiptap JSON format** is stored verbatim in `documents.content`. `content_text` is the plain text extracted for the LLM — keep these in sync on every save.
-4. **nspell dictionaries** — load `en-US` dictionary files from CDN or vendor them into `web/public/dictionaries/`. Don't shell out to hunspell binary.
-5. **Go embeds frontend** — use `//go:embed web/dist` in `cmd/server/main.go`. Single binary deployment.
-6. **Suggestion anchoring — resolve by string, not by stored position.** The `original` text string is the source of truth for where a suggestion belongs, **not** a stored numeric position. Two reasons:
-   - **Coordinate mismatch:** `strings.Index(contentText, original)` returns a *plain-text* character offset. Tiptap/ProseMirror positions are **not** plain-text offsets — every node boundary (paragraph, heading, list item) consumes position units, so a plaintext offset of N does not equal ProseMirror position N. Handing a plaintext offset to a Tiptap decoration places it in the wrong spot, and the error grows with each block in the document.
-   - **Staleness:** the user keeps typing (auto-save every 1.5s) after a checkpoint fires. Any position captured at checkpoint time is stale by the time the suggestion is stored and rendered.
-
-   **Therefore:** the frontend resolves each suggestion at *render time* by searching the live ProseMirror document for the `original` string (in PM coordinates) and applying the decoration there. The Go handler still runs `strings.Index(contentText, original)` and stores `from_pos`/`to_pos`, but these are **plain-text offsets for server-side use only** (e.g. extracting the surrounding paragraph for Ask Petal context — see Note #10), never shipped to the client as ProseMirror positions. If `original` appears multiple times, take the first occurrence; if not found at all, discard the suggestion rather than erroring. On the client, if `original` is no longer present in the live document (the user already edited that text), silently drop the suggestion — it's obsolete.
-7. **Session management** — use `gorilla/sessions` with a cookie store. Session key is `petal_session`. Store `user_id` in session after OIDC callback.
-8. **Authentik app** — needs to be created in Authentik with redirect URI `https://write.parodia.dev/api/auth/callback` and the OIDC client credentials added to `.env`.
-9. **Ask Petal SSE streaming** — use `text/event-stream` response in Go, flush after each token chunk. Frontend uses `fetch` with `ReadableStream` (not `EventSource` — needs POST) to accumulate tokens into the assistant bubble in real time. Don't buffer the full response.
-10. **Ask Petal context injection** — the Go handler for `/api/suggestions/:id/chat` fetches the suggestion + parent document in one query, extracts the paragraph containing `from_pos` from `content_text`, and injects all of it into the system prompt before the user messages. Never trust the client to send this context — always load it server-side.
-11. **LLM backend abstraction** — `NewLLMClient` is the only place that references `LLM_BACKEND`. Every other package receives an `LLMClient` interface value. `checkpoint.go` and the Ask Petal handler must import only the interface, not either concrete type. This keeps adding a third backend (e.g. LM Studio) to a single new file in the future.
-12. **Ollama streaming format differs from vLLM** — Ollama streams newline-delimited JSON objects (`{"message":{"content":"..."},"done":false}`), not SSE `data:` lines. The `OllamaClient.Stream()` method must handle this format; do not reuse the vLLM SSE parser for Ollama.
-13. **Copyleaks async flow** — submission returns immediately with a scan ID. Results arrive via webhook, not the submission response. Store the scan ID in `plagiarism_reports` immediately on submission, update the row when the webhook fires. Frontend polls `/api/docs/:id/plagiarism/latest` every 5s while `status=pending` — don't try to make this synchronous.
-14. **Copyleaks webhook HMAC** — validate the `X-Copyleaks-Signature` header on every webhook call. Reject without processing if invalid. Never skip this in production.
-15. **`replacement: null` in voice suggestions** — the SuggestionCard must check for null replacement and conditionally render. Don't assume replacement is always a string.
-17. **CJK font fallback in Ask Petal chat** — Nunito has no CJK coverage. The chat bubble `font-family` must include system CJK fallbacks: `'Nunito', 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', sans-serif`. Apply this specifically to the AskPetal message bubbles, not the editor body.
-18. **Mandarin detection is the model's job** — do not attempt language detection in Go or the frontend. The prompt instructs the model to detect and match. This works fine with Gemma4 which has solid Mandarin capability. If a future model swap degrades Mandarin quality, that's a prompt/model problem, not an architecture problem.

scripts/build_gloss.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Build the embedded English->Chinese gloss dataset from ECDICT.
+
+Petal shows an instant Chinese gloss when the writer (an English-as-a-second-
+language user whose first language is Mandarin) hovers or right-clicks a word.
+The gloss is served offline from a small map compiled into the Go binary, the
+same way the English definitions/synonyms are (see internal/lexicon).
+
+Source: ECDICT (https://github.com/skywind3000/ECDICT), MIT-licensed. We keep
+only common single words that carry a Chinese translation, trim each gloss to a
+couple of senses, and drop the noisy "[网络]" (internet-slang) lines — the result
+gzips to a few MB, in line with the other lexicon assets.
+
+Usage:
+    curl -sL https://raw.githubusercontent.com/skywind3000/ECDICT/master/ecdict.csv -o ecdict.csv
+    python3 scripts/build_gloss.py ecdict.csv internal/lexicon/data/gloss.json.gz
+"""
+import csv
+import gzip
+import json
+import re
+import sys
+
+# Frequency gate: keep a word only if ECDICT ranks it in the BNC or COCA
+# frequency lists (frq/bnc > 0). That bounds the asset to the words an ESL
+# writer actually meets, dropping the long tail of archaic/technical headwords.
+# Words below this rank but present nowhere in the frequency lists are skipped.
+MAX_RANK = 50000
+
+# A gloss is at most this many sense-lines and characters, so the hover bubble
+# stays a glance, not a wall of text.
+MAX_SENSES = 3
+MAX_CHARS = 80
+
+# Single English word: letters, with internal apostrophe/hyphen (so "don't",
+# "well-being" survive but multi-word phrases and codes are dropped).
+WORD_RE = re.compile(r"^[a-z][a-z'\-]*[a-z]$|^[a-z]$")
+
+# Tag lines we drop from a translation: "[网络]" is crowd-sourced internet slang,
+# "[俚]" slang, "[古]" archaic — none help an ESL writer pick everyday meaning.
+DROP_TAG_RE = re.compile(r"^\[(网络|俚|古|罕|废)\]")
+
+
+def clean_gloss(translation: str) -> str:
+    """Trim an ECDICT translation to a compact, glanceable Chinese gloss."""
+    # ECDICT separates senses with a literal backslash-n; normalize to real
+    # newlines (and tolerate genuine newlines) before splitting.
+    translation = translation.replace("\\n", "\n")
+    senses = []
+    for line in translation.split("\n"):
+        line = line.strip()
+        if not line or DROP_TAG_RE.match(line):
+            continue
+        senses.append(line)
+        if len(senses) >= MAX_SENSES:
+            break
+    gloss = "；".join(senses)
+    if len(gloss) > MAX_CHARS:
+        gloss = gloss[:MAX_CHARS].rstrip("；，;, ") + "…"
+    return gloss
+
+
+def rank(row: dict) -> int:
+    """Best (lowest, non-zero) frequency rank across COCA and BNC."""
+    ranks = []
+    for key in ("frq", "bnc"):
+        try:
+            v = int(row.get(key) or 0)
+        except ValueError:
+            v = 0
+        if v > 0:
+            ranks.append(v)
+    return min(ranks) if ranks else 0
+
+
+def main(src: str, dst: str) -> None:
+    out: dict[str, str] = {}
+    kept_rank: dict[str, int] = {}
+    with open(src, newline="", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            word = (row.get("word") or "").strip().lower()
+            translation = (row.get("translation") or "").strip()
+            if not word or not translation or not WORD_RE.match(word):
+                continue
+            r = rank(row)
+            if r == 0 or r > MAX_RANK:
+                continue
+            gloss = clean_gloss(translation)
+            if not gloss:
+                continue
+            # On a duplicate headword keep the more frequent (lower-rank) entry.
+            if word in kept_rank and kept_rank[word] <= r:
+                continue
+            out[word] = gloss
+            kept_rank[word] = r
+
+    payload = json.dumps(out, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    with gzip.open(dst, "wb", compresslevel=9) as gz:
+        gz.write(payload)
+    print(f"{len(out)} words -> {dst} ({len(payload)} bytes json)")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        sys.exit("usage: build_gloss.py <ecdict.csv> <out.json.gz>")
+    main(sys.argv[1], sys.argv[2])

scripts/build_phonetic.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Build the embedded English-phonetic dataset.
+
+Petal's writer is a native Mandarin speaker learning English, so the useful
+pronunciation aid is *how to say the English word* — shown in the word popover
+beside the 🔊 read-aloud button. (Pinyin would annotate Chinese she already
+reads fluently, so it isn't built.) The phonetic spelling comes from the same
+ECDICT source as the Chinese gloss, which already carries a `phonetic` column.
+
+Two modes:
+
+  # Full build from ECDICT (same CSV used by build_gloss.py):
+  curl -sL https://raw.githubusercontent.com/skywind3000/ECDICT/master/ecdict.csv -o ecdict.csv
+  python3 scripts/build_phonetic.py ecdict.csv internal/lexicon/data/phonetic.json.gz
+
+  # Write just the built-in common-word seed (no CSV needed — what ships in-repo
+  # so the feature works out of the box until a full build is run):
+  python3 scripts/build_phonetic.py --seed internal/lexicon/data/phonetic.json.gz
+"""
+import csv
+import gzip
+import json
+import re
+import sys
+
+# Same frequency gate as the gloss build, so coverage matches the words an ESL
+# writer actually meets and the asset stays small.
+MAX_RANK = 50000
+
+# Single English word (letters with internal apostrophe/hyphen).
+WORD_RE = re.compile(r"^[a-z][a-z'\-]*[a-z]$|^[a-z]$")
+
+# A small, hand-checked seed of common words → IPA. This ships in the repo so the
+# phonetic line is live immediately; a full ECDICT build overwrites it with broad
+# coverage. Kept deliberately short and correct rather than large and shaky.
+SEED = {
+    "hello": "həˈloʊ", "world": "wɜːrld", "people": "ˈpiːpl", "water": "ˈwɔːtər",
+    "river": "ˈrɪvər", "house": "haʊs", "school": "skuːl", "friend": "frɛnd",
+    "family": "ˈfæməli", "mother": "ˈmʌðər", "father": "ˈfɑːðər", "woman": "ˈwʊmən",
+    "language": "ˈlæŋɡwɪdʒ", "english": "ˈɪŋɡlɪʃ", "write": "raɪt", "writing": "ˈraɪtɪŋ",
+    "read": "riːd", "word": "wɜːrd", "sentence": "ˈsɛntəns", "beautiful": "ˈbjuːtɪfl",
+    "happy": "ˈhæpi", "love": "lʌv", "thought": "θɔːt", "through": "θruː",
+    "though": "ðoʊ", "enough": "ɪˈnʌf", "question": "ˈkwɛstʃən", "answer": "ˈænsər",
+    "because": "bɪˈkɔːz", "people's": "ˈpiːplz", "important": "ɪmˈpɔːrtnt",
+    "different": "ˈdɪfərənt", "remember": "rɪˈmɛmbər", "together": "təˈɡɛðər",
+    "morning": "ˈmɔːrnɪŋ", "tonight": "təˈnaɪt", "yesterday": "ˈjɛstərdeɪ",
+    "tomorrow": "təˈmɒroʊ", "weather": "ˈwɛðər", "color": "ˈkʌlər", "colour": "ˈkʌlər",
+    "favourite": "ˈfeɪvərɪt", "favorite": "ˈfeɪvərɪt", "comfortable": "ˈkʌmftəbl",
+    "vegetable": "ˈvɛdʒtəbl", "interesting": "ˈɪntrəstɪŋ", "necessary": "ˈnɛsəsɛri",
+    "february": "ˈfɛbruɛri", "wednesday": "ˈwɛnzdeɪ",
+    "island": "ˈaɪlənd", "knife": "naɪf", "know": "noʊ", "knee": "niː",
+    "hour": "ˈaʊər", "honest": "ˈɒnɪst", "listen": "ˈlɪsn", "castle": "ˈkæsl",
+    "thank": "θæŋk", "think": "θɪŋk", "thing": "θɪŋ", "three": "θriː",
+    "voice": "vɔɪs", "choice": "tʃɔɪs", "nature": "ˈneɪtʃər", "picture": "ˈpɪktʃər",
+    "future": "ˈfjuːtʃər", "culture": "ˈkʌltʃər", "measure": "ˈmɛʒər",
+    "usually": "ˈjuːʒuəli", "decision": "dɪˈsɪʒn", "delicious": "dɪˈlɪʃəs",
+}
+
+
+def clean_phonetic(p: str) -> str:
+    """Normalize an ECDICT phonetic field: trim, strip wrapping slashes/brackets."""
+    p = p.strip().strip("/[]").strip()
+    return p
+
+
+def build_from_csv(src: str) -> dict:
+    out = {}
+    with open(src, newline="", encoding="utf-8") as fh:
+        for row in csv.DictReader(fh):
+            word = (row.get("word") or "").strip().lower()
+            phon = clean_phonetic(row.get("phonetic") or "")
+            if not word or not phon or not WORD_RE.match(word):
+                continue
+            try:
+                rank = int(row.get("frq") or 0) or int(row.get("bnc") or 0)
+            except ValueError:
+                rank = 0
+            if rank <= 0 or rank > MAX_RANK:
+                continue
+            out[word] = phon
+    # Make sure the curated seed is always present (and authoritative).
+    out.update(SEED)
+    return out
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if not args:
+        sys.exit(__doc__)
+    if args[0] == "--seed":
+        data, dest = dict(SEED), args[1]
+    else:
+        src, dest = args[0], args[1]
+        data = build_from_csv(src)
+    with gzip.open(dest, "wt", encoding="utf-8") as fh:
+        json.dump(data, fh, ensure_ascii=False, separators=(",", ":"))
+    print(f"wrote {len(data)} phonetic entries to {dest}")
+
+
+if __name__ == "__main__":
+    main()

scripts/gen_sounds.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Generate Petal's cute UI sound palette as small WAV assets.
+
+These are warm, rounded little sounds — bubble pops, water drops, soft bells —
+played when suggestions and companion bubbles appear. We synthesize them here
+(rather than ship someone else's clips) so they match the app's gentle aesthetic
+exactly and stay tiny. Output lands in web/src/assets/sounds/ where Vite bundles
+and fingerprints them into dist (and so into the embedded Go binary).
+
+Run:  python3 scripts/gen_sounds.py
+"""
+import math
+import os
+import struct
+import wave
+
+SR = 44100
+OUT = os.path.join(os.path.dirname(__file__), "..", "web", "src", "assets", "sounds")
+
+
+def env(n, attack, decay, total):
+    """Smooth attack + exponential decay envelope over `total` seconds."""
+    a = max(1, int(attack * SR))
+    out = []
+    for i in range(n):
+        t = i / SR
+        if i < a:
+            amp = i / a
+        else:
+            amp = math.exp(-(t - attack) / decay)
+        out.append(amp)
+    return out
+
+
+def sine(freq_at, n):
+    """Sine with a per-sample frequency function freq_at(t)->Hz (phase-accurate)."""
+    out = []
+    phase = 0.0
+    for i in range(n):
+        t = i / SR
+        f = freq_at(t)
+        phase += 2 * math.pi * f / SR
+        out.append(math.sin(phase))
+    return out
+
+
+def mix(*layers):
+    n = max(len(l) for l in layers)
+    out = [0.0] * n
+    for l in layers:
+        for i, v in enumerate(l):
+            out[i] += v
+    return out
+
+
+def soft_clip(s):
+    return [math.tanh(v * 1.2) for v in s]
+
+
+def normalize(s, peak=0.9):
+    m = max(1e-9, max(abs(v) for v in s))
+    g = peak / m
+    return [v * g for v in s]
+
+
+def write_wav(name, samples):
+    samples = soft_clip(samples)
+    samples = normalize(samples, 0.85)
+    # 4ms fade-out tail so nothing clicks at the end.
+    tail = int(0.004 * SR)
+    for i in range(tail):
+        samples[-1 - i] *= i / tail
+    os.makedirs(OUT, exist_ok=True)
+    path = os.path.join(OUT, name)
+    with wave.open(path, "w") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(SR)
+        frames = b"".join(struct.pack("<h", int(max(-1, min(1, v)) * 32767)) for v in samples)
+        w.writeframes(frames)
+    print(f"wrote {name}  ({len(samples)/SR*1000:.0f} ms, {len(frames)} bytes)")
+
+
+def apply_env(sig, e):
+    return [s * a for s, a in zip(sig, e)]
+
+
+def bubble_pop():
+    """A cute bubble 'bloop' — pitch swoops up fast then a rounded body."""
+    dur = 0.16
+    n = int(dur * SR)
+    # Rising swoop is the signature of a bubble.
+    body = sine(lambda t: 360 + 720 * (1 - math.exp(-t * 38)), n)
+    body = apply_env(body, env(n, 0.004, 0.05, dur))
+    # A soft octave shimmer on top.
+    shimmer = sine(lambda t: 1080 + 400 * (1 - math.exp(-t * 38)), n)
+    shimmer = apply_env(shimmer, env(n, 0.003, 0.03, dur))
+    shimmer = [v * 0.25 for v in shimmer]
+    return mix(body, shimmer)
+
+
+def droplet():
+    """A clean little water-drop ping — high, downward, watery tail."""
+    dur = 0.22
+    n = int(dur * SR)
+    main = sine(lambda t: 1500 * math.exp(-t * 3.2) + 760, n)
+    main = apply_env(main, env(n, 0.003, 0.06, dur))
+    # Tiny resonant echo for a wet feel.
+    echo = sine(lambda t: 980, n)
+    echo = apply_env(echo, env(n, 0.05, 0.07, dur))
+    echo = [v * 0.2 for v in echo]
+    return mix(main, droop_delay(echo, 0.04))
+
+
+def droop_delay(sig, delay_s):
+    d = int(delay_s * SR)
+    return [0.0] * d + sig
+
+
+def bell(freq, dur, partials=((1, 1.0), (2.01, 0.5), (2.78, 0.28), (4.1, 0.12))):
+    """A soft inharmonic bell tone (sum of slightly detuned partials)."""
+    n = int(dur * SR)
+    layers = []
+    for ratio, amp in partials:
+        s = sine(lambda t, f=freq * ratio: f, n)
+        s = apply_env(s, env(n, 0.005, dur * 0.45, dur))
+        layers.append([v * amp for v in s])
+    return mix(*layers)
+
+
+def chime():
+    """Two gentle bell notes a soft fifth apart."""
+    a = bell(784, 0.42)  # G5
+    b = bell(1175, 0.40)  # D6
+    b = droop_delay(b, 0.10)
+    return mix(a, [v * 0.85 for v in b])
+
+
+def shimmer():
+    """Three quick ascending sparkles — glockenspiel-ish."""
+    notes = [988, 1319, 1976]  # B5, E6, B6
+    layers = []
+    for i, f in enumerate(notes):
+        s = bell(f, 0.30, partials=((1, 1.0), (2.7, 0.3), (5.1, 0.1)))
+        layers.append(droop_delay([v * 0.8 for v in s], 0.06 * i))
+    return mix(*layers)
+
+
+def cheer():
+    """A happy little major arpeggio C5-E5-G5-C6 on bells."""
+    notes = [523, 659, 784, 1047]
+    layers = []
+    for i, f in enumerate(notes):
+        s = bell(f, 0.36)
+        layers.append(droop_delay([v * 0.8 for v in s], 0.075 * i))
+    return mix(*layers)
+
+
+if __name__ == "__main__":
+    write_wav("pop.wav", bubble_pop())
+    write_wav("droplet.wav", droplet())
+    write_wav("chime.wav", chime())
+    write_wav("shimmer.wav", shimmer())
+    write_wav("cheer.wav", cheer())
+    print("done →", os.path.normpath(OUT))

web/package-lock.json

@@ -9,12 +9,22 @@
       "version": "0.0.0",
       "dependencies": {
         "@tiptap/extension-character-count": "^2.11.5",
+        "@tiptap/extension-color": "^2.27.2",
+        "@tiptap/extension-highlight": "^2.27.2",
+        "@tiptap/extension-image": "^2.27.2",
+        "@tiptap/extension-link": "^2.27.2",
         "@tiptap/extension-placeholder": "^2.11.5",
+        "@tiptap/extension-table": "^2.27.2",
+        "@tiptap/extension-table-cell": "^2.27.2",
+        "@tiptap/extension-table-header": "^2.27.2",
+        "@tiptap/extension-table-row": "^2.27.2",
         "@tiptap/extension-text-align": "^2.11.5",
         "@tiptap/extension-underline": "^2.11.5",
         "@tiptap/pm": "^2.11.5",
         "@tiptap/react": "^2.11.5",
         "@tiptap/starter-kit": "^2.11.5",
+        "lottie-web": "^5.13.0",
+        "nspell": "^2.1.5",
         "react": "^19.1.0",
         "react-dom": "^19.1.0"
       },
@@ -23,9 +33,11 @@
         "@types/react": "^19.1.0",
         "@types/react-dom": "^19.1.0",
         "@vitejs/plugin-react": "^4.3.4",
+        "dictionary-en": "^4.0.0",
         "tailwindcss": "^4.0.0",
         "typescript": "^5.7.3",
-        "vite": "^6.1.0"
+        "vite": "^6.1.0",
+        "vitest": "^4.1.9"
       }
     },
     "node_modules/@babel/code-frame": {
@@ -1175,6 +1187,13 @@
         "win32"
       ]
     },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@tailwindcss/node": {
       "version": "4.3.1",
       "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.3.1.tgz",
@@ -1557,6 +1576,20 @@
         "@tiptap/pm": "^2.7.0"
       }
     },
+    "node_modules/@tiptap/extension-color": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-color/-/extension-color-2.27.2.tgz",
+      "integrity": "sha512-sOKCP8/2V3sRM3FdWgMe1lFE5ewsWNCRafiVoujS1+TTHGCj4jw6W+LiumBUk7cRI8kXW/rqGWVC4RVdknYUCA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0",
+        "@tiptap/extension-text-style": "^2.7.0"
+      }
+    },
     "node_modules/@tiptap/extension-document": {
       "version": "2.27.2",
       "resolved": "https://registry.npmjs.org/@tiptap/extension-document/-/extension-document-2.27.2.tgz",
@@ -1641,6 +1674,19 @@
         "@tiptap/core": "^2.7.0"
       }
     },
+    "node_modules/@tiptap/extension-highlight": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-highlight/-/extension-highlight-2.27.2.tgz",
+      "integrity": "sha512-ZjlktDdMjruMJFAVz0TbQf0v92Jqkc7Ri1iZJqBXuLid+r+GxUzl2CVAV7qq5yagkGQgvAG+WGsMk880HgR3MA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0"
+      }
+    },
     "node_modules/@tiptap/extension-history": {
       "version": "2.27.2",
       "resolved": "https://registry.npmjs.org/@tiptap/extension-history/-/extension-history-2.27.2.tgz",
@@ -1669,6 +1715,19 @@
         "@tiptap/pm": "^2.7.0"
       }
     },
+    "node_modules/@tiptap/extension-image": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-image/-/extension-image-2.27.2.tgz",
+      "integrity": "sha512-5zL/BY41FIt72azVrCrv3n+2YJ/JyO8wxCcA4Dk1eXIobcgVyIdo4rG39gCqIOiqziAsqnqoj12QHTBtHsJ6mQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0"
+      }
+    },
     "node_modules/@tiptap/extension-italic": {
       "version": "2.27.2",
       "resolved": "https://registry.npmjs.org/@tiptap/extension-italic/-/extension-italic-2.27.2.tgz",
@@ -1682,6 +1741,23 @@
         "@tiptap/core": "^2.7.0"
       }
     },
+    "node_modules/@tiptap/extension-link": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-link/-/extension-link-2.27.2.tgz",
+      "integrity": "sha512-bnP61qkr0Kj9Cgnop1hxn2zbOCBzNtmawxr92bVTOE31fJv6FhtCnQiD6tuPQVGMYhcmAj7eihtvuEMFfqEPcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "linkifyjs": "^4.3.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0",
+        "@tiptap/pm": "^2.7.0"
+      }
+    },
     "node_modules/@tiptap/extension-list-item": {
       "version": "2.27.2",
       "resolved": "https://registry.npmjs.org/@tiptap/extension-list-item/-/extension-list-item-2.27.2.tgz",
@@ -1748,6 +1824,59 @@
         "@tiptap/core": "^2.7.0"
       }
     },
+    "node_modules/@tiptap/extension-table": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-table/-/extension-table-2.27.2.tgz",
+      "integrity": "sha512-pDbhOpT5phZkcsyPjGBQlXv0+0hmdrvqHJ+dJjkGcCtlfy2pHiEIhmIItOFagc7wXy8G9iUFZ9Jie4zvDf+brg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0",
+        "@tiptap/pm": "^2.7.0"
+      }
+    },
+    "node_modules/@tiptap/extension-table-cell": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-table-cell/-/extension-table-cell-2.27.2.tgz",
+      "integrity": "sha512-9Lk46MjZMFzVZfOj9Kd7VgC6Odt6vmEhlCYVumErShUY7EkFqCw3b2IYoUtQkntfOEx/Afnhff/okNQwPsJeUA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0"
+      }
+    },
+    "node_modules/@tiptap/extension-table-header": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-table-header/-/extension-table-header-2.27.2.tgz",
+      "integrity": "sha512-ZEb6lbG0NbbodWLV0b4BS/QrDIPlUbCcuOsUxzqVvlMUY1Vg6Fj6fKwLaBcsIUDHi8sxZDBEgYEDw3BR/zcO6A==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0"
+      }
+    },
+    "node_modules/@tiptap/extension-table-row": {
+      "version": "2.27.2",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-table-row/-/extension-table-row-2.27.2.tgz",
+      "integrity": "sha512-Nw9+tA56Y5HtLVP01NGCZSUuTQhJPtfK9OfmDgGgcxynn2cRVdEtj+9FNZqRhQ1iRVaAI+Rd4xRvX9qYePMOxw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "^2.7.0"
+      }
+    },
     "node_modules/@tiptap/extension-text": {
       "version": "2.27.2",
       "resolved": "https://registry.npmjs.org/@tiptap/extension-text/-/extension-text-2.27.2.tgz",
@@ -1931,6 +2060,24 @@
         "@babel/types": "^7.28.2"
       }
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.9",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
@@ -2007,12 +2154,135 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/@vitest/expect": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.9.tgz",
+      "integrity": "sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.9.tgz",
+      "integrity": "sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.1.9",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.9.tgz",
+      "integrity": "sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.9.tgz",
+      "integrity": "sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.1.9",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.9.tgz",
+      "integrity": "sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.9.tgz",
+      "integrity": "sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.9.tgz",
+      "integrity": "sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.9",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/argparse": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
       "license": "Python-2.0"
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/baseline-browser-mapping": {
       "version": "2.10.40",
       "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.40.tgz",
@@ -2081,6 +2351,16 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/convert-source-map": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -2129,6 +2409,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/dictionary-en": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/dictionary-en/-/dictionary-en-4.0.0.tgz",
+      "integrity": "sha512-3NHnE1uq33ZE/CIwaZ6gqxa4BnglHnxeAcTM0GJ7cmtRGcvX9InMK/IqLtYcUMFCUpUNgybH+DzkqdgAo3F1zg==",
+      "dev": true,
+      "license": "(MIT AND BSD)",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/electron-to-chromium": {
       "version": "1.5.379",
       "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.379.tgz",
@@ -2162,6 +2453,13 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.1.0.tgz",
+      "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -2226,6 +2524,26 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+      "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -2282,6 +2600,29 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/is-buffer": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-2.0.5.tgz",
+      "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/jiti": {
       "version": "2.7.0",
       "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz",
@@ -2605,6 +2946,18 @@
         "uc.micro": "^2.0.0"
       }
     },
+    "node_modules/linkifyjs": {
+      "version": "4.3.3",
+      "resolved": "https://registry.npmjs.org/linkifyjs/-/linkifyjs-4.3.3.tgz",
+      "integrity": "sha512-P8aEP5U/D1/IlTY2OeYsErdwh9bGuLE30NcXtKEjgdHcahveQoQwM2yZNsioQHsWFz0P7KKudisbrzCgR0sDHg==",
+      "license": "MIT"
+    },
+    "node_modules/lottie-web": {
+      "version": "5.13.0",
+      "resolved": "https://registry.npmjs.org/lottie-web/-/lottie-web-5.13.0.tgz",
+      "integrity": "sha512-+gfBXl6sxXMPe8tKQm7qzLnUy5DUPJPKIyRHwtpCpyUEYjHYRJC/5gjUvdkuO2c3JllrPtHXH5UJJK8LRYl5yQ==",
+      "license": "MIT"
+    },
     "node_modules/lru-cache": {
       "version": "5.1.1",
       "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
@@ -2694,12 +3047,42 @@
         "node": ">=18"
       }
     },
+    "node_modules/nspell": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/nspell/-/nspell-2.1.5.tgz",
+      "integrity": "sha512-PSStyugKMiD9mHmqI/CR5xXrSIGejUXPlo88FBRq5Og1kO5QwQ5Ilu8D8O5I/SHpoS+mibpw6uKA8rd3vXd2Sg==",
+      "license": "MIT",
+      "dependencies": {
+        "is-buffer": "^2.0.0"
+      }
+    },
+    "node_modules/obug": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.3.tgz",
+      "integrity": "sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
     "node_modules/orderedmap": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/orderedmap/-/orderedmap-2.1.1.tgz",
       "integrity": "sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g==",
       "license": "MIT"
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -3051,6 +3434,13 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -3061,6 +3451,20 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.1.0.tgz",
+      "integrity": "sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tailwindcss": {
       "version": "4.3.1",
       "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.1.tgz",
@@ -3082,6 +3486,23 @@
         "url": "https://opencollective.com/webpack"
       }
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz",
+      "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.17",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
@@ -3099,6 +3520,16 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tinyrainbow": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.0.tgz",
+      "integrity": "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/tippy.js": {
       "version": "6.3.7",
       "resolved": "https://registry.npmjs.org/tippy.js/-/tippy.js-6.3.7.tgz",
@@ -3243,12 +3674,119 @@
         }
       }
     },
+    "node_modules/vitest": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.9.tgz",
+      "integrity": "sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.1.9",
+        "@vitest/mocker": "4.1.9",
+        "@vitest/pretty-format": "4.1.9",
+        "@vitest/runner": "4.1.9",
+        "@vitest/snapshot": "4.1.9",
+        "@vitest/spy": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.9",
+        "@vitest/browser-preview": "4.1.9",
+        "@vitest/browser-webdriverio": "4.1.9",
+        "@vitest/coverage-istanbul": "4.1.9",
+        "@vitest/coverage-v8": "4.1.9",
+        "@vitest/ui": "4.1.9",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
     "node_modules/w3c-keyname": {
       "version": "2.2.8",
       "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
       "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
       "license": "MIT"
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",

web/package.json

@@ -6,26 +6,40 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
-    "react": "^19.1.0",
+    "@tiptap/extension-character-count": "^2.11.5",
-    "react-dom": "^19.1.0",
+    "@tiptap/extension-color": "^2.27.2",
-    "@tiptap/react": "^2.11.5",
+    "@tiptap/extension-highlight": "^2.27.2",
-    "@tiptap/pm": "^2.11.5",
+    "@tiptap/extension-image": "^2.27.2",
-    "@tiptap/starter-kit": "^2.11.5",
+    "@tiptap/extension-link": "^2.27.2",
-    "@tiptap/extension-underline": "^2.11.5",
-    "@tiptap/extension-text-align": "^2.11.5",
     "@tiptap/extension-placeholder": "^2.11.5",
-    "@tiptap/extension-character-count": "^2.11.5"
+    "@tiptap/extension-table": "^2.27.2",
+    "@tiptap/extension-table-cell": "^2.27.2",
+    "@tiptap/extension-table-header": "^2.27.2",
+    "@tiptap/extension-table-row": "^2.27.2",
+    "@tiptap/extension-text-align": "^2.11.5",
+    "@tiptap/extension-underline": "^2.11.5",
+    "@tiptap/pm": "^2.11.5",
+    "@tiptap/react": "^2.11.5",
+    "@tiptap/starter-kit": "^2.11.5",
+    "lottie-web": "^5.13.0",
+    "nspell": "^2.1.5",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "@vitejs/plugin-react": "^4.3.4",
+    "dictionary-en": "^4.0.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.3",
-    "vite": "^6.1.0"
+    "vite": "^6.1.0",
+    "vitest": "^4.1.9"
   }
 }

web/public/dictionaries/en/LICENSE

@@ -0,0 +1,347 @@
+en_US Hunspell Dictionary
+Version 2020.12.07
+Mon Dec 7 20:14:35 2020 -0500 [5ef55f9]
+http://wordlist.sourceforge.net
+
+README file for English Hunspell dictionaries derived from SCOWL.
+
+These dictionaries are created using the speller/make-hunspell-dict
+script in SCOWL.
+
+The following dictionaries are available:
+
+  en_US (American)
+  en_CA (Canadian)
+  en_GB-ise (British with "ise" spelling)
+  en_GB-ize (British with "ize" spelling)
+  en_AU (Australian)
+
+  en_US-large
+  en_CA-large
+  en_GB-large (with both "ise" and "ize" spelling)
+  en_AU-large
+
+The normal (non-large) dictionaries correspond to SCOWL size 60 and,
+to encourage consistent spelling, generally only include one spelling
+variant for a word.  The large dictionaries correspond to SCOWL size
+70 and may include multiple spelling for a word when both variants are
+considered almost equal.  The larger dictionaries however (1) have not
+been as carefully checked for errors as the normal dictionaries and
+thus may contain misspelled or invalid words; and (2) contain
+uncommon, yet valid, words that might cause problems as they are
+likely to be misspellings of more common words (for example, "ort" and
+"calender").
+
+To get an idea of the difference in size, here are 25 random words
+only found in the large dictionary for American English:
+
+  Bermejo Freyr's Guenevere Hatshepsut Nottinghamshire arrestment
+  crassitudes crural dogwatches errorless fetial flaxseeds godroon
+  incretion jalapeño's kelpie kishkes neuroglias pietisms pullulation
+  stemwinder stenoses syce thalassic zees
+
+The en_US, en_CA and en_AU are the official dictionaries for Hunspell.
+The en_GB and large dictionaries are made available on an experimental
+basis.  If you find them useful please send me a quick email at
+kevina@gnu.org.
+
+If none of these dictionaries suite you (for example, maybe you want
+the normal dictionary that also includes common variants) additional
+dictionaries can be generated at http://app.aspell.net/create or by
+modifying speller/make-hunspell-dict in SCOWL.  Please do let me know
+if you end up publishing a customized dictionary.
+
+If a word is not found in the dictionary or a word is there you think
+shouldn't be, you can lookup the word up at http://app.aspell.net/lookup
+to help determine why that is.
+
+General comments on these list can be sent directly to me at
+kevina@gnu.org or to the wordlist-devel mailing lists
+(https://lists.sourceforge.net/lists/listinfo/wordlist-devel).  If you
+have specific issues with any of these dictionaries please file a bug
+report at https://github.com/kevina/wordlist/issues.
+
+IMPORTANT CHANGES INTRODUCED In 2016.11.20:
+
+New Australian dictionaries thanks to the work of Benjamin Titze
+(btitze@protonmail.ch).
+
+IMPORTANT CHANGES INTRODUCED IN 2016.04.24:
+
+The dictionaries are now in UTF-8 format instead of ISO-8859-1.  This
+was required to handle smart quotes correctly.
+
+IMPORTANT CHANGES INTRODUCED IN 2016.01.19:
+
+"SET UTF8" was changes to "SET UTF-8" in the affix file as some
+versions of Hunspell do not recognize "UTF8".
+
+ADDITIONAL NOTES:
+
+The NOSUGGEST flag was added to certain taboo words.  While I made an
+honest attempt to flag the strongest taboo words with the NOSUGGEST
+flag, I MAKE NO GUARANTEE THAT I FLAGGED EVERY POSSIBLE TABOO WORD.
+The list was originally derived from Németh László, however I removed
+some words which, while being considered taboo by some dictionaries,
+are not really considered swear words in today's society.
+
+COPYRIGHT, SOURCES, and CREDITS:
+
+The English dictionaries come directly from SCOWL
+and is thus under the same copyright of SCOWL.  The affix file is
+a heavily modified version of the original english.aff file which was
+released as part of Geoff Kuenning's Ispell and as such is covered by
+his BSD license.  Part of SCOWL is also based on Ispell thus the
+Ispell copyright is included with the SCOWL copyright.
+
+The collective work is Copyright 2000-2018 by Kevin Atkinson as well
+as any of the copyrights mentioned below:
+
+  Copyright 2000-2018 by Kevin Atkinson
+
+  Permission to use, copy, modify, distribute and sell these word
+  lists, the associated scripts, the output created from the scripts,
+  and its documentation for any purpose is hereby granted without fee,
+  provided that the above copyright notice appears in all copies and
+  that both that copyright notice and this permission notice appear in
+  supporting documentation. Kevin Atkinson makes no representations
+  about the suitability of this array for any purpose. It is provided
+  "as is" without express or implied warranty.
+
+Alan Beale <biljir@pobox.com> also deserves special credit as he has,
+in addition to providing the 12Dicts package and being a major
+contributor to the ENABLE word list, given me an incredible amount of
+feedback and created a number of special lists (those found in the
+Supplement) in order to help improve the overall quality of SCOWL.
+
+The 10 level includes the 1000 most common English words (according to
+the Moby (TM) Words II [MWords] package), a subset of the 1000 most
+common words on the Internet (again, according to Moby Words II), and
+frequently class 16 from Brian Kelk's "UK English Wordlist
+with Frequency Classification".
+
+The MWords package was explicitly placed in the public domain:
+
+    The Moby lexicon project is complete and has
+    been place into the public domain. Use, sell,
+    rework, excerpt and use in any way on any platform.
+
+    Placing this material on internal or public servers is
+    also encouraged. The compiler is not aware of any
+    export restrictions so freely distribute world-wide.
+
+    You can verify the public domain status by contacting
+
+    Grady Ward
+    3449 Martha Ct.
+    Arcata, CA  95521-4884
+
+    grady@netcom.com
+    grady@northcoast.com
+
+The "UK English Wordlist With Frequency Classification" is also in the
+Public Domain:
+
+  Date: Sat, 08 Jul 2000 20:27:21 +0100
+  From: Brian Kelk <Brian.Kelk@cl.cam.ac.uk>
+
+  > I was wondering what the copyright status of your "UK English
+  > Wordlist With Frequency Classification" word list as it seems to
+  > be lacking any copyright notice.
+
+  There were many many sources in total, but any text marked
+  "copyright" was avoided. Locally-written documentation was one
+  source. An earlier version of the list resided in a filespace called
+  PUBLIC on the University mainframe, because it was considered public
+  domain.
+
+  Date: Tue, 11 Jul 2000 19:31:34 +0100
+
+  > So are you saying your word list is also in the public domain?
+
+  That is the intention.
+
+The 20 level includes frequency classes 7-15 from Brian's word list.
+
+The 35 level includes frequency classes 2-6 and words appearing in at
+least 11 of 12 dictionaries as indicated in the 12Dicts package.  All
+words from the 12Dicts package have had likely inflections added via
+my inflection database.
+
+The 12Dicts package and Supplement is in the Public Domain.
+
+The WordNet database, which was used in the creation of the
+Inflections database, is under the following copyright:
+
+  This software and database is being provided to you, the LICENSEE,
+  by Princeton University under the following license.  By obtaining,
+  using and/or copying this software and database, you agree that you
+  have read, understood, and will comply with these terms and
+  conditions.:
+
+  Permission to use, copy, modify and distribute this software and
+  database and its documentation for any purpose and without fee or
+  royalty is hereby granted, provided that you agree to comply with
+  the following copyright notice and statements, including the
+  disclaimer, and that the same appear on ALL copies of the software,
+  database and documentation, including modifications that you make
+  for internal use or for distribution.
+
+  WordNet 1.6 Copyright 1997 by Princeton University.  All rights
+  reserved.
+
+  THIS SOFTWARE AND DATABASE IS PROVIDED "AS IS" AND PRINCETON
+  UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+  IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PRINCETON
+  UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANT-
+  ABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE
+  LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT INFRINGE ANY
+  THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+
+  The name of Princeton University or Princeton may not be used in
+  advertising or publicity pertaining to distribution of the software
+  and/or database.  Title to copyright in this software, database and
+  any associated documentation shall at all times remain with
+  Princeton University and LICENSEE agrees to preserve same.
+
+The 40 level includes words from Alan's 3esl list found in version 4.0
+of his 12dicts package.  Like his other stuff the 3esl list is also in the
+public domain.
+
+The 50 level includes Brian's frequency class 1, words appearing
+in at least 5 of 12 of the dictionaries as indicated in the 12Dicts
+package, and uppercase words in at least 4 of the previous 12
+dictionaries.  A decent number of proper names is also included: The
+top 1000 male, female, and Last names from the 1990 Census report; a
+list of names sent to me by Alan Beale; and a few names that I added
+myself.  Finally a small list of abbreviations not commonly found in
+other word lists is included.
+
+The name files form the Census report is a government document which I
+don't think can be copyrighted.
+
+The file special-jargon.50 uses common.lst and word.lst from the
+"Unofficial Jargon File Word Lists" which is derived from "The Jargon
+File".  All of which is in the Public Domain.  This file also contain
+a few extra UNIX terms which are found in the file "unix-terms" in the
+special/ directory.
+
+The 55 level includes words from Alan's 2of4brif list found in version
+4.0 of his 12dicts package.  Like his other stuff the 2of4brif is also
+in the public domain.
+
+The 60 level includes all words appearing in at least 2 of the 12
+dictionaries as indicated by the 12Dicts package.
+
+The 70 level includes Brian's frequency class 0 and the 74,550 common
+dictionary words from the MWords package.  The common dictionary words,
+like those from the 12Dicts package, have had all likely inflections
+added.  The 70 level also included the 5desk list from version 4.0 of
+the 12Dics package which is in the public domain.
+
+The 80 level includes the ENABLE word list, all the lists in the
+ENABLE supplement package (except for ABLE), the "UK Advanced Cryptics
+Dictionary" (UKACD), the list of signature words from the YAWL package,
+and the 10,196 places list from the MWords package.
+
+The ENABLE package, mainted by M\Cooper <thegrendel@theriver.com>,
+is in the Public Domain:
+
+  The ENABLE master word list, WORD.LST, is herewith formally released
+  into the Public Domain. Anyone is free to use it or distribute it in
+  any manner they see fit. No fee or registration is required for its
+  use nor are "contributions" solicited (if you feel you absolutely
+  must contribute something for your own peace of mind, the authors of
+  the ENABLE list ask that you make a donation on their behalf to your
+  favorite charity). This word list is our gift to the Scrabble
+  community, as an alternate to "official" word lists. Game designers
+  may feel free to incorporate the WORD.LST into their games. Please
+  mention the source and credit us as originators of the list. Note
+  that if you, as a game designer, use the WORD.LST in your product,
+  you may still copyright and protect your product, but you may *not*
+  legally copyright or in any way restrict redistribution of the
+  WORD.LST portion of your product. This *may* under law restrict your
+  rights to restrict your users' rights, but that is only fair.
+
+UKACD, by J Ross Beresford <ross@bryson.demon.co.uk>, is under the
+following copyright:
+
+  Copyright (c) J Ross Beresford 1993-1999. All Rights Reserved.
+
+  The following restriction is placed on the use of this publication:
+  if The UK Advanced Cryptics Dictionary is used in a software package
+  or redistributed in any form, the copyright notice must be
+  prominently displayed and the text of this document must be included
+  verbatim.
+
+  There are no other restrictions: I would like to see the list
+  distributed as widely as possible.
+
+The 95 level includes the 354,984 single words, 256,772 compound
+words, 4,946 female names and the 3,897 male names, and 21,986 names
+from the MWords package, ABLE.LST from the ENABLE Supplement, and some
+additional words found in my part-of-speech database that were not
+found anywhere else.
+
+Accent information was taken from UKACD.
+
+The VarCon package was used to create the American, British, Canadian,
+and Australian word list.  It is under the following copyright:
+
+  Copyright 2000-2016 by Kevin Atkinson
+
+  Permission to use, copy, modify, distribute and sell this array, the
+  associated software, and its documentation for any purpose is hereby
+  granted without fee, provided that the above copyright notice appears
+  in all copies and that both that copyright notice and this permission
+  notice appear in supporting documentation. Kevin Atkinson makes no
+  representations about the suitability of this array for any
+  purpose. It is provided "as is" without express or implied warranty.
+
+  Copyright 2016 by Benjamin Titze
+
+  Permission to use, copy, modify, distribute and sell this array, the
+  associated software, and its documentation for any purpose is hereby
+  granted without fee, provided that the above copyright notice appears
+  in all copies and that both that copyright notice and this permission
+  notice appear in supporting documentation. Benjamin Titze makes no
+  representations about the suitability of this array for any
+  purpose. It is provided "as is" without express or implied warranty.
+
+  Since the original words lists come from the Ispell distribution:
+
+  Copyright 1993, Geoff Kuenning, Granada Hills, CA
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+
+  1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+  2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+  3. All modifications to the source code must be clearly marked as
+     such.  Binary redistributions based on modified source code
+     must be clearly marked as modified versions in the documentation
+     and/or other materials provided with the distribution.
+  (clause 4 removed with permission from Geoff Kuenning)
+  5. The name of Geoff Kuenning may not be used to endorse or promote
+     products derived from this software without specific prior
+     written permission.
+
+  THIS SOFTWARE IS PROVIDED BY GEOFF KUENNING AND CONTRIBUTORS ``AS IS'' AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED.  IN NO EVENT SHALL GEOFF KUENNING OR CONTRIBUTORS BE LIABLE
+  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+  SUCH DAMAGE.
+
+Build Date: Mon Dec  7 20:19:27 EST 2020
+Wordlist Command: mk-list --accents=strip en_US 60

web/public/dictionaries/en/en.aff

@@ -0,0 +1,205 @@
+SET UTF-8
+TRY esianrtolcdugmphbyfvkwzESIANRTOLCDUGMPHBYFVKWZ'
+ICONV 1
+ICONV ’ '
+NOSUGGEST !
+
+# ordinal numbers
+COMPOUNDMIN 1
+# only in compounds: 1th, 2th, 3th
+ONLYINCOMPOUND c
+# compound rules:
+# 1. [0-9]*1[0-9]th (10th, 11th, 12th, 56714th, etc.)
+# 2. [0-9]*[02-9](1st|2nd|3rd|[4-9]th) (21st, 22nd, 123rd, 1234th, etc.)
+COMPOUNDRULE 2
+COMPOUNDRULE n*1t
+COMPOUNDRULE n*mp
+WORDCHARS 0123456789
+
+PFX A Y 1
+PFX A   0     re         .
+
+PFX I Y 1
+PFX I   0     in         .
+
+PFX U Y 1
+PFX U   0     un         .
+
+PFX C Y 1
+PFX C   0     de          .
+
+PFX E Y 1
+PFX E   0     dis         .
+
+PFX F Y 1
+PFX F   0     con         .
+
+PFX K Y 1
+PFX K   0     pro         .
+
+SFX V N 2
+SFX V   e     ive        e
+SFX V   0     ive        [^e]
+
+SFX N Y 3
+SFX N   e     ion        e
+SFX N   y     ication    y
+SFX N   0     en         [^ey]
+
+SFX X Y 3
+SFX X   e     ions       e
+SFX X   y     ications   y
+SFX X   0     ens        [^ey]
+
+SFX H N 2
+SFX H   y     ieth       y
+SFX H   0     th         [^y]
+
+SFX Y Y 1
+SFX Y   0     ly         .
+
+SFX G Y 2
+SFX G   e     ing        e
+SFX G   0     ing        [^e]
+
+SFX J Y 2
+SFX J   e     ings       e
+SFX J   0     ings       [^e]
+
+SFX D Y 4
+SFX D   0     d          e
+SFX D   y     ied        [^aeiou]y
+SFX D   0     ed         [^ey]
+SFX D   0     ed         [aeiou]y
+
+SFX T N 4
+SFX T   0     st         e
+SFX T   y     iest       [^aeiou]y
+SFX T   0     est        [aeiou]y
+SFX T   0     est        [^ey]
+
+SFX R Y 4
+SFX R   0     r          e
+SFX R   y     ier        [^aeiou]y
+SFX R   0     er         [aeiou]y
+SFX R   0     er         [^ey]
+
+SFX Z Y 4
+SFX Z   0     rs         e
+SFX Z   y     iers       [^aeiou]y
+SFX Z   0     ers        [aeiou]y
+SFX Z   0     ers        [^ey]
+
+SFX S Y 4
+SFX S   y     ies        [^aeiou]y
+SFX S   0     s          [aeiou]y
+SFX S   0     es         [sxzh]
+SFX S   0     s          [^sxzhy]
+
+SFX P Y 3
+SFX P   y     iness      [^aeiou]y
+SFX P   0     ness       [aeiou]y
+SFX P   0     ness       [^y]
+
+SFX M Y 1
+SFX M   0     's         .
+
+SFX B Y 3
+SFX B   0     able       [^aeiou]
+SFX B   0     able       ee
+SFX B   e     able       [^aeiou]e
+
+SFX L Y 1
+SFX L   0     ment       .
+
+REP 90
+REP a ei
+REP ei a
+REP a ey
+REP ey a
+REP ai ie
+REP ie ai
+REP alot a_lot
+REP are air
+REP are ear
+REP are eir
+REP air are
+REP air ere
+REP ere air
+REP ere ear
+REP ere eir
+REP ear are
+REP ear air
+REP ear ere
+REP eir are
+REP eir ere
+REP ch te
+REP te ch
+REP ch ti
+REP ti ch
+REP ch tu
+REP tu ch
+REP ch s
+REP s ch
+REP ch k
+REP k ch
+REP f ph
+REP ph f
+REP gh f
+REP f gh
+REP i igh
+REP igh i
+REP i uy
+REP uy i
+REP i ee
+REP ee i
+REP j di
+REP di j
+REP j gg
+REP gg j
+REP j ge
+REP ge j
+REP s ti
+REP ti s
+REP s ci
+REP ci s
+REP k cc
+REP cc k
+REP k qu
+REP qu k
+REP kw qu
+REP o eau
+REP eau o
+REP o ew
+REP ew o
+REP oo ew
+REP ew oo
+REP ew ui
+REP ui ew
+REP oo ui
+REP ui oo
+REP ew u
+REP u ew
+REP oo u
+REP u oo
+REP u oe
+REP oe u
+REP u ieu
+REP ieu u
+REP ue ew
+REP ew ue
+REP uff ough
+REP oo ieu
+REP ieu oo
+REP ier ear
+REP ear ier
+REP ear air
+REP air ear
+REP w qu
+REP qu w
+REP z ss
+REP ss z
+REP shun tion
+REP shun sion
+REP shun cion
+REP size cise

web/src/App.tsx

@@ -1,45 +1,557 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { api, type DocSummary, type Document, type Suggestion, type Tag, type TagColor } from './api/client'
+import { useAutoSave } from './hooks/useAutoSave'
+import { useCheckpoint } from './hooks/useCheckpoint'
+import { useSpellChecker } from './hooks/useSpellChecker'
+import { useTags } from './hooks/useTags'
+import { DocList } from './components/DocList/DocList'
+import { EditorCore, type EditorChange } from './components/Editor/EditorCore'
+import { ToneSelect } from './components/Editor/ToneSelect'
+import { ExportMenu } from './components/Export/ExportMenu'
+import { HistoryPanel } from './components/History/HistoryPanel'
+import { GardenPanel } from './components/Garden/GardenPanel'
+import { StatusBar } from './components/StatusBar/StatusBar'
+import { PetalCompanion } from './components/Companion/PetalCompanion'
+import { UpdateBanner } from './components/UpdateBanner/UpdateBanner'
+import { useVersionWatch } from './hooks/useVersionWatch'
+import { PetalFall } from './effects/PetalFall'
+import { useNightMode } from './hooks/useNightMode'
+import { playSuggestionSound } from './audio/sounds'
 
-// Phase 0 placeholder: proves the stack end-to-end — React + Tailwind v4 tokens
-// rendering, and the Go backend reachable via the /api proxy. Real UI lands in
-// later phases (DocList, Editor, StatusBar).
 export default function App() {
-  const [api, setApi] = useState<'checking' | 'ok' | 'down'>('checking')
+  const updateAvailable = useVersionWatch()
+  // Late-night calm mode: dark theme + falling stars instead of petals. The hook
+  // toggles the `petal-night` class on <html>; we pass the flag to the ambient
+  // layer so the petals become stars.
+  const night = useNightMode()
+  const [docs, setDocs] = useState<DocSummary[]>([])
+  const [currentDoc, setCurrentDoc] = useState<Document | null>(null)
+  const [title, setTitle] = useState('')
+  const [wordCount, setWordCount] = useState(0)
+  // The current document's target tone (steers checkpoint advice) and its live
+  // plain text (drives the expanded writing-stats panel in the StatusBar).
+  const [tone, setTone] = useState('general')
+  const [docText, setDocText] = useState('')
+  const [ready, setReady] = useState(false)
+  // Distraction-free mode: entered on editor focus, collapses the doc-list
+  // sidebar. Escape or a click outside the editor canvas restores it.
+  const [focusMode, setFocusMode] = useState(false)
+  // Mobile drawer: below the tablet breakpoint the sidebar is an overlay toggled
+  // by the header hamburger. Ignored on wide screens (sidebar is always in-flow).
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  const canvasRef = useRef<HTMLDivElement>(null)
+  // Monotonic counters the companion watches to react to writing + accepts.
+  const [editTick, setEditTick] = useState(0)
+  const [acceptTick, setAcceptTick] = useState(0)
+  // History drawer visibility, and an epoch bumped on restore to force the
+  // editor to remount with the restored content (its initialContent is read
+  // only on mount).
+  const [historyOpen, setHistoryOpen] = useState(false)
+  const [gardenOpen, setGardenOpen] = useState(false)
+  const [editorEpoch, setEditorEpoch] = useState(0)
 
-  useEffect(() => {
+  // Live mirrors of the current doc's editable fields so the "discard blank
-    fetch('/api/health')
+  // drafts on navigation" logic can read the latest values without rebuilding
-      .then((r) => setApi(r.ok ? 'ok' : 'down'))
+  // callbacks on every keystroke.
-      .catch(() => setApi('down'))
+  const currentDocRef = useRef(currentDoc)
+  const titleRef = useRef(title)
+  const wordCountRef = useRef(wordCount)
+  currentDocRef.current = currentDoc
+  titleRef.current = title
+  wordCountRef.current = wordCount
+
+  // A throwaway blank draft: no words and still the default/empty title. We
+  // delete these on navigation rather than leave orphan "Untitled" docs behind.
+  const isBlankDraft = useCallback(() => {
+    const t = titleRef.current.trim()
+    return wordCountRef.current === 0 && (t === '' || t === 'Untitled')
   }, [])
 
+  const { status, schedule, saveNow } = useAutoSave(currentDoc?.id ?? null)
+  const {
+    suggestions,
+    checking,
+    voicing,
+    collocating,
+    llmDown,
+    schedule: scheduleCheckpoint,
+    runVoice,
+    runCollocation,
+    removeSuggestion,
+  } = useCheckpoint(currentDoc?.id ?? null)
+  // Browser-side spell checker — loads the en-US dictionary once per session.
+  const { checker: spellChecker, addWord } = useSpellChecker()
+  // The tag roster (with counts). Assignments live on the doc summaries below.
+  const { tags: tagRoster, refresh: refreshTags, createTag } = useTags()
+
+  // Patch a summary in the sidebar list (optimistic title / word-count updates).
+  const patchSummary = useCallback((id: string, patch: Partial<DocSummary>) => {
+    setDocs((prev) => prev.map((d) => (d.id === id ? { ...d, ...patch } : d)))
+  }, [])
+
+  // Attach or detach a tag on a document, updating the sidebar optimistically and
+  // refreshing the roster so its counts stay current. Tags are kept sorted by
+  // name to match the server's ordering.
+  const setDocTag = useCallback(
+    async (docId: string, tag: Tag, attach: boolean) => {
+      setDocs((prev) =>
+        prev.map((d) => {
+          if (d.id !== docId) return d
+          const without = d.tags.filter((t) => t.id !== tag.id)
+          const next = attach ? [...without, tag] : without
+          next.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }))
+          return { ...d, tags: next }
+        }),
+      )
+      try {
+        if (attach) await api.assignTag(docId, tag.id)
+        else await api.unassignTag(docId, tag.id)
+        void refreshTags()
+      } catch (err) {
+        console.error('tag assignment failed', err)
+        void refreshTags()
+      }
+    },
+    [refreshTags],
+  )
+
+  const handleToggleTag = useCallback(
+    (docId: string, tag: Tag) => {
+      const doc = docs.find((d) => d.id === docId)
+      const has = doc?.tags.some((t) => t.id === tag.id) ?? false
+      void setDocTag(docId, tag, !has)
+    },
+    [docs, setDocTag],
+  )
+
+  const handleCreateTag = useCallback(
+    async (docId: string, name: string, color: TagColor) => {
+      const tag = await createTag(name, color)
+      if (tag) void setDocTag(docId, tag, true)
+    },
+    [createTag, setDocTag],
+  )
+
+  const openDoc = useCallback(
+    async (id: string) => {
+      setDrawerOpen(false) // close the mobile drawer when a doc is chosen
+      // Decide the leaving doc's fate before any await mutates state.
+      const leaving = currentDocRef.current
+      const leavingBlank = isBlankDraft()
+      await saveNow() // flush any pending edits to the doc we're leaving
+      const doc = await api.getDoc(id)
+      setCurrentDoc(doc)
+      setTitle(doc.title)
+      setWordCount(doc.word_count)
+      setTone(doc.tone || 'general')
+      setDocText(doc.content_text)
+      // Leaving an untouched blank draft for a different doc? Drop it silently
+      // (best-effort cleanup — a 404 just means it's already gone).
+      if (leaving && leaving.id !== id && leavingBlank) {
+        api.deleteDoc(leaving.id).catch(() => {})
+        setDocs((prev) => prev.filter((d) => d.id !== leaving.id))
+      }
+    },
+    [saveNow, isBlankDraft],
+  )
+
+  // Initial load: fetch the list, opening the first doc (or creating one).
+  const bootedRef = useRef(false)
+  useEffect(() => {
+    if (bootedRef.current) return
+    bootedRef.current = true
+    ;(async () => {
+      try {
+        let list = await api.listDocs()
+        if (list.length === 0) {
+          const fresh = await api.createDoc()
+          list = [{ id: fresh.id, title: fresh.title, word_count: 0, updated_at: fresh.updated_at, tags: [] }]
+          setDocs(list)
+          setCurrentDoc(fresh)
+          setTitle(fresh.title)
+          setWordCount(0)
+          setTone(fresh.tone || 'general')
+          setDocText('')
+        } else {
+          setDocs(list)
+          await openDoc(list[0].id)
+        }
+      } catch (err) {
+        console.error('failed to load documents', err)
+      } finally {
+        setReady(true)
+      }
+    })()
+  }, [openDoc])
+
+  const handleCreate = useCallback(async () => {
+    // Already sitting on a fresh blank draft? Reuse it instead of stacking
+    // another empty "Untitled" on top.
+    if (currentDocRef.current && isBlankDraft()) return
+    await saveNow()
+    const fresh = await api.createDoc()
+    setDocs((prev) => [
+      { id: fresh.id, title: fresh.title, word_count: 0, updated_at: fresh.updated_at, tags: [] },
+      ...prev,
+    ])
+    setCurrentDoc(fresh)
+    setTitle(fresh.title)
+    setWordCount(0)
+    setTone(fresh.tone || 'general')
+    setDocText('')
+  }, [saveNow, isBlankDraft])
+
+  // Duplicate a document: copy its body/tone into a fresh doc titled "… (副本)",
+  // then open the copy. Tags aren't carried over (a fresh start for the copy).
+  const handleDuplicate = useCallback(
+    async (id: string) => {
+      try {
+        await saveNow() // flush in case we're duplicating the open doc
+        const src = await api.getDoc(id)
+        const fresh = await api.createDoc()
+        const dupTitle = `${src.title?.trim() || 'Untitled'} (副本)`
+        const updated = await api.updateDoc(fresh.id, {
+          title: dupTitle,
+          content: src.content,
+          content_text: src.content_text,
+          tone: src.tone,
+          word_count: src.word_count,
+        })
+        setDocs((prev) => [
+          { id: updated.id, title: updated.title, word_count: updated.word_count, updated_at: updated.updated_at, tags: [] },
+          ...prev,
+        ])
+        setCurrentDoc(updated)
+        setTitle(updated.title)
+        setWordCount(updated.word_count)
+        setTone(updated.tone || 'general')
+        setDocText(updated.content_text)
+      } catch (err) {
+        console.error('duplicate failed', err)
+      }
+    },
+    [saveNow],
+  )
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      await api.deleteDoc(id)
+      setDocs((prev) => {
+        const remaining = prev.filter((d) => d.id !== id)
+        if (currentDoc?.id === id) {
+          if (remaining.length > 0) {
+            void openDoc(remaining[0].id)
+          } else {
+            setCurrentDoc(null)
+            setTitle('')
+            setWordCount(0)
+            setTone('general')
+            setDocText('')
+          }
+        }
+        return remaining
+      })
+    },
+    [currentDoc, openDoc],
+  )
+
+  const handleTitleChange = useCallback(
+    (value: string) => {
+      setTitle(value)
+      if (currentDoc) {
+        patchSummary(currentDoc.id, { title: value })
+        schedule({ title: value })
+      }
+    },
+    [currentDoc, patchSummary, schedule],
+  )
+
+  const handleEditorChange = useCallback(
+    (change: EditorChange) => {
+      setWordCount(change.word_count)
+      setDocText(change.content_text)
+      setEditTick((n) => n + 1)
+      if (currentDoc) {
+        patchSummary(currentDoc.id, { word_count: change.word_count })
+        schedule(change)
+        scheduleCheckpoint(change.content_text)
+      }
+    },
+    [currentDoc, patchSummary, schedule, scheduleCheckpoint],
+  )
+
+  // Changing the tone persists it and re-runs the checkpoint so Petal's advice
+  // re-tunes to the new register. The auto-save (1.5s) lands before the
+  // checkpoint debounce (4s), so the server reads the updated tone.
+  const handleToneChange = useCallback(
+    (value: string) => {
+      setTone(value)
+      if (currentDoc) {
+        schedule({ tone: value })
+        scheduleCheckpoint()
+      }
+    },
+    [currentDoc, schedule, scheduleCheckpoint],
+  )
+
+  // Accept applies the replacement in the editor (handled in EditorCore) and
+  // marks the suggestion accepted; dismiss just rejects it. Both drop it locally.
+  const handleAccept = useCallback(
+    async (s: Suggestion) => {
+      removeSuggestion(s.id)
+      setAcceptTick((n) => n + 1)
+      try {
+        await api.acceptSuggestion(s.id)
+      } catch (err) {
+        console.error('accept failed', err)
+      }
+    },
+    [removeSuggestion],
+  )
+
+  // After restoring a version, swap the restored doc into the editor. Bumping
+  // editorEpoch remounts EditorCore so it picks up the restored content.
+  const handleRestored = useCallback(
+    (doc: Document) => {
+      setCurrentDoc(doc)
+      setTitle(doc.title)
+      setWordCount(doc.word_count)
+      setTone(doc.tone || 'general')
+      setDocText(doc.content_text)
+      patchSummary(doc.id, { title: doc.title, word_count: doc.word_count })
+      setEditorEpoch((n) => n + 1)
+    },
+    [patchSummary],
+  )
+
+  // Escape always restores the sidebar while in distraction-free mode.
+  useEffect(() => {
+    if (!focusMode) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setFocusMode(false)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [focusMode])
+
+  // A pointer-down outside the centered editor canvas (the cream gutters, the
+  // header, the status bar) also restores the sidebar.
+  const handleChromeDown = useCallback((e: React.MouseEvent) => {
+    if (!canvasRef.current?.contains(e.target as Node)) setFocusMode(false)
+  }, [])
+
+  const handleDismiss = useCallback(
+    async (s: Suggestion) => {
+      removeSuggestion(s.id)
+      try {
+        await api.dismissSuggestion(s.id)
+      } catch (err) {
+        console.error('dismiss failed', err)
+      }
+    },
+    [removeSuggestion],
+  )
+
+  // Play a soft sound when freshly-checked suggestions arrive — one per distinct
+  // new type, lightly staggered so a batch reads as a little melody rather than
+  // a pile-up. We track which ids we've already chimed for, and only chime for
+  // recently-created suggestions so opening a doc with old pending advice stays
+  // silent (the existing set was created in a past session).
+  const chimedRef = useRef<Set<string>>(new Set())
+  useEffect(() => {
+    const fresh = suggestions.filter((s) => !chimedRef.current.has(s.id))
+    fresh.forEach((s) => chimedRef.current.add(s.id))
+    const justMade = fresh.filter(
+      (s) => Date.now() - new Date(s.created_at).getTime() < 12_000,
+    )
+    if (justMade.length === 0) return
+    const types = [...new Set(justMade.map((s) => s.type))].slice(0, 3)
+    const timers = types.map((t, i) =>
+      window.setTimeout(() => playSuggestionSound(t), i * 150),
+    )
+    return () => timers.forEach((id) => window.clearTimeout(id))
+  }, [suggestions])
+
+  // Forget chimed ids when switching documents so the set can't grow unbounded.
+  useEffect(() => {
+    chimedRef.current = new Set()
+  }, [currentDoc?.id])
+
   return (
-    <div className="flex h-full flex-col items-center justify-center gap-6 px-6 text-center">
+    <div className="flex h-full flex-col">
-      <div
+      <PetalFall night={night} />
-        className="flex flex-col items-center gap-3 bg-surface px-12 py-10"
+      <header
-        style={{ borderRadius: 'var(--radius-card)', boxShadow: 'var(--shadow-soft)' }}
+        onMouseDown={handleChromeDown}
+        className="petal-no-print flex h-12 shrink-0 items-center gap-2 px-5"
+        style={{ borderBottom: '1px solid var(--color-border)' }}
       >
-        <span className="text-5xl">🌸</span>
+        <button
-        <h1 className="text-3xl font-extrabold text-plum">Petal</h1>
+          type="button"
-        <p className="max-w-xs text-muted" style={{ fontFamily: 'var(--font-body)' }}>
+          aria-label="Toggle document list"
-          A cozy place to write.
+          onClick={() => {
-        </p>
+            setFocusMode(false)
-        <span
+            setDrawerOpen((v) => !v)
-          className="mt-2 inline-flex items-center gap-2 px-4 py-1.5 text-sm font-semibold"
+          }}
-          style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-surface-alt)' }}
+          className="petal-sidebar-toggle petal-tap-sm -ml-2 mr-1 items-center justify-center text-xl"
+          style={{ borderRadius: 'var(--radius-pill)', width: 36, height: 36, color: 'var(--color-plum)' }}
         >
-          <span
+          ☰
-            className="inline-block h-2 w-2 rounded-full"
+        </button>
-            style={{
+        <span className="text-xl">🌸</span>
-              background:
+        <span className="text-lg font-extrabold text-plum">Petal</span>
-                api === 'ok'
+        <button
-                  ? 'var(--color-success)'
+          type="button"
-                  : api === 'down'
+          onClick={() => setGardenOpen(true)}
-                    ? 'var(--color-accent)'
+          aria-label="Vocabulary garden"
-                    : 'var(--color-muted)',
+          title="Words you've looked up, blooming for review"
-            }}
+          className="petal-tap-sm ml-auto inline-flex h-9 items-center gap-1.5 whitespace-nowrap px-3 text-sm font-bold"
+          style={{
+            borderRadius: 'var(--radius-pill)',
+            background: 'var(--color-surface)',
+            color: 'var(--color-plum)',
+            boxShadow: 'var(--shadow-soft)',
+          }}
+        >
+          <span aria-hidden>🌷</span>
+          <span>词汇花园</span>
+          <span style={{ color: 'var(--color-muted)' }}>· Garden</span>
+        </button>
+      </header>
+
+      <div className="relative flex min-h-0 flex-1">
+        <div
+          className={`petal-no-print petal-sidebar shrink-0${focusMode ? ' petal-sidebar-hidden' : ''}${drawerOpen ? ' petal-drawer-open' : ''}`}
+        >
+          <DocList
+            docs={docs}
+            roster={tagRoster}
+            selectedId={currentDoc?.id ?? null}
+            onSelect={openDoc}
+            onCreate={handleCreate}
+            onDelete={handleDelete}
+            onDuplicate={handleDuplicate}
+            onToggleTag={handleToggleTag}
+            onCreateTag={handleCreateTag}
           />
-          {api === 'checking' ? 'Checking backend…' : api === 'ok' ? 'Backend connected' : 'Backend offline'}
+        </div>
-        </span>
+
+        <div
+          className={`petal-no-print petal-scrim${drawerOpen ? ' petal-scrim-show' : ''}`}
+          onClick={() => setDrawerOpen(false)}
+          aria-hidden
+        />
+
+        <main className="flex min-w-0 flex-1 flex-col">
+          {currentDoc ? (
+            <>
+              <div
+                onMouseDown={handleChromeDown}
+                className="flex flex-1 flex-col overflow-y-auto px-6 py-8"
+              >
+                <div ref={canvasRef} className="mx-auto flex w-full max-w-[720px] flex-1 flex-col">
+                  <div className="mb-5 flex items-center gap-3">
+                    <input
+                      value={title}
+                      onChange={(e) => handleTitleChange(e.target.value)}
+                      placeholder="Untitled"
+                      aria-label="Document title"
+                      className="min-w-0 flex-1 bg-transparent text-3xl font-extrabold text-plum focus:outline-none"
+                      style={{ fontFamily: 'var(--font-ui)' }}
+                    />
+                    <div className="petal-no-print shrink-0">
+                      <ToneSelect value={tone} onChange={handleToneChange} />
+                    </div>
+                    <button
+                      type="button"
+                      onClick={() => setHistoryOpen(true)}
+                      aria-label="Version history"
+                      title="Browse and restore earlier versions"
+                      className="petal-no-print inline-flex h-9 shrink-0 items-center gap-1.5 whitespace-nowrap px-3 text-sm font-bold"
+                      style={{
+                        borderRadius: 'var(--radius-pill)',
+                        background: 'var(--color-surface)',
+                        color: 'var(--color-plum)',
+                        boxShadow: 'var(--shadow-soft)',
+                      }}
+                    >
+                      <span aria-hidden>🕘</span>
+                      <span>历史</span>
+                      <span style={{ color: 'var(--color-muted)' }}>· History</span>
+                    </button>
+                    <div className="petal-no-print">
+                      <ExportMenu docId={currentDoc.id} />
+                    </div>
+                  </div>
+                  <EditorCore
+                    key={`${currentDoc.id}:${editorEpoch}`}
+                    docId={currentDoc.id}
+                    initialContent={currentDoc.content}
+                    onChange={handleEditorChange}
+                    suggestions={suggestions}
+                    onAccept={handleAccept}
+                    onDismiss={handleDismiss}
+                    onVoiceCheck={runVoice}
+                    voicing={voicing}
+                    onCollocationCheck={runCollocation}
+                    collocating={collocating}
+                    onFocusMode={() => setFocusMode(true)}
+                    spellChecker={spellChecker}
+                    onAddWord={addWord}
+                  />
+                </div>
+              </div>
+              <div className="petal-no-print" onMouseDown={handleChromeDown}>
+                <StatusBar
+                  wordCount={wordCount}
+                  text={docText}
+                  saveStatus={status}
+                  checking={checking}
+                  voicing={voicing}
+                  collocating={collocating}
+                  llmDown={llmDown}
+                />
+              </div>
+            </>
+          ) : (
+            <div
+              className="flex flex-1 items-center justify-center text-sm"
+              style={{ color: 'var(--color-muted)' }}
+            >
+              {ready ? 'Create a document to start writing.' : 'Loading…'}
+            </div>
+          )}
+        </main>
+      </div>
+
+      {historyOpen && currentDoc && (
+        <HistoryPanel
+          docId={currentDoc.id}
+          onClose={() => setHistoryOpen(false)}
+          onRestored={handleRestored}
+        />
+      )}
+
+      {gardenOpen && (
+        <GardenPanel
+          onClose={() => setGardenOpen(false)}
+          onOpenDoc={(id) => {
+            setGardenOpen(false)
+            void openDoc(id)
+          }}
+        />
+      )}
+
+      {updateAvailable && <UpdateBanner />}
+
+      <div className="petal-no-print">
+        <PetalCompanion
+          wordCount={wordCount}
+          saveStatus={status}
+          llmDown={llmDown}
+          editTick={editTick}
+          acceptTick={acceptTick}
+          text={docText}
+        />
       </div>
     </div>
   )

web/src/api/client.ts

@@ -0,0 +1,400 @@
+// Thin fetch wrappers for the Petal backend. Everything lives under /api, which
+// Vite proxies to the Go server in dev and the binary serves directly in prod.
+
+// A tag's palette key, mapped to a CSS color on the frontend. Mirrors the
+// backend TagColor* constants; unknown values render as rose.
+export type TagColor = 'rose' | 'mint' | 'peach' | 'lavender' | 'sky' | 'honey'
+
+export interface Tag {
+  id: string
+  name: string
+  color: TagColor
+  doc_count?: number // present only in the tag-roster listing
+}
+
+export interface DocSummary {
+  id: string
+  title: string
+  word_count: number
+  updated_at: string
+  tags: Tag[]
+}
+
+// One cross-document search hit. `snippet` is plain text with the matched span
+// wrapped in the 
… sentinels (see splitSnippet) for highlighting.
+export interface SearchResult {
+  id: string
+  title: string
+  word_count: number
+  updated_at: string
+  snippet: string
+  tags: Tag[]
+}
+
+export interface Document {
+  id: string
+  user_id: string
+  title: string
+  content: string // Tiptap JSON (stringified)
+  content_text: string // flattened plain text
+  tone: string // target writing tone; steers LLM advice
+  word_count: number
+  created_at: string
+  updated_at: string
+}
+
+// Fields the editor sends on auto-save. All optional so a rename can send title
+// alone; the editor sends the full set.
+export interface DocUpdate {
+  title?: string
+  content?: string
+  content_text?: string
+  tone?: string
+  word_count?: number
+}
+
+// One sense of a word from the offline dictionary.
+export interface WordMeaning {
+  part_of_speech: string
+  definition: string
+  example?: string
+}
+
+// The offline lookup for one word: a Chinese gloss, a few definition senses, and
+// a list of synonyms. Any of these may be empty when the word isn't a headword.
+export interface WordInfo {
+  word: string
+  gloss: string // Chinese translation; '' when the word isn't in the gloss set
+  phonetic: string // IPA for the English word; '' when absent
+  definitions: WordMeaning[]
+  synonyms: string[]
+}
+
+// The lightweight Chinese-only gloss behind the inline hover/select tooltip.
+export interface Gloss {
+  word: string
+  gloss: string
+}
+
+export type SuggestionType = 'grammar' | 'phrasing' | 'idiom' | 'clarity' | 'voice' | 'collocation' | 'mechanics'
+
+// One word in the vocabulary garden: a looked-up word with its gloss/phonetic,
+// the sentence it was met in, and its spaced-repetition state. `reps` drives how
+// "bloomed" its blossom looks; `due_at` decides when it next surfaces for review.
+export interface VocabWord {
+  id: string
+  word: string
+  gloss: string
+  definition: string // English fallback meaning shown in review when there's no gloss
+  phonetic: string
+  example: string
+  doc_id: string | null
+  due_at: string
+  interval_days: number
+  ease: number
+  reps: number
+  lapses: number
+  last_reviewed: string | null
+  created_at: string
+}
+
+// The self-assessment grades a flashcard review can record.
+export type VocabGrade = 'again' | 'good' | 'easy'
+
+// A point-in-time snapshot of a document. List responses omit the heavy
+// content/content_text fields; they arrive only on getVersion (preview/restore).
+export interface DocumentVersion {
+  id: string
+  doc_id: string
+  title: string
+  content?: string
+  content_text?: string
+  word_count: number
+  kind: 'auto' | 'manual' | 'pre_restore'
+  created_at: string
+}
+
+// Downloadable export formats. PDF is handled client-side via the browser's
+// print dialog (CJK-safe, no server-side font embedding).
+export type ExportFormat = 'md' | 'html' | 'txt' | 'docx'
+
+// A single LLM-proposed edit. `original` is the source of truth for placement —
+// the editor re-anchors by matching this string in the live document (spec
+// Note #6); from_pos/to_pos are server-side advisory only. `replacement` is
+// empty for voice flags (awareness-only, no correction to apply).
+export interface Suggestion {
+  id: string
+  doc_id: string
+  from_pos: number
+  to_pos: number
+  original: string
+  replacement: string
+  explanation: string
+  type: SuggestionType
+  status: 'pending' | 'accepted' | 'rejected'
+  created_at: string
+}
+
+// A deterministic, rule-based fix detected client-side (see Companion/prose.ts).
+// The frontend owns mechanics detection; the backend only persists these as the
+// 'mechanics' suggestion family. Spans are exact plaintext offsets.
+export interface MechanicsFinding {
+  from: number
+  to: number
+  original: string
+  replacement: string
+  explanation: string
+}
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`/api${path}`, {
+    headers: { 'Content-Type': 'application/json' },
+    ...init,
+  })
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw new Error(`${res.status} ${res.statusText}${detail ? `: ${detail}` : ''}`)
+  }
+  if (res.status === 204) return undefined as T
+  return res.json() as Promise<T>
+}
+
+export const api = {
+  listDocs: () => req<DocSummary[]>('/docs'),
+  createDoc: () => req<Document>('/docs', { method: 'POST' }),
+  getDoc: (id: string) => req<Document>(`/docs/${id}`),
+  updateDoc: (id: string, body: DocUpdate) =>
+    req<Document>(`/docs/${id}`, { method: 'PUT', body: JSON.stringify(body) }),
+  deleteDoc: (id: string) => req<void>(`/docs/${id}`, { method: 'DELETE' }),
+
+  // Grammar checkpoint: runs an LLM pass and returns the fresh pending set.
+  // Rate-limited per document server-side (returns the existing set if too soon).
+  // Both passes return the UNIFIED pending set (grammar + voice), so the client
+  // never drops one family's highlights when the other refreshes.
+  checkDoc: (id: string) => req<Suggestion[]>(`/docs/${id}/check`, { method: 'POST' }),
+  // Voice-consistency pass: whole-document, explicit-action, slower. Returns the
+  // unified pending set too. Rate-limited per document server-side.
+  voiceDoc: (id: string) => req<Suggestion[]>(`/docs/${id}/voice`, { method: 'POST' }),
+  // Collocation coach: whole-document, explicit-action pass flagging non-native
+  // word pairings ("do a decision" → "make a decision"). Returns the unified
+  // pending set too. Rate-limited per document server-side.
+  collocationDoc: (id: string) => req<Suggestion[]>(`/docs/${id}/collocation`, { method: 'POST' }),
+  // Mechanics pass: persist the client-detected deterministic fixes as the
+  // 'mechanics' family and return the unified pending set. Not rate-limited (it's
+  // free, local detection); runs alongside the grammar checkpoint.
+  submitMechanics: (id: string, findings: MechanicsFinding[]) =>
+    req<Suggestion[]>(`/docs/${id}/mechanics`, {
+      method: 'POST',
+      body: JSON.stringify({ findings }),
+    }),
+  // Pending suggestions for a doc, loaded when the editor opens it.
+  listSuggestions: (id: string) => req<Suggestion[]>(`/docs/${id}/suggestions`),
+  acceptSuggestion: (id: string) =>
+    req<void>(`/suggestions/${id}/accept`, { method: 'POST' }),
+  dismissSuggestion: (id: string) =>
+    req<void>(`/suggestions/${id}/dismiss`, { method: 'POST' }),
+  // Simplified-Chinese rendering of a suggestion's explanation, for the Ask Petal
+  // opening bubble (the explanation itself stays English in the card body).
+  translateSuggestion: (id: string) =>
+    req<{ translation: string }>(`/suggestions/${id}/translate`, { method: 'POST' }),
+
+  // Version history. listVersions returns metadata only (no bodies); getVersion
+  // loads one full snapshot for preview; snapshotDoc takes an explicit restore
+  // point; restoreVersion copies a snapshot back onto the live doc (capturing a
+  // pre_restore safety copy server-side first) and returns the restored doc.
+  listVersions: (id: string) => req<DocumentVersion[]>(`/docs/${id}/versions`),
+  getVersion: (id: string, vid: string) =>
+    req<DocumentVersion>(`/docs/${id}/versions/${vid}`),
+  snapshotDoc: (id: string) =>
+    req<DocumentVersion>(`/docs/${id}/versions`, { method: 'POST' }),
+  restoreVersion: (id: string, vid: string) =>
+    req<Document>(`/docs/${id}/versions/${vid}/restore`, { method: 'POST' }),
+
+  // Download URL for an exported document (md/html/txt/docx). Used as an <a
+  // href download> target so the browser handles the file save.
+  exportUrl: (id: string, format: ExportFormat) =>
+    `/api/docs/${id}/export?format=${format}`,
+
+  // Download URL for a whole-corpus backup: a zip of every document rendered in
+  // the given format. A one-click "download all my writing" safety net.
+  exportAllUrl: (format: ExportFormat) => `/api/docs/export-all?format=${format}`,
+
+  // Offline word lookup (gloss + definition + synonyms) for the right-click popover.
+  lookupWord: (word: string) => req<WordInfo>(`/word/${encodeURIComponent(word)}`),
+  // Lightweight Chinese-only gloss for the inline hover/select tooltip — instant
+  // and offline, so it fires on hover without spinning up the heavier lookup.
+  glossWord: (word: string) => req<Gloss>(`/gloss/${encodeURIComponent(word)}`),
+  // Tone-rewrite: rewrites a selected passage in the given style ('natural',
+  // 'academic', …) and returns the rewritten text for an in-editor preview. Not
+  // persisted — the editor applies it directly on accept.
+  rewriteSelection: (docId: string, text: string, style: string) =>
+    req<{ rewrite: string }>(`/docs/${docId}/rewrite`, {
+      method: 'POST',
+      body: JSON.stringify({ text, style }),
+    }),
+
+  // Cross-document full-text search (title + body). Returns hits with a
+  // highlighted snippet. Empty query returns []. Encodes the term for the URL.
+  search: (q: string) => req<SearchResult[]>(`/search?q=${encodeURIComponent(q)}`),
+
+  // Image upload: posts a single image file as multipart form data and returns
+  // its served URL (e.g. /api/images/<hash>.png). Stored on disk by the binary,
+  // so the document JSON keeps a small URL reference instead of inlined base64.
+  // Doesn't go through req() because the body is FormData, not JSON.
+  uploadImage: async (file: File): Promise<{ url: string }> => {
+    const form = new FormData()
+    form.append('image', file)
+    const res = await fetch('/api/images', { method: 'POST', body: form })
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '')
+      throw new Error(`${res.status} ${res.statusText}${detail ? `: ${detail}` : ''}`)
+    }
+    return res.json() as Promise<{ url: string }>
+  },
+
+  // Tags. listTags returns the roster with per-tag document counts; createTag is
+  // idempotent on name (returns the existing tag if it already exists);
+  // updateTag recolors/renames; deleteTag removes it (assignments cascade).
+  // assignTag/unassignTag link a tag to one document.
+  listTags: () => req<Tag[]>('/tags'),
+  createTag: (name: string, color: TagColor) =>
+    req<Tag>('/tags', { method: 'POST', body: JSON.stringify({ name, color }) }),
+  updateTag: (id: string, patch: { name?: string; color?: TagColor }) =>
+    req<Tag>(`/tags/${id}`, { method: 'PATCH', body: JSON.stringify(patch) }),
+  deleteTag: (id: string) => req<void>(`/tags/${id}`, { method: 'DELETE' }),
+  assignTag: (docId: string, tagId: string) =>
+    req<void>(`/docs/${docId}/tags`, { method: 'POST', body: JSON.stringify({ tag_id: tagId }) }),
+  unassignTag: (docId: string, tagId: string) =>
+    req<void>(`/docs/${docId}/tags/${tagId}`, { method: 'DELETE' }),
+
+  // Vocabulary garden. recordVocab captures (or refreshes) a looked-up word —
+  // idempotent per word, fired automatically on lookup. listVocab is the whole
+  // garden; dueVocab is just the cards ready for review; reviewVocab grades one
+  // card and returns its rescheduled state; deleteVocab removes a word.
+  recordVocab: (body: {
+    word: string
+    gloss?: string
+    definition?: string
+    phonetic?: string
+    example?: string
+    doc_id?: string | null
+  }) => req<VocabWord>('/vocab', { method: 'POST', body: JSON.stringify(body) }),
+  listVocab: () => req<VocabWord[]>('/vocab'),
+  dueVocab: () => req<VocabWord[]>('/vocab/due'),
+  reviewVocab: (id: string, grade: VocabGrade) =>
+    req<VocabWord>(`/vocab/${id}/review`, { method: 'POST', body: JSON.stringify({ grade }) }),
+  deleteVocab: (id: string) => req<void>(`/vocab/${id}`, { method: 'DELETE' }),
+
+  // Current deployed build id — changes whenever a new frontend ships. The
+  // app polls this to offer a refresh. Bypasses any cache so the answer is live.
+  version: () => req<{ version: string }>('/version', { cache: 'no-store' }),
+}
+
+// The sentinel characters the server wraps a search match in (\x01 … \x02). Used
+// by splitSnippet to render the matched span highlighted.
+export const SNIPPET_HL_START = String.fromCharCode(1)
+export const SNIPPET_HL_END = String.fromCharCode(2)
+
+// splitSnippet breaks a server snippet into ordered { text, hit } segments so the
+// UI can bold the matched span(s) without dangerously setting innerHTML.
+export function splitSnippet(snippet: string): { text: string; hit: boolean }[] {
+  const out: { text: string; hit: boolean }[] = []
+  let rest = snippet
+  for (;;) {
+    const start = rest.indexOf(SNIPPET_HL_START)
+    if (start < 0) {
+      if (rest) out.push({ text: rest, hit: false })
+      break
+    }
+    if (start > 0) out.push({ text: rest.slice(0, start), hit: false })
+    const end = rest.indexOf(SNIPPET_HL_END, start + 1)
+    if (end < 0) {
+      // Unterminated (shouldn't happen) — emit the remainder plainly.
+      out.push({ text: rest.slice(start + 1), hit: false })
+      break
+    }
+    out.push({ text: rest.slice(start + 1, end), hit: true })
+    rest = rest.slice(end + 1)
+  }
+  return out
+}
+
+// tagColorVar maps a tag color key to its CSS custom property. Unknown keys fall
+// back to the rose accent, matching the backend's coercion.
+export function tagColorVar(color: TagColor | string): string {
+  switch (color) {
+    case 'mint':
+      return 'var(--color-mint)'
+    case 'peach':
+      return 'var(--color-peach)'
+    case 'lavender':
+      return 'var(--color-lavender)'
+    case 'sky':
+      return 'var(--color-sky)'
+    case 'honey':
+      return 'var(--color-honey)'
+    default:
+      return 'var(--color-accent)'
+  }
+}
+
+// One turn in an Ask Petal conversation. History lives only in the component —
+// the server is stateless and re-injects the suggestion context every request.
+export interface ChatMessage {
+  role: 'user' | 'assistant'
+  content: string
+}
+
+// streamSuggestionChat POSTs the conversation to the SSE chat endpoint and
+// invokes onToken for each text chunk as it arrives. It uses fetch + a
+// ReadableStream reader (not EventSource, which can't POST) and resolves when
+// the stream ends. Abort via the optional signal to cancel mid-response.
+export async function streamSuggestionChat(
+  suggestionId: string,
+  messages: ChatMessage[],
+  onToken: (text: string) => void,
+  signal?: AbortSignal,
+): Promise<void> {
+  const res = await fetch(`/api/suggestions/${suggestionId}/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ messages }),
+    signal,
+  })
+  if (!res.ok || !res.body) {
+    const detail = await res.text().catch(() => '')
+    throw new Error(`${res.status} ${res.statusText}${detail ? `: ${detail}` : ''}`)
+  }
+
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let buf = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buf += decoder.decode(value, { stream: true })
+    // SSE events are separated by a blank line. Process every complete one and
+    // keep the trailing partial in the buffer.
+    let sep: number
+    while ((sep = buf.indexOf('\n\n')) >= 0) {
+      const event = parseSSE(buf.slice(0, sep))
+      buf = buf.slice(sep + 2)
+      if (event.name === 'done') return
+      if (event.name === 'token' && event.data) {
+        const text = (JSON.parse(event.data) as { text: string }).text
+        if (text) onToken(text)
+      }
+    }
+  }
+}
+
+// parseSSE pulls the event name and data payload out of one raw SSE frame.
+function parseSSE(frame: string): { name: string; data: string } {
+  let name = 'message'
+  const dataLines: string[] = []
+  for (const line of frame.split('\n')) {
+    if (line.startsWith('event:')) name = line.slice(6).trim()
+    else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim())
+  }
+  return { name, data: dataLines.join('\n') }
+}

web/src/audio/sounds.ts

@@ -0,0 +1,194 @@
+// Petal's cute sound palette. These are hand-picked mp3 effects (warm bubble
+// pops, a wooden "tok", rolling baoding balls, a Chinese fanfare for milestones,
+// and a playful "haiya" for errors) living as assets in ./assets/sounds. Vite
+// fingerprints and bundles them into dist, so they ride along inside the single
+// Go binary; here we just fetch + decode them once and play them through a Web
+// Audio bus with a soft master volume. The whole thing is opt-out-able and the
+// mute choice persists in localStorage so it survives reloads.
+
+import pop1Url from '../assets/sounds/pop1.mp3'
+import pop2Url from '../assets/sounds/pop2.mp3'
+import tokUrl from '../assets/sounds/tok.mp3'
+import blockUrl from '../assets/sounds/block.mp3'
+import baodingUrl from '../assets/sounds/baoding.mp3'
+import milestoneUrl from '../assets/sounds/milestone.mp3'
+import errorUrl from '../assets/sounds/error.mp3'
+
+const STORAGE_KEY = 'petal.sound'
+
+// Master volume — deliberately gentle. These are background delights, not alerts.
+const MASTER_GAIN = 0.5
+
+export type SoundName =
+  | 'pop1' // a soft bubble pop
+  | 'pop2' // a second bubble pop, slightly different
+  | 'tok' // a light wooden "tok"
+  | 'block' // a quick Chinese wood-block tap
+  | 'baoding' // rolling baoding-ball shimmer
+  | 'milestone' // a happy Chinese fanfare (word-count milestones)
+  | 'error' // a playful "haiya" — something went wrong
+
+const SOURCES: Record<SoundName, string> = {
+  pop1: pop1Url,
+  pop2: pop2Url,
+  tok: tokUrl,
+  block: blockUrl,
+  baoding: baodingUrl,
+  milestone: milestoneUrl,
+  error: errorUrl,
+}
+
+// The pool of light "something happened" notification sounds. We rotate through
+// these (skipping the one just played) so the same blip never repeats back to
+// back — a batch of suggestions or a run of tips stays lively instead of
+// hammering one note. milestone/error are deliberately NOT in the pool: they're
+// reserved for their specific moments.
+const POP_POOL: SoundName[] = ['pop1', 'pop2', 'tok', 'block', 'baoding']
+let lastPop = -1
+
+let ctx: AudioContext | null = null
+let master: GainNode | null = null
+const buffers = new Map<SoundName, AudioBuffer>()
+let enabled = readEnabled()
+const listeners = new Set<(on: boolean) => void>()
+
+function readEnabled(): boolean {
+  try {
+    return localStorage.getItem(STORAGE_KEY) !== 'off'
+  } catch {
+    return true
+  }
+}
+
+export function isSoundEnabled(): boolean {
+  return enabled
+}
+
+export function setSoundEnabled(on: boolean): void {
+  enabled = on
+  try {
+    localStorage.setItem(STORAGE_KEY, on ? 'on' : 'off')
+  } catch {
+    /* private mode — choice just won't persist */
+  }
+  listeners.forEach((fn) => fn(on))
+  // Touching the context on enable doubles as a user-gesture unlock + warm-up.
+  if (on) void ensureContext()
+}
+
+export function onSoundEnabledChange(fn: (on: boolean) => void): () => void {
+  listeners.add(fn)
+  return () => listeners.delete(fn)
+}
+
+// Lazily create the AudioContext (browsers require a user gesture before audio
+// can play; the first play() after a click will succeed, earlier ones resume).
+async function ensureContext(): Promise<AudioContext | null> {
+  if (typeof window === 'undefined') return null
+  const AC: typeof AudioContext | undefined =
+    window.AudioContext ??
+    (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
+  if (!AC) return null
+  if (!ctx) {
+    ctx = new AC()
+    master = ctx.createGain()
+    master.gain.value = MASTER_GAIN
+    // A gentle soft-clip so stacked sounds never crackle.
+    const shaper = ctx.createWaveShaper()
+    shaper.curve = softClipCurve()
+    master.connect(shaper)
+    shaper.connect(ctx.destination)
+  }
+  if (ctx.state === 'suspended') {
+    try {
+      await ctx.resume()
+    } catch {
+      /* will retry on the next gesture */
+    }
+  }
+  return ctx
+}
+
+function softClipCurve(): Float32Array<ArrayBuffer> {
+  const n = 1024
+  const curve = new Float32Array(new ArrayBuffer(n * 4))
+  for (let i = 0; i < n; i++) {
+    const x = (i / (n - 1)) * 2 - 1
+    curve[i] = Math.tanh(x * 1.2)
+  }
+  return curve
+}
+
+// Fetch + decode one sound, caching the decoded buffer for instant replay.
+async function load(name: SoundName, audio: AudioContext): Promise<AudioBuffer | null> {
+  const cached = buffers.get(name)
+  if (cached) return cached
+  try {
+    const res = await fetch(SOURCES[name])
+    const bytes = await res.arrayBuffer()
+    const buf = await audio.decodeAudioData(bytes)
+    buffers.set(name, buf)
+    return buf
+  } catch {
+    return null // asset missing / decode failed — sound just won't play
+  }
+}
+
+// Warm the cache so the first real play is instant.
+async function prime(): Promise<void> {
+  const audio = await ensureContext()
+  if (!audio) return
+  await Promise.all((Object.keys(SOURCES) as SoundName[]).map((n) => load(n, audio)))
+}
+
+// Fire a sound. No-op when muted or audio is unavailable. Never throws — a
+// delight that fails should fail silently.
+export function playSound(name: SoundName): void {
+  if (!enabled) return
+  void (async () => {
+    const audio = await ensureContext()
+    if (!audio || !master || audio.state !== 'running') return
+    const buf = await load(name, audio)
+    if (!buf) return
+    try {
+      const src = audio.createBufferSource()
+      src.buffer = buf
+      src.connect(master)
+      src.start()
+    } catch {
+      /* audio glitch — ignore */
+    }
+  })()
+}
+
+// Play the next notification pop from the pool, never repeating the last one, so
+// consecutive blips always sound different. This is the everyday "something
+// arrived" voice for suggestions, tips, and gentle cheers.
+export function playPop(): void {
+  let i = lastPop
+  // Tiny pool, so a short scan to pick anything but the last is plenty.
+  for (let tries = 0; tries < POP_POOL.length && i === lastPop; tries++) {
+    i = Math.floor(Math.random() * POP_POOL.length)
+  }
+  lastPop = i
+  playSound(POP_POOL[i])
+}
+
+// Each freshly-surfaced suggestion just gets a rotating pop — the variety comes
+// from the pool, not from the suggestion type, so a batch of same-type fixes
+// still sounds lively.
+export function playSuggestionSound(_type: string): void {
+  playPop()
+}
+
+// Unlock + warm audio on the first user gesture so the very first sound isn't
+// dropped by the browser's autoplay policy. Self-removing.
+if (typeof window !== 'undefined') {
+  const unlock = () => {
+    void prime()
+    window.removeEventListener('pointerdown', unlock)
+    window.removeEventListener('keydown', unlock)
+  }
+  window.addEventListener('pointerdown', unlock)
+  window.addEventListener('keydown', unlock)
+}

web/src/audio/speech.ts

@@ -0,0 +1,120 @@
+// Read-aloud for an ESL writer: hear how an English word or passage sounds.
+//
+// Primary path is server-side neural TTS (Piper, proxied at /api/tts) — natural,
+// consistent across devices, and far better than the browser's built-in voices
+// (which fall back to robotic espeak on Chromium). If the server route is absent
+// (TTS disabled) or unreachable, we fall back to the browser's Web Speech API so
+// the buttons still do something. No model or network is strictly required.
+
+// speechSupported reports whether read-aloud can do anything at all. Audio
+// playback is universal, so as long as we can construct an Audio element OR the
+// Web Speech API exists, the buttons should show. The server path is tried at
+// call time and degrades on its own.
+export function speechSupported(): boolean {
+  if (typeof window === 'undefined') return false
+  return typeof window.Audio === 'function' || 'speechSynthesis' in window
+}
+
+// webSpeechSupported gates the fallback path specifically.
+function webSpeechSupported(): boolean {
+  return typeof window !== 'undefined' && 'speechSynthesis' in window && 'SpeechSynthesisUtterance' in window
+}
+
+// current holds the in-flight server-audio element and its object URL so a rapid
+// re-tap can stop and replace it (mirroring speechSynthesis.cancel()).
+let current: { audio: HTMLAudioElement; url: string } | null = null
+
+// requestSeq increments on every speak() call so a slow fetch that resolves after
+// a newer tap can detect it's stale and bow out instead of double-playing.
+let requestSeq = 0
+
+// stopSpeech halts any read-aloud in flight — both the server-audio element and
+// the Web Speech fallback — and bumps requestSeq so a fetch still in flight bows
+// out instead of playing late. Exported so a panel can cancel audio on unmount,
+// keeping a word's pronunciation from outliving the panel that started it.
+export function stopSpeech(): void {
+  requestSeq++
+  if (current) {
+    current.audio.pause()
+    URL.revokeObjectURL(current.url)
+    current = null
+  }
+  if (webSpeechSupported()) window.speechSynthesis.cancel()
+}
+
+// pickVoice prefers an exact locale match (e.g. en-US), then any voice in the
+// same language family (en-*). Returns undefined to let the engine default.
+function pickVoice(lang: string): SpeechSynthesisVoice | undefined {
+  const voices = window.speechSynthesis.getVoices()
+  const base = lang.split('-')[0]
+  return voices.find((v) => v.lang === lang) || voices.find((v) => v.lang?.startsWith(base))
+}
+
+// speakWebSpeech is the fallback: the browser's built-in synthesizer. A touch
+// slower than default so learners can follow along.
+function speakWebSpeech(text: string, lang: string): void {
+  if (!webSpeechSupported()) return
+  const synth = window.speechSynthesis
+  synth.cancel()
+  const utterance = new SpeechSynthesisUtterance(text)
+  utterance.lang = lang
+  const voice = pickVoice(lang)
+  if (voice) utterance.voice = voice
+  utterance.rate = 0.95
+  synth.speak(utterance)
+}
+
+// detectLang guesses a BCP-47 locale from the text so the right Piper voice is
+// chosen. Any Han/kana character routes to Chinese (zh-CN) — a selection is
+// essentially never mixed at the level that matters, and reading a Chinese
+// passage with the English voice spells each character out ("Chinese letter…").
+// Everything else defaults to US English, the language she's learning.
+const CJK = /[぀-ヿ㐀-䶿一-鿿豈-﫿ｦ-ﾟ]/
+export function detectLang(text: string): string {
+  return CJK.test(text) ? 'zh-CN' : 'en-US'
+}
+
+// speak reads `text` aloud, cancelling anything already in flight so rapid taps
+// don't queue up. `lang` defaults to a guess from the text (Chinese vs English)
+// so callers can just pass the selection; pass an explicit locale to override.
+// It tries the server's neural voice first and silently falls back to the browser
+// voice if that's unavailable (route off, network error, or a 404 for a language
+// with no configured voice).
+export function speak(text: string, lang = detectLang(text)): void {
+  if (!text.trim()) return
+  stopSpeech()
+  const seq = ++requestSeq
+
+  fetch('/api/tts', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text, lang }),
+  })
+    .then((res) => {
+      if (!res.ok) throw new Error(`tts ${res.status}`)
+      return res.blob()
+    })
+    .then((blob) => {
+      // A newer tap superseded this one while the fetch was in flight — drop it.
+      if (seq !== requestSeq) return
+      const url = URL.createObjectURL(blob)
+      const audio = new Audio(url)
+      current = { audio, url }
+      // Release the blob once playback finishes (or errors) to avoid leaking.
+      const cleanup = () => {
+        if (current?.audio === audio) {
+          URL.revokeObjectURL(url)
+          current = null
+        }
+      }
+      audio.addEventListener('ended', cleanup)
+      audio.addEventListener('error', cleanup)
+      return audio.play()
+    })
+    .catch(() => {
+      // Server TTS unavailable for this request — use the browser voice instead,
+      // unless a newer tap has already superseded this one.
+      if (seq !== requestSeq) return
+      speakWebSpeech(text, lang)
+    })
+}

web/src/components/Companion/LottiePlayer.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from 'react'
+// Light build: drops the eval-based expression engine (smaller bundle, no eval
+// warning). Plenty for a looping mascot; swap to 'lottie-web' only if an asset
+// genuinely needs After Effects expressions.
+import lottie, { type AnimationItem } from 'lottie-web/build/player/lottie_light'
+
+interface Props {
+  // Parsed Lottie JSON (imported, so it bundles offline). When undefined the
+  // `fallback` is rendered instead — letting the companion ship before any
+  // animation asset exists.
+  animationData?: object
+  loop?: boolean
+  className?: string
+  // Mirror the animation left↔right (for assets drawn facing the wrong way).
+  flip?: boolean
+  fallback: React.ReactNode
+}
+
+// Tighten the SVG viewBox to the animation's actual drawn content so an asset
+// with a lot of empty artboard padding (common with stock Lottie files) fills
+// the badge instead of floating tiny in the middle. We union the content bbox
+// across a few frames (the mascot moves) and make it square so it isn't
+// distorted by the square container.
+function fitToContent(anim: AnimationItem, svg: SVGSVGElement) {
+  try {
+    const frames = anim.getDuration(true)
+    let x1 = Infinity, y1 = Infinity, x2 = -Infinity, y2 = -Infinity
+    const SAMPLES = 6
+    for (let i = 0; i < SAMPLES; i++) {
+      anim.goToAndStop(Math.floor(((frames - 1) * i) / (SAMPLES - 1)), true)
+      const b = svg.getBBox()
+      if (b.width === 0 || b.height === 0) continue
+      x1 = Math.min(x1, b.x)
+      y1 = Math.min(y1, b.y)
+      x2 = Math.max(x2, b.x + b.width)
+      y2 = Math.max(y2, b.y + b.height)
+    }
+    if (!isFinite(x1)) return
+    const cx = (x1 + x2) / 2, cy = (y1 + y2) / 2
+    const side = Math.max(x2 - x1, y2 - y1) * 1.14 // ~7% breathing room each side
+    svg.setAttribute('viewBox', `${cx - side / 2} ${cy - side / 2} ${side} ${side}`)
+    svg.setAttribute('preserveAspectRatio', 'xMidYMid meet')
+  } catch {
+    /* getBBox unsupported / not laid out — leave the original viewBox */
+  } finally {
+    anim.goToAndPlay(0, true)
+  }
+}
+
+// A thin wrapper over lottie-web (framework-agnostic, no React peer deps, fully
+// offline). Reloads the animation whenever the data changes — moods swap by
+// passing a different `animationData`.
+export function LottiePlayer({ animationData, loop = true, className, flip, fallback }: Props) {
+  const ref = useRef<HTMLDivElement>(null)
+  const anim = useRef<AnimationItem | null>(null)
+
+  useEffect(() => {
+    const container = ref.current
+    if (!container || !animationData) return
+    const item = lottie.loadAnimation({
+      container,
+      renderer: 'svg',
+      loop,
+      autoplay: true,
+      animationData,
+    })
+    anim.current = item
+    item.addEventListener('DOMLoaded', () => {
+      const svg = container.querySelector('svg')
+      if (svg) fitToContent(item, svg as SVGSVGElement)
+    })
+    return () => {
+      item.destroy()
+      anim.current = null
+    }
+  }, [animationData, loop])
+
+  if (!animationData) return <>{fallback}</>
+  return (
+    <div
+      ref={ref}
+      className={className}
+      style={flip ? { transform: 'scaleX(-1)' } : undefined}
+      aria-hidden
+    />
+  )
+}

web/src/components/Companion/PetalCompanion.tsx

@@ -0,0 +1,215 @@
+import { useEffect, useRef, useState } from 'react'
+import type { SaveStatus } from '../../hooks/useAutoSave'
+import { useCompanion, type Mood } from './useCompanion'
+import { LottiePlayer } from './LottiePlayer'
+import { COMPANIONS, DEFAULT_COMPANION } from './companions'
+
+interface Props {
+  wordCount: number
+  saveStatus: SaveStatus
+  llmDown: boolean
+  editTick: number
+  acceptTick: number
+  text: string
+}
+
+// Emoji placeholder per mood, used for any mood a companion has no Lottie for.
+const MOOD_EMOJI: Record<Mood, string> = {
+  idle: '🐾',
+  happy: '😺',
+  talking: '😸',
+  celebrate: '😻',
+  sleeping: '🐾',
+}
+
+const STORAGE_KEY = 'petal.companion'
+
+// PetalCompanion is the cozy corner mascot: it watches the writing session via
+// useCompanion and shows a Mandarin-first speech bubble for cheers, tips, and
+// break reminders. Clicking the mascot opens a picker to switch companions
+// (the choice persists in localStorage).
+export function PetalCompanion({ wordCount, saveStatus, llmDown, editTick, acceptTick, text }: Props) {
+  const { mood, bubble, dismiss, holdBubble, releaseBubble } = useCompanion({
+    wordCount,
+    saveStatus,
+    llmDown,
+    editTick,
+    acceptTick,
+    text,
+  })
+
+  const [companionId, setCompanionId] = useState<string>(() => {
+    try {
+      return localStorage.getItem(STORAGE_KEY) || DEFAULT_COMPANION
+    } catch {
+      return DEFAULT_COMPANION
+    }
+  })
+  const companion = COMPANIONS.find((c) => c.id === companionId) ?? COMPANIONS[0]
+  const [pickerOpen, setPickerOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // Awake companions (no sleeping clip) don't visibly nap — when the engine
+  // dozes them, keep their normal idle pose instead of a sleepy face. Only a
+  // mascot with a real sleep animation (the always-asleep cat) shows the zzz.
+  const hasSleepClip = Boolean(companion.animations.sleeping)
+  // An always-asleep mascot (the cat) stays pinned to one pose so its Lottie
+  // never reloads as the engine flips moods underneath it.
+  const renderMood: Mood = companion.alwaysAsleep
+    ? 'idle'
+    : mood === 'sleeping' && !hasSleepClip
+      ? 'idle'
+      : mood
+  const napping = companion.alwaysAsleep || (mood === 'sleeping' && hasSleepClip)
+
+  // Never swap the cute companion for a bare emoji on an idle nap: fall back to
+  // the idle animation when a mood has no clip of its own, and only reach for
+  // the emoji if the companion ships no animations at all.
+  const animationData = companion.animations[renderMood] ?? companion.animations.idle
+
+  function choose(id: string) {
+    setCompanionId(id)
+    try {
+      localStorage.setItem(STORAGE_KEY, id)
+    } catch {
+      /* private mode / storage disabled — selection just won't persist */
+    }
+    setPickerOpen(false)
+  }
+
+  // Click outside the corner closes the picker.
+  useEffect(() => {
+    if (!pickerOpen) return
+    const onDown = (e: MouseEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setPickerOpen(false)
+    }
+    document.addEventListener('mousedown', onDown)
+    return () => document.removeEventListener('mousedown', onDown)
+  }, [pickerOpen])
+
+  return (
+    <div
+      ref={rootRef}
+      className="pointer-events-none fixed bottom-4 right-4 z-40 flex flex-col items-end gap-2"
+    >
+      {pickerOpen && (
+        <div
+          className="petal-bubble pointer-events-auto flex flex-col gap-0.5 p-1.5"
+          style={{
+            background: 'var(--color-surface)',
+            border: '1px solid var(--color-border)',
+            borderRadius: 'var(--radius-card)',
+            boxShadow: 'var(--shadow-soft)',
+            fontFamily: 'var(--font-ui)',
+            minWidth: 180,
+          }}
+        >
+          <p
+            className="px-2 pb-1 pt-0.5 text-[0.7rem] font-bold"
+            style={{ color: 'var(--color-muted)' }}
+          >
+            选个小伙伴 · Choose a companion
+          </p>
+          {COMPANIONS.map((c) => {
+            const active = c.id === companion.id
+            return (
+              <button
+                key={c.id}
+                type="button"
+                onClick={() => choose(c.id)}
+                className="flex items-center gap-2.5 rounded-xl px-2 py-1.5 text-left text-sm transition-colors"
+                style={{
+                  background: active ? 'var(--color-surface-alt)' : 'transparent',
+                  color: 'var(--color-plum)',
+                }}
+                onMouseEnter={(e) => {
+                  if (!active) e.currentTarget.style.background = 'var(--color-surface-alt)'
+                }}
+                onMouseLeave={(e) => {
+                  if (!active) e.currentTarget.style.background = 'transparent'
+                }}
+              >
+                <span style={{ fontSize: 20, lineHeight: 1 }}>{c.emoji}</span>
+                <span className="flex-1">
+                  <span className="font-bold">{c.zh}</span>{' '}
+                  <span style={{ color: 'var(--color-muted)' }}>{c.name}</span>
+                </span>
+                {active && <span style={{ color: 'var(--color-accent)' }}>✓</span>}
+              </button>
+            )
+          })}
+        </div>
+      )}
+
+      {bubble && !pickerOpen && (
+        <div
+          role="status"
+          onClick={dismiss}
+          onMouseEnter={holdBubble}
+          onMouseLeave={releaseBubble}
+          className="petal-bubble pointer-events-auto max-w-[420px] cursor-pointer p-4 pr-5"
+          style={{
+            background: 'var(--color-surface)',
+            border: '1px solid var(--color-border)',
+            borderRadius: 'var(--radius-card)',
+            boxShadow: 'var(--shadow-soft)',
+            // CJK-first font stack (north star Note #17) — she reads Mandarin.
+            fontFamily: 'var(--font-ui)',
+          }}
+          title="Click to dismiss"
+        >
+          <p
+            className="font-bold leading-snug"
+            style={{ color: 'var(--color-plum)', fontSize: '1.4rem' }}
+          >
+            {bubble.zh}
+          </p>
+          <p
+            className="mt-0.5 leading-snug"
+            style={{ color: 'var(--color-muted)', fontSize: '1.15rem' }}
+          >
+            {bubble.en}
+          </p>
+        </div>
+      )}
+
+      <button
+        type="button"
+        onClick={() => setPickerOpen((o) => !o)}
+        title="Choose a companion"
+        aria-label="Choose a companion"
+        className={`petal-companion pointer-events-auto select-none ${napping ? 'petal-companion-sleep' : ''}`}
+        style={{
+          // Size scales with the viewport — see --petal-companion-size in index.css.
+          width: 'var(--petal-companion-size)',
+          height: 'var(--petal-companion-size)',
+          padding: 0,
+          borderRadius: 'var(--radius-pill)',
+          background: 'var(--color-surface-alt)',
+          border: '1px solid var(--color-border)',
+          boxShadow: 'var(--shadow-soft)',
+          display: 'grid',
+          placeItems: 'center',
+          position: 'relative',
+        }}
+      >
+        <LottiePlayer
+          key={companion.id}
+          animationData={animationData}
+          flip={companion.flip}
+          className="petal-companion-art"
+          fallback={
+            <span style={{ fontSize: 'calc(var(--petal-companion-size) * 0.5)', lineHeight: 1 }}>
+              {MOOD_EMOJI[renderMood]}
+            </span>
+          }
+        />
+        {napping && (
+          <span className="petal-zzz absolute" aria-hidden style={{ color: 'var(--color-muted)' }}>
+            z
+          </span>
+        )}
+      </button>
+    </div>
+  )
+}

web/src/components/Companion/companions.ts

@@ -0,0 +1,92 @@
+import type { Mood } from './useCompanion'
+import sleepingCat from './animations/sleeping-cat.json'
+import happyDog from './animations/happy-dog.json'
+import wiggleDog from './animations/wiggle-dog.json'
+import butterfly from './animations/butterfly.json'
+import parrot from './animations/parrot.json'
+
+export interface Companion {
+  id: string
+  name: string // English label
+  zh: string // Chinese label (she reads Mandarin — north star Note #17)
+  emoji: string // shown in the picker + used as the per-mood fallback base
+  // mood → Lottie asset. Unmapped moods fall back to the per-mood emoji.
+  animations: Partial<Record<Mood, object>>
+  // When true the mascot keeps its calm sway + drifting zzz regardless of mood
+  // (e.g. a cat that's always asleep but still talks in its sleep).
+  alwaysAsleep?: boolean
+  // When true the rendered animation is mirrored left↔right — for assets drawn
+  // facing the "wrong" way for our bottom-right corner (e.g. the parrot).
+  flip?: boolean
+}
+
+// The roster. Add a companion by dropping a pure-vector Lottie JSON into
+// ./animations and appending an entry here — that's the whole change.
+export const COMPANIONS: Companion[] = [
+  {
+    id: 'cat',
+    name: 'Sleepy Cat',
+    zh: '瞌睡猫',
+    emoji: '😴',
+    alwaysAsleep: true,
+    animations: {
+      idle: sleepingCat,
+      happy: sleepingCat,
+      talking: sleepingCat,
+      celebrate: sleepingCat,
+      sleeping: sleepingCat,
+    },
+  },
+  {
+    id: 'dog',
+    name: 'Happy Dog',
+    zh: '开心狗',
+    emoji: '🐶',
+    animations: {
+      idle: happyDog,
+      happy: happyDog,
+      talking: happyDog,
+      celebrate: happyDog,
+      // no sleeping clip → stays in its idle pose instead of visibly napping
+    },
+  },
+  {
+    id: 'wiggle-dog',
+    name: 'Wiggle Dog',
+    zh: '摇尾狗',
+    emoji: '🐕',
+    animations: {
+      idle: wiggleDog,
+      happy: wiggleDog,
+      talking: wiggleDog,
+      celebrate: wiggleDog,
+    },
+  },
+  {
+    id: 'butterfly',
+    name: 'Butterfly',
+    zh: '蝴蝶',
+    emoji: '🦋',
+    animations: {
+      idle: butterfly,
+      happy: butterfly,
+      talking: butterfly,
+      celebrate: butterfly,
+    },
+  },
+  {
+    id: 'parrot',
+    name: 'Parrot',
+    zh: '鹦鹉',
+    emoji: '🦜',
+    flip: true, // asset faces left; mirror it to face into the page
+    animations: {
+      idle: parrot,
+      happy: parrot,
+      talking: parrot,
+      celebrate: parrot,
+    },
+  },
+]
+
+export const DEFAULT_COMPANION = 'cat'

web/src/components/Companion/prose.test.ts

@@ -0,0 +1,366 @@
+import { describe, it, expect } from 'vitest'
+import { analyzeProse } from './prose'
+
+// These tests pin the rules-based prose checker's behavior. For an ESL writer a
+// *wrong* nudge costs trust faster than a missed one earns it, so every rule is
+// tested in two directions: a true-positive case that must fire, and at least
+// one near-miss "guard" case that must stay silent. Sentences are padded past
+// the 8-word floor that analyzeProse needs before it offers advice.
+
+const rulesFor = (text: string) => analyzeProse(text).map((h) => h.rule)
+
+// Assert a given rule appears among the hints for this text.
+function expectRule(text: string, rule: string) {
+  expect(rulesFor(text), `expected "${rule}" for: ${text}`).toContain(rule)
+}
+
+// Assert the text produces no hints at all (false-positive guard).
+function expectClean(text: string) {
+  expect(analyzeProse(text), `expected no hints for: ${text}`).toEqual([])
+}
+
+describe('analyzeProse — floor', () => {
+  it('stays quiet on very short drafts (under 8 English words)', () => {
+    expect(analyzeProse('he go now')).toEqual([])
+  })
+
+  it('returns hints highest-priority first', () => {
+    // This 36-word run-on also contains a lowercase "i"; run-on must lead.
+    const hints = analyzeProse(
+      'yesterday i walked all the way to the market and i bought apples and oranges and i saw my friend there and we talked and laughed and walked back home together in the warm afternoon sun.',
+    )
+    expect(hints[0].rule).toBe('runon')
+    expect(hints.map((h) => h.rule)).toContain('cap-i')
+  })
+})
+
+describe('run-ons', () => {
+  it('flags a long, comma-heavy sentence', () => {
+    expectRule(
+      'I went to the market and I bought some apples and then I saw my friend and we talked for a while and after that we went to the cafe and ordered coffee and cake together.',
+      'runon',
+    )
+  })
+
+  it('leaves a normal sentence alone', () => {
+    expectClean('The garden was quiet in the morning and the rain fell softly on the leaves.')
+  })
+})
+
+describe('comma splices', () => {
+  it('flags two independent clauses joined by a comma', () => {
+    expectRule('I finished the report, I sent it to my boss right away today.', 'splice')
+  })
+
+  it('catches a splice with a verb not on any list', () => {
+    expectRule('The garden was quiet in the morning, she poured a cup of tea slowly.', 'splice')
+  })
+
+  it('does not flag an introductory transition (However, …)', () => {
+    expectClean('However, we decided to stay home and rest for the entire weekend.')
+  })
+
+  it('does not flag an introductory phrase (After dinner, …)', () => {
+    expectClean('After dinner, I went home and read a book until I fell asleep.')
+  })
+
+  it('does not flag a pronoun list after a comma', () => {
+    expectClean('We invited my brother, you and your sister to the dinner party.')
+  })
+})
+
+describe('unclear antecedents', () => {
+  it('flags a vague "This + verb" opener after a prior sentence', () => {
+    expectRule(
+      'We changed the whole schedule last week. This makes everyone confused about the new times.',
+      'antecedent',
+    )
+  })
+
+  it('leaves "This" alone when it names its noun', () => {
+    expectClean(
+      'We changed the whole schedule last week. This new schedule confuses everyone about the times.',
+    )
+  })
+})
+
+describe('oxford comma', () => {
+  it('flags a 3-item noun list missing the serial comma', () => {
+    expectRule('My mother, my father and my sister came to visit us last summer.', 'oxford')
+  })
+
+  it('flags a verb-phrase list missing the serial comma', () => {
+    expectRule('We cleaned the kitchen, washed the dishes and took out the trash.', 'oxford')
+  })
+
+  it('does not flag a list that already has the serial comma', () => {
+    expectClean('I bought apples, bananas, and oranges at the store this morning.')
+  })
+
+  it('does not flag a compound predicate as a list', () => {
+    expectClean('After dinner, I went home and read a book until I fell asleep.')
+  })
+})
+
+describe('a / an', () => {
+  it('flags "a" before a vowel sound', () => {
+    expectRule('She found a umbrella and a old book on the table by the window.', 'article')
+  })
+
+  it('flags "an" before a consonant sound', () => {
+    expectRule('He gave me an book and an pencil to use during the long exam.', 'article')
+  })
+
+  it('respects sound exceptions (a university, an hour)', () => {
+    expectClean('He is a university student and it took an hour to arrive here.')
+  })
+})
+
+describe('uncountable plurals', () => {
+  it('flags a pluralized mass noun', () => {
+    expectRule('She gave me many informations about the new job opening today.', 'uncountable')
+  })
+
+  it('leaves the singular mass noun alone', () => {
+    expectClean('He shared some useful advice and helped me with my homework tonight.')
+  })
+})
+
+describe('capitalization of proper nouns', () => {
+  it('flags lowercase languages and days', () => {
+    expectRule('I am learning english and french during my free time every week.', 'propercap')
+    expectRule('We will meet on monday to discuss the final project together soon.', 'propercap')
+  })
+
+  it('does not flag ambiguous homographs (may, march)', () => {
+    expectClean('They may visit in the spring and march through the old town square.')
+  })
+
+  it('leaves already-capitalized proper nouns alone', () => {
+    expectClean('I will study English and Chinese together this coming summer break here.')
+  })
+})
+
+describe('subject–verb agreement', () => {
+  it('flags a bare verb after he/she/it', () => {
+    expectRule('My brother is busy but he go to the gym every single morning.', 'sva')
+    expectRule('She have a lovely garden full of roses behind her small house.', 'sva')
+  })
+
+  it('flags a sentence-initial subject too', () => {
+    expectRule('It make me happy whenever the sun comes out after the rain.', 'sva')
+  })
+
+  it('does not flag causative/perception frames (let it go, make it work)', () => {
+    expectClean('Please let it go and try to enjoy the rest of your day.')
+    expectClean('We should make it work before the big meeting tomorrow afternoon.')
+  })
+})
+
+describe('plural after a number', () => {
+  it('flags a singular noun after a cardinal number', () => {
+    expectRule('I bought three apple and some bread at the market this morning.', 'plural')
+  })
+
+  it('does not flag an adjective between number and noun', () => {
+    expectClean('We adopted two small dogs from the shelter near our apartment today.')
+  })
+
+  it('does not flag irregular plurals (five people)', () => {
+    expectClean('There were five people waiting patiently outside in the cold morning rain.')
+  })
+
+  it('does not flag an already-plural noun', () => {
+    expectClean('She has two cats and they sleep all day long on the couch.')
+  })
+})
+
+describe('double determiner', () => {
+  it('flags a stacked article + possessive', () => {
+    expectRule('Please put the my book back on the shelf when you finish it.', 'doubledet')
+  })
+})
+
+describe('there is + plural', () => {
+  it('flags "there is" with a plural quantifier', () => {
+    expectRule('There is many reasons to visit the coast during the warm months.', 'thereis')
+  })
+
+  it('does not flag "there is some" with a mass noun', () => {
+    expectClean('There is some water left in the bottle if you are thirsty now.')
+  })
+})
+
+describe('its / it’s', () => {
+  it("flags it's used as a possessive", () => {
+    expectRule("The cat licked it's own paw while sitting quietly by the window.", 'its')
+  })
+
+  it('flags its used where "it is" is meant', () => {
+    expectRule('I think its a wonderful idea to travel together next year sometime.', 'its')
+  })
+
+  it('leaves correct possessive "its" alone', () => {
+    expectClean('The dog wagged its tail happily when we came home that evening.')
+  })
+})
+
+describe('than / then', () => {
+  it('flags a comparative followed by "then"', () => {
+    expectRule('This cake tastes much better then the one we made last weekend.', 'than')
+  })
+
+  it('leaves sequential "then" alone', () => {
+    expectClean('We ate dinner and then we watched a long movie on the sofa.')
+  })
+})
+
+describe('comma after a transition', () => {
+  it('flags a sentence-initial transition with no comma', () => {
+    expectRule('However we decided to stay home and rest for the whole weekend.', 'introcomma')
+  })
+
+  it('does not flag a sequence word (Then …)', () => {
+    expectClean('Then we walked to the park and fed the ducks by the pond.')
+  })
+})
+
+describe('spacing around punctuation', () => {
+  it('flags a missing space after a comma', () => {
+    expectRule('I like apples,bananas and grapes from the little shop down the street.', 'space-after')
+  })
+
+  it('flags a space before punctuation', () => {
+    expectRule('She smiled warmly , then walked away without saying a single word today.', 'space-punct')
+  })
+
+  it('does not flag thousands separators in numbers', () => {
+    expectClean('The list had 1,000 items and cost us about 2,500 dollars in total.')
+  })
+})
+
+describe('capitalization basics', () => {
+  it('flags a lowercase standalone "i"', () => {
+    expectRule('Yesterday i walked to the store and bought milk, eggs, and bread.', 'cap-i')
+  })
+
+  it('flags a sentence that does not start with a capital', () => {
+    expectRule('The sun set slowly. it was a beautiful evening down by the river.', 'cap-sentence')
+  })
+})
+
+import { mechanicsFindings } from './prose'
+
+// mechanicsFindings is the applyable subset feeding the suggestion cards. Each
+// finding must carry an EXACT span (text.slice(from,to) === original) and a
+// replacement that actually changes the text — these become one-click edits.
+describe('mechanicsFindings — applyable fixes', () => {
+  // Every finding's span must be exact, regardless of which rule produced it.
+  function expectExactSpans(text: string) {
+    const found = mechanicsFindings(text)
+    for (const f of found) {
+      expect(text.slice(f.from, f.to), `span for ${JSON.stringify(f)}`).toBe(f.original)
+      expect(f.replacement).not.toBe(f.original)
+    }
+    return found
+  }
+
+  const one = (text: string, rulePred: (f: ReturnType<typeof mechanicsFindings>[number]) => boolean) =>
+    expectExactSpans(text).find(rulePred)
+
+  it('doubled word → single word, exact span', () => {
+    const f = one('I saw the the cat in the garden today.', (f) => f.original === 'the the')
+    expect(f?.replacement).toBe('the')
+  })
+
+  it('finds BOTH doublings with distinct spans', () => {
+    const found = mechanicsFindings('the the dog and the the cat ran around the yard.')
+      .filter((f) => f.original === 'the the')
+    expect(found).toHaveLength(2)
+    expect(found[0].from).not.toBe(found[1].from)
+  })
+
+  // Spans are widened to a distinctive phrase so they re-anchor by string in the
+  // editor (a bare "a"/"i"/" is" would match the wrong spot). The replacement
+  // carries the whole corrected phrase.
+
+  it('lowercase standalone i is awareness-only (no card)', () => {
+    // It still flags as a companion bubble (see analyzeProse), but a single
+    // character can't be anchored, so it must NOT become a card.
+    expect(mechanicsFindings('Yesterday i walked to the store and came home.').length).toBe(0)
+    expect(rulesFor('Yesterday i walked to the store and came home.')).toContain('cap-i')
+  })
+
+  it('a → an: spans the whole "a <noun>" phrase', () => {
+    const f = one('She found a umbrella under the old wooden table.', (f) => f.original === 'a umbrella')
+    expect(f?.replacement).toBe('an umbrella')
+  })
+
+  it('uncountable plural → singular', () => {
+    const f = one('She gave me many informations about the new job.', (f) => f.original === 'informations')
+    expect(f?.replacement).toBe('information')
+  })
+
+  it('lowercase proper noun → capitalized', () => {
+    const f = one('I am learning english during my free time this year.', (f) => f.original === 'english')
+    expect(f?.replacement).toBe('English')
+  })
+
+  it('subject-verb agreement → corrects the verb, spans subject+verb', () => {
+    const f = one('She have three cats and a dog at her house.', (f) => f.original === 'She have')
+    expect(f?.replacement).toBe('She has')
+  })
+
+  it('singular noun after a number → plural, spans number+noun', () => {
+    const f = one('I bought five apple at the market this morning.', (f) => f.original === 'five apple')
+    expect(f?.replacement).toBe('five apples')
+  })
+
+  it('comparative + then → than, spans the phrase', () => {
+    const f = one('This book is better then the one I read last week.', (f) => f.original === 'better then')
+    expect(f?.replacement).toBe('better than')
+  })
+
+  it('space before punctuation is removed (spans the word)', () => {
+    const f = one('I love it , it makes me very happy indeed.', (f) => f.original === 'it ,')
+    expect(f?.replacement).toBe('it,')
+  })
+
+  it('missing space after a comma is added (spans both words)', () => {
+    const f = one('I bought apples,bananas and pears at the store.', (f) => f.original === 'apples,bananas')
+    expect(f?.replacement).toBe('apples, bananas')
+  })
+
+  it('stacked determiner drops the article', () => {
+    const f = one('She left the my book on the kitchen table again.', (f) => f.original === 'the my')
+    expect(f?.replacement).toBe('my')
+  })
+
+  it('there is + plural → there are, spans the phrase', () => {
+    const f = one('There is many people waiting outside in the cold.', (f) => f.original === 'There is many')
+    expect(f?.replacement).toBe('There are many')
+  })
+
+  it("it's own → its own, spans the phrase", () => {
+    const f = one("The cat licked it's own paw very slowly today.", (f) => f.original === "it's own")
+    expect(f?.replacement).toBe('its own')
+  })
+
+  it("its a → it's a, spans the phrase", () => {
+    const f = one('I think its a wonderful day to go outside now.', (f) => f.original === 'its a')
+    expect(f?.replacement).toBe("it's a")
+  })
+
+  // Awareness-only rules never produce cards — they stay companion bubbles.
+  it('run-ons and splices produce NO card findings', () => {
+    const runOn = 'I went to the market and I bought some apples and then I saw my friend and we talked for a while and after that we went to the cafe and ordered coffee and cake together.'
+    expect(mechanicsFindings(runOn).some((f) => f.original.length > 30)).toBe(false)
+    const splice = 'I finished the report, I sent it to my boss right away today.'
+    // no card spans the comma-join; only (if any) small word-level fixes
+    expect(mechanicsFindings(splice).every((f) => f.to - f.from < 12)).toBe(true)
+  })
+
+  it('clean prose yields no findings', () => {
+    expect(mechanicsFindings('The garden was quiet and the rain fell softly on the leaves.')).toEqual([])
+  })
+})

web/src/components/Companion/prose.ts

@@ -0,0 +1,695 @@
+// Rules-based prose checker — NO LLM. This is the companion's "smart" side: it
+// reads the writer's actual text and surfaces one gentle, context-aware grammar
+// or style note at a time, the way an attentive tutor leaning over her shoulder
+// would. Every rule here is intentionally conservative: a wrong nudge erodes
+// trust far faster than a missed one earns it, so we only speak up when a
+// pattern is a high-confidence, genuinely-common English mistake.
+//
+// Each finding becomes a Mandarin-first bubble Line (see tips.ts), often quoting
+// a short slice of her own sentence so the advice clearly belongs to *this*
+// paragraph and not a generic tip jar.
+//
+// Two consumers share these rules (one source of truth, no duplication):
+//   • the companion bubbles — awareness notes, shown one at a time (analyzeProse)
+//   • the suggestion cards  — applyable one-click fixes (mechanicsFindings)
+// A rule is "applyable" when it can name an exact span and a single replacement;
+// it attaches a `fix` and feeds the cards. Awareness-only rules (run-ons, comma
+// splices, …) carry no `fix` and stay companion bubbles. The companion hides
+// fix-bearing hints so the same span never appears as both a bubble and a card.
+
+import type { Line } from './tips'
+
+export interface ProseHint extends Line {
+  // Stable, content-derived id so the same untouched sentence isn't re-flagged
+  // every cadence; the companion remembers recently-shown ids.
+  id: string
+  // Rule family, used to vary advice (don't show the same kind twice in a row).
+  rule: string
+  // Present only on *applyable* findings: the exact span and the text to swap in.
+  // These become suggestion cards; the companion skips them (see useCompanion).
+  fix?: Fix
+}
+
+// An exact, one-click edit: replace text[from:to] with `replacement`.
+export interface Fix {
+  from: number
+  to: number
+  replacement: string
+}
+
+// A deterministic suggestion-card finding, derived from an applyable hint. Mirrors
+// the backend's card shape (original/replacement/explanation + span) so the card
+// pipeline can persist it as the 'mechanics' family. `explanation` is the English
+// note; the card's own translate action renders Mandarin on demand.
+export interface MechanicsFinding {
+  from: number
+  to: number
+  original: string
+  replacement: string
+  explanation: string
+}
+
+// ── small text helpers ──────────────────────────────────────────────────────
+
+const ENGLISH_WORD_RE = /[A-Za-z]+(?:['’-][A-Za-z]+)*/g
+
+// Split into sentence-ish chunks (text + leading punctuation trimmed). Mirrors
+// the SENTENCE_RE terminators used elsewhere, including CJK fullwidth forms.
+function sentences(text: string): string[] {
+  const out: string[] = []
+  const re = /[^.!?。！？]+[.!?。！？]*/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text))) {
+    const s = m[0].trim()
+    if (s) out.push(s)
+  }
+  return out
+}
+
+// First few words of a sentence, as an anchor we can quote back to her.
+function anchor(s: string, n = 6): string {
+  const words = s.split(/\s+/).slice(0, n).join(' ')
+  return words.length < s.length ? `${words}…` : words
+}
+
+// Cheap, stable hash → short id suffix, so ids stay stable across recomputes but
+// change the moment she edits the offending text.
+function key(s: string): string {
+  return s.toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 48)
+}
+
+// Capitalize `repl`'s first letter when `original` started uppercase, so fixing a
+// sentence-initial word doesn't quietly lowercase the line.
+function matchCase(original: string, repl: string): string {
+  if (!original || !repl) return repl
+  const c = original[0]
+  if (c >= 'A' && c <= 'Z') return repl[0].toUpperCase() + repl.slice(1)
+  return repl
+}
+
+// ── individual rules ────────────────────────────────────────────────────────
+// Each rule pushes its findings; awareness rules cap themselves to a couple so a
+// single sentence can't flood the bubble, while applyable rules report every
+// occurrence (each becomes its own card). Applyable rules attach a `fix`.
+
+// Run-on / overly long sentences — the single most common readability problem
+// for ESL writers, who often chain clauses that a period would serve better.
+// Awareness-only: there is no single mechanical fix for "split this sentence".
+function runOns(text: string, out: ProseHint[]) {
+  let found = 0
+  for (const s of sentences(text)) {
+    if (found >= 2) break
+    const words = s.match(ENGLISH_WORD_RE)?.length ?? 0
+    const commas = (s.match(/,/g) ?? []).length
+    const longRun = words >= 32
+    const commaHeavy = words >= 24 && commas >= 2
+    if (longRun || commaHeavy) {
+      found++
+      out.push({
+        id: `runon:${key(s)}`,
+        rule: 'runon',
+        zh: '这句话有点长啦，分成两三句会更清楚 🌸',
+        en: `This one runs long — try splitting it: “${anchor(s)}”`,
+      })
+    }
+  }
+}
+
+// Comma splice — two independent clauses joined by only a comma. We look for a
+// comma immediately followed by a subject pronoun + a finite verb, which is a
+// strong, low-false-positive signal of a spliced second clause.
+// A comma, then a subject pronoun starting a fresh clause, then its verb. We no
+// longer whitelist verbs (that lost too many real splices) — instead we take any
+// word after the pronoun and reject the function words that signal it *isn't* a
+// new clause (a conjunction/preposition list like “she and I”, “it of course”).
+const SPLICE_RE = /[a-z]\w*,\s+(I|we|they|he|she|it|you)\s+([a-z]+)\b/g
+const SPLICE_NONVERB = new Set([
+  'and', 'or', 'but', 'nor', 'yet', 'so', 'to', 'too', 'also', 'of', 'in', 'on',
+  'at', 'for', 'with', 'as', 'who', 'whom', 'which', 'that', 'than', 'then',
+  'will', // “…, I will, …” is usually an aside, not a clean splice
+])
+
+// First words that signal the lead is an *introductory* element (transition,
+// subordinate clause, or adverbial phrase), where a following “, subject verb”
+// is correct punctuation — not a splice. Guards against “However, we left.” and
+// “After dinner, I went home.”
+const INTRO_LEAD = new Set([
+  'after', 'before', 'when', 'while', 'although', 'though', 'because', 'since',
+  'if', 'as', 'until', 'unless', 'whenever', 'wherever', 'whereas', 'however',
+  'therefore', 'moreover', 'furthermore', 'nevertheless', 'nonetheless',
+  'meanwhile', 'consequently', 'otherwise', 'besides', 'instead', 'finally',
+  'first', 'firstly', 'second', 'secondly', 'next', 'then', 'later', 'eventually',
+  'afterwards', 'anyway', 'yesterday', 'today', 'tomorrow', 'honestly',
+  'actually', 'suddenly', 'sometimes', 'usually', 'often', 'also', 'still',
+  'now', 'here', 'there', 'well', 'yes', 'no', 'fortunately', 'unfortunately',
+  'surprisingly', 'clearly', 'obviously', 'basically', 'generally', 'initially',
+  'recently', 'currently', 'sadly', 'luckily', 'hopefully', 'frankly',
+  'personally', 'overall', 'soon', 'once', 'during', 'in', 'on', 'at', 'for',
+  'with', 'without', 'by', 'from', 'despite', 'throughout', 'given', 'regarding',
+])
+
+// A genuine comma splice has an *independent clause* before the comma. We
+// approximate that by requiring the lead to be ≥3 words and not begin with an
+// introductory word — short or transition-led leads are intro phrases, not
+// spliced clauses. Precision over recall: a wrong nudge costs more than a miss.
+// Awareness-only: the fix is ambiguous (period vs. a joining word).
+function commaSplices(text: string, out: ProseHint[]) {
+  let found = 0
+  for (const s of sentences(text)) {
+    if (found >= 2) break
+    SPLICE_RE.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = SPLICE_RE.exec(s)) && found < 2) {
+      const commaIdx = s.indexOf(',', m.index)
+      const lead = s.slice(0, commaIdx).trim()
+      const words = lead.split(/\s+/).filter(Boolean)
+      const firstWord = words[0]?.toLowerCase().replace(/[^a-z]/g, '') ?? ''
+      if (words.length < 3 || INTRO_LEAD.has(firstWord)) continue
+      if (SPLICE_NONVERB.has(m[2].toLowerCase())) continue
+      found++
+      out.push({
+        id: `splice:${key(m[0])}`,
+        rule: 'splice',
+        zh: '这里用逗号连了两句话，可以改成句号，或加个 “and / but”。',
+        en: `Two sentences joined by a comma: “…${m[0].trim()}…” — use a period or add a joining word.`,
+      })
+    }
+  }
+}
+
+// Unclear antecedent — a sentence that opens with This/That/These/Those riding
+// straight into a verb, with no noun naming what it points back to. Only flag
+// when there's a prior sentence (so an antecedent is actually in question).
+// Awareness-only: naming the referent needs the writer.
+const ANTECEDENT_RE =
+  /^(This|That|These|Those)\s+(is|are|was|were|will|would|can|could|should|makes?|made|means?|shows?|showed|gives?|gave|causes?|caused|creates?|created|leads?|led|results?|happens?|happened|helps?|helped)\b/
+
+function antecedents(text: string, out: ProseHint[]) {
+  const list = sentences(text)
+  let found = 0
+  for (let i = 1; i < list.length && found < 2; i++) {
+    const s = list[i]
+    const m = s.match(ANTECEDENT_RE)
+    if (m) {
+      found++
+      out.push({
+        id: `antecedent:${key(s)}`,
+        rule: 'antecedent',
+        zh: `“${m[1]}” 指代不太清楚，最好点明它指的是什么（比如 “${m[1]} idea / change…”）。`,
+        en: `“${m[1]}” here is a little vague — name what it refers to.`,
+      })
+    }
+  }
+}
+
+// Oxford comma — a 3+ item list ending “… X and Y” with no comma before the
+// conjunction. Guarded by a clause-starter stoplist so we don't mistake a
+// compound clause (“…, but she and I…”) for a list. Awareness-only: inserting
+// the serial comma is borderline-stylistic, so we nudge rather than auto-edit.
+const OXFORD_RE = /(\w+),\s+([\w'’-]+(?:\s+[\w'’-]+){0,2})\s+(and|or)\s+[\w'’-]+/g
+const CLAUSE_STARTERS = new Set([
+  'but', 'so', 'because', 'which', 'who', 'that', 'when', 'while', 'if',
+  'although', 'though', 'since', 'as', 'and', 'or', 'nor', 'yet', 'then',
+  'however', 'whereas',
+  // Subject pronouns signal a clause, not a list item (“…, I went home and…”).
+  'i', 'you', 'he', 'she', 'it', 'we', 'they',
+])
+
+function oxford(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  let found = 0
+  OXFORD_RE.lastIndex = 0
+  while ((m = OXFORD_RE.exec(text)) && found < 1) {
+    const firstWord = m[2].split(/\s+/)[0]?.toLowerCase() ?? ''
+    if (CLAUSE_STARTERS.has(firstWord)) continue
+    found++
+    out.push({
+      id: `oxford:${key(m[0])}`,
+      rule: 'oxford',
+      zh: '列举三样以上时，在 “and / or” 前也加个逗号会更清楚（牛津逗号）。',
+      en: `In a list, a comma before “${m[3]}” keeps it clear: “a, b, ${m[3]} c”.`,
+    })
+  }
+}
+
+// A transition word opening a sentence with no comma after it (“However we…”).
+// Limited to conjunctive adverbs that strongly want the comma — sequence words
+// like “Then/First/Finally” are left out (their comma is optional). Awareness-
+// only: it fires per-sentence (offsets are sentence-relative), so we nudge.
+const INTRO_RE =
+  /^(However|Therefore|Moreover|Furthermore|Nevertheless|Nonetheless|Meanwhile|Consequently|In addition|In conclusion|As a result|On the other hand|For example|For instance)\s+[A-Za-z]/
+
+function introComma(text: string, out: ProseHint[]) {
+  for (const s of sentences(text)) {
+    const m = s.match(INTRO_RE)
+    if (m) {
+      out.push({
+        id: `introcomma:${m[1].toLowerCase()}`,
+        rule: 'introcomma',
+        zh: `开头的过渡词后面加个逗号：“${m[1]}, …”。`,
+        en: `Put a comma after the opening transition: “${m[1]}, …”.`,
+      })
+      break
+    }
+  }
+}
+
+// Sentence not starting with a capital. We look after a terminator, and ignore
+// CJK sentences (she writes Mandarin too — those don't take Latin capitals).
+// Awareness-only: a bare “. x” also matches abbreviations (“U.S. then”), so we
+// nudge rather than auto-capitalize.
+const LOWER_START_RE = /[.!?]\s+([a-z])/
+
+function sentenceCaps(text: string, out: ProseHint[]) {
+  if (LOWER_START_RE.test(text)) {
+    out.push({
+      id: 'cap-sentence',
+      rule: 'cap-sentence',
+      zh: '每个句子的开头，用大写字母开始吧。',
+      en: 'Start each new sentence with a capital letter.',
+    })
+  }
+}
+
+// ── applyable rules (also feed the suggestion cards) ─────────────────────────
+
+// Doubled word — “the the”, “is is”. Excludes the handful of doublings that can
+// be legitimate (“the fact that that happened”, “she had had enough”).
+const DOUBLE_RE = /\b([A-Za-z]+)(\s+)\1\b/gi
+const LEGIT_DOUBLES = new Set(['that', 'had'])
+
+function doubles(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  DOUBLE_RE.lastIndex = 0
+  while ((m = DOUBLE_RE.exec(text))) {
+    const w = m[1].toLowerCase()
+    if (LEGIT_DOUBLES.has(w)) continue
+    const from = m.index
+    const to = from + m[0].length
+    out.push({
+      id: `double:${from}:${key(m[0])}`,
+      rule: 'double',
+      zh: `“${m[1]}” 好像写了两遍，检查一下哦。`,
+      en: `“${m[1]} ${m[1]}” — looks like a word got doubled.`,
+      fix: { from, to, replacement: m[1] },
+    })
+  }
+}
+
+// Lowercase standalone “I”. Conservative: only when bounded by spaces / line
+// edge, to avoid tangling with “i.e.” and the like. Awareness-only: a single
+// character can't be re-anchored unambiguously by string (every word holds an
+// “i”), so this stays a companion nudge rather than a one-click card.
+const LOWER_I_RE = /(^|[^\p{L}\p{N}_])i(?=$|[^\p{L}\p{N}_])/mu
+
+function pronounI(text: string, out: ProseHint[]) {
+  const m = LOWER_I_RE.exec(text)
+  LOWER_I_RE.lastIndex = 0
+  if (!m) return
+  const at = m.index + m[1].length
+  if (text[at + 1] === '.') return // “i.e.” etc. — precision over recall
+  out.push({
+    id: 'cap-i',
+    rule: 'cap-i',
+    zh: '英文里的 “I”（我）任何时候都要大写哦。',
+    en: 'In English, “I” is always written as a capital letter.',
+  })
+}
+
+// A stray space *before* punctuation (a common habit carried from CJK spacing).
+const SPACE_BEFORE_PUNCT_RE = /([A-Za-z]+) +([,;:!?]|\.(?!\.))/g
+
+function spaceBeforePunct(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  SPACE_BEFORE_PUNCT_RE.lastIndex = 0
+  while ((m = SPACE_BEFORE_PUNCT_RE.exec(text))) {
+    const from = m.index
+    const to = from + m[0].length
+    out.push({
+      id: `space-punct:${from}`,
+      rule: 'space-punct',
+      zh: '标点前面不用空格，逗号、句号紧跟在前一个词后面就好。',
+      en: 'No space before punctuation — it tucks right against the word.',
+      fix: { from, to, replacement: m[1] + m[2] },
+    })
+  }
+}
+
+// Missing space *after* a comma or sentence period (“apple,banana”, “end.Next”).
+// The comma case requires letters on both sides so numbers like 1,000 are safe;
+// the period case requires a real word boundary so “e.g.”/“U.S.” are skipped.
+const NO_SPACE_COMMA_RE = /([A-Za-z]+,)([A-Za-z]+)/g
+const NO_SPACE_PERIOD_RE = /([a-z]{2,}\.)([A-Z][a-z]+)/g
+
+function spaceAfterPunct(text: string, out: ProseHint[]) {
+  for (const re of [NO_SPACE_COMMA_RE, NO_SPACE_PERIOD_RE]) {
+    let m: RegExpExecArray | null
+    re.lastIndex = 0
+    while ((m = re.exec(text))) {
+      const from = m.index
+      const to = from + m[0].length
+      out.push({
+        id: `space-after:${from}`,
+        rule: 'space-after',
+        zh: '逗号、句号后面要空一格，再接下一个词。',
+        en: 'Add a space after a comma or period before the next word.',
+        fix: { from, to, replacement: `${m[1]} ${m[2]}` },
+      })
+    }
+  }
+}
+
+// a vs. an — chosen by the *sound* of the next word. We work only on lowercase
+// words (sidestepping proper nouns / acronyms) and keep sound-exception lists.
+const A_BEFORE_VOWEL_RE = /\b(a)\s+([aeiou][a-z]+)\b/g
+// Vowel-spelled but consonant-sounding → “a” is correct, don't flag.
+const CONSONANT_SOUND_RE = /^(uni|use|usu|util|euro?|eul|ewe|once|one|ubiqu|unanim)/
+const AN_BEFORE_CONSONANT_RE = /\b(an)\s+([b-df-hj-np-tv-z][a-z]+)\b/g
+// Consonant-spelled but vowel-sounding (silent h) → “an” is correct, don't flag.
+const VOWEL_SOUND_RE = /^(hour|honest|honou?r|heir|homage)/
+
+function articles(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  A_BEFORE_VOWEL_RE.lastIndex = 0
+  while ((m = A_BEFORE_VOWEL_RE.exec(text))) {
+    if (CONSONANT_SOUND_RE.test(m[2])) continue
+    // Span the whole "a <noun>" so the original is a distinctive, anchorable
+    // phrase (a bare "a" matches everywhere). Replacement swaps only the article.
+    out.push({
+      id: `article-an:${m.index}`,
+      rule: 'article',
+      zh: `元音开头的词前用 “an”：“an ${m[2]}”。`,
+      en: `Before a vowel sound, use “an”: “an ${m[2]}”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: matchCase(m[1], 'an') + m[0].slice(m[1].length) },
+    })
+  }
+  AN_BEFORE_CONSONANT_RE.lastIndex = 0
+  while ((m = AN_BEFORE_CONSONANT_RE.exec(text))) {
+    if (VOWEL_SOUND_RE.test(m[2])) continue
+    out.push({
+      id: `article-a:${m.index}`,
+      rule: 'article',
+      zh: `辅音开头的词前用 “a”：“a ${m[2]}”。`,
+      en: `Before a consonant sound, use “a”: “a ${m[2]}”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: matchCase(m[1], 'a') + m[0].slice(m[1].length) },
+    })
+  }
+}
+
+// Mass nouns that Mandarin speakers very commonly pluralize. These words are
+// essentially never valid with a trailing “s”, so the list is its own guard.
+const UNCOUNTABLE_PLURAL_RE =
+  /\b(informations|advices|knowledges|equipments|furnitures|homeworks|softwares|hardwares|luggages|baggages|sceneries|machineries)\b/gi
+
+function uncountables(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  UNCOUNTABLE_PLURAL_RE.lastIndex = 0
+  while ((m = UNCOUNTABLE_PLURAL_RE.exec(text))) {
+    const word = m[1]
+    const singular = word.replace(/s$/i, '')
+    out.push({
+      id: `uncountable:${m.index}`,
+      rule: 'uncountable',
+      zh: `“${word}” 是不可数名词，不用加 s，写 “${singular}” 就好。`,
+      en: `“${word}” is uncountable — drop the “s”: just “${singular}”.`,
+      fix: { from: m.index, to: m.index + word.length, replacement: singular },
+    })
+  }
+}
+
+// Languages, nationalities, days, and months are proper nouns in English but
+// not in Mandarin, so they're routinely left lowercase. We list only the
+// unambiguous ones — “may/march/august/china/turkey/polish” are skipped because
+// they're also ordinary lowercase words and would misfire.
+const PROPER_NOUNS =
+  'monday|tuesday|wednesday|thursday|friday|saturday|sunday|' +
+  'january|february|april|june|july|september|october|november|december|' +
+  'english|chinese|mandarin|cantonese|japanese|korean|french|spanish|german|' +
+  'italian|russian|portuguese|arabic|vietnamese|thai|american|british|canadian|' +
+  'australian|mexican|brazilian|european'
+// Case-sensitive (lowercase-only) so already-capitalized words aren't flagged.
+const PROPER_NOUN_RE = new RegExp(`\\b(${PROPER_NOUNS})\\b`, 'g')
+
+function properCaps(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  PROPER_NOUN_RE.lastIndex = 0
+  while ((m = PROPER_NOUN_RE.exec(text))) {
+    const word = m[1]
+    const fixed = word[0].toUpperCase() + word.slice(1)
+    out.push({
+      id: `propercap:${m.index}`,
+      rule: 'propercap',
+      zh: `语言、国籍、星期和月份在英文里要大写：“${fixed}”。`,
+      en: `Languages, days, and months are capitalized in English: “${fixed}”.`,
+      fix: { from: m.index, to: m.index + word.length, replacement: fixed },
+    })
+  }
+}
+
+// Third-person singular verb form, for the agreement rule's suggestion.
+function third(verb: string): string {
+  const v = verb.toLowerCase()
+  const irregular: Record<string, string> = { have: 'has', do: 'does', go: 'goes' }
+  if (irregular[v]) return irregular[v]
+  if (/[^aeiou]y$/.test(v)) return v.slice(0, -1) + 'ies'
+  if (/(s|x|z|ch|sh)$/.test(v)) return v + 'es'
+  return v + 's'
+}
+
+// Subject–verb agreement after he/she/it: a bare (base-form) verb where the
+// third-person “-s” form is required. We skip the causative/perception frames
+// (“let it go”, “make it work”, “help it grow”) where the bare verb is correct.
+const SVA_BASE =
+  'go|have|do|make|like|want|need|know|think|say|see|feel|get|take|come|give|' +
+  'run|play|work|live|look|seem|become|bring|buy|find|keep|leave|tell|try|call|' +
+  'move|turn|put|mean|show|use|love|hope|wish|believe|understand|remember|enjoy'
+// The preceding word is optional so a sentence-initial subject (“She have…”)
+// still matches; when present it lets us skip causative/perception frames.
+const SVA_RE = new RegExp(`(?:(\\w+)\\s+)?\\b(he|she|it)\\s+(${SVA_BASE})\\b`, 'gi')
+const CAUSATIVE = new Set([
+  'let', 'lets', 'make', 'makes', 'made', 'help', 'helps', 'helped', 'watch',
+  'watches', 'watched', 'see', 'sees', 'saw', 'hear', 'heard', 'have', 'has',
+  'had', 'let’s', "let's",
+])
+
+function subjectVerbAgreement(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  SVA_RE.lastIndex = 0
+  while ((m = SVA_RE.exec(text))) {
+    if (m[1] && CAUSATIVE.has(m[1].toLowerCase())) continue
+    const verb = m[3]
+    const fixed = third(verb)
+    // Span the whole match (subject + verb, plus any captured lead) so the
+    // original anchors; the replacement corrects only the trailing verb.
+    const head = m[0].slice(0, m[0].length - verb.length)
+    out.push({
+      id: `sva:${m.index}`,
+      rule: 'sva',
+      zh: `主语是 he/she/it 时，动词要加 -s：“${m[2]} ${fixed}”。`,
+      en: `After he/she/it the verb takes “-s”: “${m[2]} ${fixed}”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: head + matchCase(verb, fixed) },
+    })
+  }
+}
+
+// Singular noun after a cardinal number (“three apple”). Adjectives between the
+// number and noun would misfire (“two small dogs”), so we only flag when the
+// candidate is followed by a clause boundary — a verb, preposition, article, or
+// punctuation — which means it's the noun itself, not a modifier.
+const NUMBER_NOUN_RE =
+  /\b(two|three|four|five|six|seven|eight|nine|ten)\s+([a-z]{3,})\b(?=\s*(?:[.,!?;:]|$|\s(?:is|are|was|were|and|or|but|that|which|who|in|on|at|to|for|with|will|can|could|would|should|the|a|an)\b))/g
+// Irregular plurals / mass nouns that are correct without an “s”.
+const NON_S_PLURAL = new Set([
+  'people', 'children', 'men', 'women', 'fish', 'deer', 'sheep', 'feet', 'teeth',
+  'mice', 'geese', 'police', 'staff', 'series', 'species', 'aircraft', 'cattle',
+  'hundred', 'thousand', 'million', 'billion', 'dozen', 'percent',
+])
+
+function pluralAfterNumber(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  NUMBER_NOUN_RE.lastIndex = 0
+  while ((m = NUMBER_NOUN_RE.exec(text))) {
+    const noun = m[2].toLowerCase()
+    if (noun.endsWith('s') || NON_S_PLURAL.has(noun)) continue
+    // Span "<number> <noun>" so the original anchors; append “s” to the noun.
+    out.push({
+      id: `plural:${m.index}`,
+      rule: 'plural',
+      zh: `“${m[1]}” 后面的名词要用复数：“${m[1]} ${m[2]}s”。`,
+      en: `After “${m[1]}”, the noun is plural: “${m[1]} ${m[2]}s”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: `${m[0]}s` },
+    })
+  }
+}
+
+// Two stacked determiners (“the my book”, “a the”) — Mandarin uses a bare
+// possessive, so the article often gets stacked on top. The article goes.
+const DOUBLE_DET_RE =
+  /\b(a|an|the)(\s+)(a|an|the|my|your|his|her|its|our|their)\b/gi
+
+function doubleDeterminer(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  DOUBLE_DET_RE.lastIndex = 0
+  while ((m = DOUBLE_DET_RE.exec(text))) {
+    // Two *identical* words ("the the") are a doubled word, not stacked
+    // determiners — leave that to the `doubles` rule so we don't double-flag.
+    if (m[1].toLowerCase() === m[3].toLowerCase()) continue
+    out.push({
+      id: `doubledet:${m.index}`,
+      rule: 'doubledet',
+      zh: `“${m[1]} ${m[3]}” 用了两个限定词，留一个就好（比如去掉 “${m[1]}”）。`,
+      en: `“${m[1]} ${m[3]}” stacks two determiners — keep just one.`,
+      // Drop the article (m[1]); keep the second determiner, casing preserved.
+      fix: { from: m.index, to: m.index + m[0].length, replacement: matchCase(m[1], m[3]) },
+    })
+  }
+}
+
+// “there is” with a plural quantifier → should be “there are”. We trigger only
+// on clearly-plural cues (skip “some/any”, which are fine with singular mass
+// nouns: “there is some water”).
+const THERE_IS_RE =
+  /\bthere(\s+is|'s|’s)\s+(many|several|numerous|various|few|two|three|four|five|six|seven|eight|nine|ten)\b/gi
+
+function thereIsPlural(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  THERE_IS_RE.lastIndex = 0
+  while ((m = THERE_IS_RE.exec(text))) {
+    // Span the whole "there is <plural>" phrase so it anchors; swap the verb part
+    // (m[1]: “ is” / “'s”) for “ are”, preserving the “there” casing and the cue.
+    const replacement = m[0].slice(0, 5) + ' are' + m[0].slice(5 + m[1].length)
+    out.push({
+      id: `thereis:${m.index}`,
+      rule: 'thereis',
+      zh: `后面是复数时用 “there are”：“there are ${m[2]}…”。`,
+      en: `With a plural, use “there are”: “there are ${m[2]}…”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement },
+    })
+  }
+}
+
+// its / it's — only the two unambiguous directions: “it's own” (always its own)
+// and “its a/an” (the possessive can't take an article → it's a/an).
+const ITS_OWN_RE = /\b(it's|it’s)\s+own\b/gi
+const ITS_ARTICLE_RE = /\bits\s+(a|an)\b/gi
+
+function itsConfusion(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  ITS_OWN_RE.lastIndex = 0
+  while ((m = ITS_OWN_RE.exec(text))) {
+    // Span "it's own" so it anchors; swap the leading token to the possessive.
+    out.push({
+      id: `its-own:${m.index}`,
+      rule: 'its',
+      zh: '“it’s” = “it is”；表示“它的”要用 “its”，所以是 “its own”。',
+      en: '“it’s” means “it is” — the possessive is “its”: “its own”.',
+      fix: { from: m.index, to: m.index + m[0].length, replacement: matchCase(m[1], 'its') + m[0].slice(m[1].length) },
+    })
+  }
+  ITS_ARTICLE_RE.lastIndex = 0
+  while ((m = ITS_ARTICLE_RE.exec(text))) {
+    // Span "its a/an" so it anchors; swap "its" → "it's".
+    out.push({
+      id: `its-article:${m.index}`,
+      rule: 'its',
+      zh: `这里应该是 “it’s ${m[1]}”（it is），“its” 是“它的”。`,
+      en: `Here it should be “it’s ${m[1]}” (it is); “its” means belonging to it.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: matchCase(m[0][0], "it's") + m[0].slice(3) },
+    })
+  }
+}
+
+// Comparative + “then” where “than” is meant (“better then”, “more then”). We
+// use an explicit comparative list rather than a generic “-er” pattern, which
+// would snag “after then”, “however”, “remember”, etc.
+const COMPARATIVES =
+  'better|more|less|rather|worse|greater|other|older|younger|bigger|smaller|' +
+  'larger|faster|slower|higher|lower|cheaper|stronger|weaker|easier|harder|' +
+  'earlier|later|sooner|longer|shorter|taller|richer|poorer|happier|safer'
+const THAN_THEN_RE = new RegExp(`\\b(${COMPARATIVES})(\\s+)then\\b`, 'gi')
+
+function thanThen(text: string, out: ProseHint[]) {
+  let m: RegExpExecArray | null
+  THAN_THEN_RE.lastIndex = 0
+  while ((m = THAN_THEN_RE.exec(text))) {
+    // Span "<comparative> then" so it anchors; swap the trailing “then” → “than”.
+    const thenFrom = m.index + m[0].length - 4
+    out.push({
+      id: `than:${m.index}`,
+      rule: 'than',
+      zh: `比较的时候用 “than”，不是 “then”：“${m[1]} than”。`,
+      en: `For comparisons use “than”, not “then”: “${m[1]} than”.`,
+      fix: { from: m.index, to: m.index + m[0].length, replacement: m[0].slice(0, m[0].length - 4) + matchCase(text[thenFrom], 'than') },
+    })
+  }
+}
+
+// ── orchestration ───────────────────────────────────────────────────────────
+
+// Rules run in priority order — the ones the writer cares most about first, so
+// that when several fire at once the companion leads with the weightiest note.
+const RULES: Array<(text: string, out: ProseHint[]) => void> = [
+  runOns,
+  commaSplices,
+  antecedents,
+  oxford,
+  articles,
+  uncountables,
+  properCaps,
+  subjectVerbAgreement,
+  pluralAfterNumber,
+  doubleDeterminer,
+  thereIsPlural,
+  itsConfusion,
+  thanThen,
+  introComma,
+  doubles,
+  pronounI,
+  sentenceCaps,
+  spaceBeforePunct,
+  spaceAfterPunct,
+]
+
+// analyzeProse returns context-aware hints, highest-priority first. It bails on
+// text too short to advise on (mid-thought drafts shouldn't get picked apart).
+// Hints that carry a `fix` are applyable (they also surface as suggestion cards);
+// the companion filters those out so a span isn't both a bubble and a card.
+export function analyzeProse(text: string): ProseHint[] {
+  const englishWords = text.match(ENGLISH_WORD_RE)?.length ?? 0
+  if (englishWords < 8) return []
+  const out: ProseHint[] = []
+  for (const rule of RULES) rule(text, out)
+  return out
+}
+
+// mechanicsFindings returns every applyable deterministic fix in the text, as
+// suggestion-card findings with exact spans. No word-count floor: a doubled word
+// or a stray lowercase “i” is worth fixing even in a short draft, the way a
+// spell-checker would. The card pipeline persists these as the 'mechanics'
+// family; collisions with the LLM cards are resolved server-side (mechanics
+// wins, since its span is exact).
+export function mechanicsFindings(text: string): MechanicsFinding[] {
+  const hints: ProseHint[] = []
+  for (const rule of RULES) rule(text, hints)
+  const found: MechanicsFinding[] = []
+  for (const h of hints) {
+    if (!h.fix) continue
+    const { from, to, replacement } = h.fix
+    const original = text.slice(from, to)
+    if (!original || original === replacement) continue
+    found.push({ from, to, original, replacement, explanation: h.en })
+  }
+  // Two rules can occasionally claim overlapping spans (e.g. a doubled word that
+  // also reads as stacked determiners). Resolve to one card per stretch of text:
+  // earlier start wins, ties broken by the longer span. The backend resolves the
+  // separate mechanics-vs-LLM collisions; this handles mechanics-vs-mechanics.
+  found.sort((a, b) => (a.from !== b.from ? a.from - b.from : b.to - a.to))
+  const out: MechanicsFinding[] = []
+  let lastEnd = -1
+  for (const f of found) {
+    if (f.from < lastEnd) continue
+    out.push(f)
+    lastEnd = f.to
+  }
+  return out
+}

web/src/components/Companion/tips.ts

@@ -0,0 +1,94 @@
+// Bilingual companion copy — Mandarin first (she writes/reads in Mandarin), with
+// a warm English subtitle. Kept gentle and encouraging, never scolding. The
+// bubble renders zh prominently and en underneath. (Spec north star: CJK is
+// first-class; Ask Petal & companion answer in Mandarin.)
+
+export interface Line {
+  zh: string
+  en: string
+}
+
+// Played when a suggestion is accepted or a milestone hits — pure warmth.
+export const ENCOURAGEMENTS: Line[] = [
+  { zh: '好棒！这一句更顺了 🌸', en: 'Lovely — that reads so much smoother now.' },
+  { zh: '你写得越来越好了 ✨', en: "You're getting better and better." },
+  { zh: '我很喜欢这个改法 💕', en: 'I really like that change.' },
+  { zh: '继续保持，加油！', en: 'Keep going — you’ve got this!' },
+  { zh: '嗯嗯，这样清楚多了 👍', en: 'Mm, that’s much clearer.' },
+  { zh: '这个词用得真好 🌷', en: 'That’s such a good word choice.' },
+  { zh: '哇，这一段读起来真舒服 ☁️', en: 'Ooh, that paragraph flows so nicely.' },
+  { zh: '看你越写越有信心，真好 💛', en: 'I love watching you write with more confidence.' },
+  { zh: '一点点进步，都是了不起的进步 🌱', en: 'Every little bit of progress counts.' },
+  { zh: '今天的你，文字闪闪发光 ✨', en: 'Your words are sparkling today.' },
+]
+
+// Gentle, generic writing/ESL tips — the fallback when the rules-based prose
+// checker (prose.ts) finds nothing concrete to point at in her current text.
+export const TIPS: Line[] = [
+  { zh: '小贴士：英文句子短一点，会更清楚哦。', en: 'Tip: shorter English sentences often read clearer.' },
+  { zh: '别忘了冠词 “the” 和 “a” 哦。', en: "Don't forget articles like “the” and “a”." },
+  { zh: '过去的事情用过去式：go → went。', en: 'For the past, use past tense: go → went.' },
+  { zh: '读出声音，能帮你发现奇怪的地方。', en: 'Reading aloud helps you catch awkward spots.' },
+  { zh: '一个段落讲一个想法就好。', en: 'One idea per paragraph keeps it tidy.' },
+  { zh: '不确定的地方，问问我就好啦 ✨', en: 'Not sure about something? Just ask me. ✨' },
+  { zh: '复数别忘了加 s：two apples 🍎', en: 'Plurals take an “s”: two apples 🍎' },
+]
+
+// Shown after a long stretch of continuous writing.
+export const BREAKS: Line[] = [
+  { zh: '写了好一会儿啦，起来走走，让眼睛休息一下 🍵', en: "You've been writing a while — stretch and rest your eyes. 🍵" },
+  { zh: '喝口水，休息五分钟好不好？', en: 'Sip some water and take five?' },
+  { zh: '看看远方，放松一下眼睛 🌿', en: 'Look into the distance for a moment — give your eyes a break. 🌿' },
+]
+
+// Shown when she's still writing late at night (≥11pm). Caring, a little
+// playful — the kitten is always asleep, so "you should be too" lands as a gag,
+// never a scold. zh stays gentle; the English subtitle carries the wink.
+export const BEDTIME: Line[] = [
+  { zh: '你的床在想你了哦 🛏️', en: 'I bet your bed is missing you right now.' },
+  { zh: '太累可写不出好文字呀，早点歇着吧 🌙', en: 'A tired writer is a bad writer — get some rest.' },
+  { zh: '好好睡一觉，灵感自己会来 ✨', en: 'Sleep is a wondrous enabler.' },
+  { zh: '听见了吗？没有吧——大家都睡了，你也该睡啦 😴', en: "Hear that? No… you don't, because everyone is sleeping and you should be too." },
+  // A few old Chinese proverbs on sleep (zh = a faithful rendering of the
+  // English sense — the verified classical 原文 isn't recoverable; swap in the
+  // exact source text if you have it). They read a touch wittier/wiser than the
+  // gentle lines above, which suits a late-night nudge.
+  { zh: '一夜不眠，十日不安。', en: "The loss of one night's sleep is followed by ten days of inconvenience." },
+  { zh: '前半夜醒着想自己的过错，后半夜睡着才想别人的不是。', en: 'Think of your own faults the first part of the night when you are awake, and of the faults of others the latter part of the night when you are asleep.' },
+  { zh: '黄昏与人相骂，夜半独自难眠。', en: 'Curse your spouse at evening, sleep alone at night.' },
+]
+
+// First hello when the app opens.
+export const GREETING: Line = {
+  zh: '嗨～我在这儿陪你写作哦 🐱',
+  en: "Hi! I'm right here keeping you company. 🐱",
+}
+
+// Welcome-back nudge after she returns from an idle pause.
+export const WELCOME_BACK: Line = {
+  zh: '欢迎回来 ✨ 我们继续吧！',
+  en: 'Welcome back ✨ let’s keep going!',
+}
+
+// Gentle "haiya, something went wrong" lines — paired with the error sound when
+// the LLM is unreachable or a save fails. Never alarming, always reassuring.
+export const ERRORS: Line[] = [
+  { zh: '哎呀～出了点小问题，你的字都还在哦。', en: 'Oops — a little hiccup, but your words are safe.' },
+  { zh: '哎呀，我这边卡了一下，马上就好。', en: 'Haiya, I got stuck for a sec — back in a moment.' },
+  { zh: '别担心，等一下再试试看 🍵', en: "Don't worry — let's try again in a bit. 🍵" },
+]
+
+// Word-count milestones worth a little cheer — every 100 words, on up.
+export const MILESTONES = Array.from({ length: 100 }, (_, i) => (i + 1) * 100)
+
+export function milestoneLine(n: number): Line {
+  return {
+    zh: `哇！已经 ${n} 个词了，太厉害了 🎉`,
+    en: `Wow — ${n} words already! Amazing. 🎉`,
+  }
+}
+
+// Deterministic-enough random pick (Math.random is fine in the browser runtime).
+export function pick<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)]
+}

web/src/components/Companion/useCompanion.ts

@@ -0,0 +1,302 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { SaveStatus } from '../../hooks/useAutoSave'
+import {
+  BEDTIME,
+  BREAKS,
+  ENCOURAGEMENTS,
+  ERRORS,
+  GREETING,
+  MILESTONES,
+  TIPS,
+  WELCOME_BACK,
+  milestoneLine,
+  pick,
+  type Line,
+} from './tips'
+import { analyzeProse } from './prose'
+import { playPop, playSound, type SoundName } from '../../audio/sounds'
+import { isBedtime } from '../../lib/night'
+
+// The kitten's expression. Maps to a Lottie animation when assets are present,
+// otherwise to an emoji placeholder (see PetalCompanion).
+export type Mood = 'idle' | 'happy' | 'talking' | 'sleeping' | 'celebrate'
+
+export type BubbleTone = 'cheer' | 'tip' | 'break' | 'error' | 'bedtime'
+export interface Bubble extends Line {
+  tone: BubbleTone
+}
+
+interface Signals {
+  wordCount: number
+  saveStatus: SaveStatus
+  // True while the writing-assist LLM is unreachable (timeout / down). A
+  // false→true flip earns a gentle "haiya".
+  llmDown: boolean
+  // Monotonic counters bumped by the app on each editor change / accepted
+  // suggestion — lets the companion react without a full event bus.
+  editTick: number
+  acceptTick: number
+  // The document's plain text, used by the rules-based prose checker to offer
+  // context-aware writing notes instead of only generic tips.
+  text: string
+}
+
+// Timing knobs (ms). Tuned to feel present but never naggy.
+const IDLE_MS = 75_000 // no edits → kitten naps
+const BREAK_MS = 25 * 60_000 // continuous writing → suggest a break
+const TIP_MIN_GAP = 4 * 60_000 // at most one spontaneous tip per this window
+const PROACTIVE_GAP = 40_000 // floor between any two unsolicited bubbles
+const BEDTIME_GAP = 30 * 60_000 // at most one "go to bed" nudge per this window
+// The late-night window itself (isBedtime) lives in ../../lib/night so the
+// companion nag and the night-mode theme/starfall share one definition.
+// How long a bubble lingers. These are *floors* — readBubbleMs extends them by
+// how much there is to read, since she reads both the Mandarin and the English
+// (and tips now quote a slice of her own sentence, so they run longer).
+const BUBBLE_MS = 14_000 // baseline for a tip / break
+const CHEER_MS = 9_000 // a short cheer still needs a beat in two languages
+const READ_MS_PER_CHAR = 55 // ~18 chars/sec, generous for a bilingual ESL read
+const MAX_BUBBLE_MS = 32_000 // cap so a long quote can't pin the bubble forever
+const HOVER_GRACE_MS = 3_000 // lingers this long after she stops hovering
+const now = () => Date.now()
+
+// Reading time for a bubble: a base floor by tone, stretched by the combined
+// length of the Mandarin + English lines so denser advice stays up long enough
+// to actually finish reading.
+function readBubbleMs(b: Bubble): number {
+  const base = b.tone === 'cheer' ? CHEER_MS : b.tone === 'bedtime' ? BUBBLE_MS + 4_000 : BUBBLE_MS
+  const chars = b.zh.length + b.en.length
+  return Math.min(MAX_BUBBLE_MS, base + chars * READ_MS_PER_CHAR)
+}
+
+// useCompanion is the behavior engine: it watches writing signals and decides
+// when the kitten speaks, what mood it shows, and how to pace itself so the
+// companion feels alive without interrupting. UI-agnostic — returns state only.
+export function useCompanion({ wordCount, saveStatus, llmDown, editTick, acceptTick, text }: Signals) {
+  const [mood, setMood] = useState<Mood>('idle')
+  const [bubble, setBubble] = useState<Bubble | null>(null)
+
+  const lastActivity = useRef(now())
+  const sessionStart = useRef(now())
+  const lastProactive = useRef(0)
+  const lastTip = useRef(0)
+  const lastBreak = useRef(0)
+  const lastBedtime = useRef(0)
+  const nextMilestone = useRef(0) // index into MILESTONES
+  const sleeping = useRef(false)
+
+  // Latest text for the prose checker, read lazily by the heartbeat (kept in a
+  // ref so per-keystroke changes don't re-arm the interval).
+  const textRef = useRef(text)
+  textRef.current = text
+  // Recently-surfaced hint ids, so the same untouched sentence isn't re-flagged
+  // each cadence. A small ring — old ids age out and may resurface later.
+  const recentHints = useRef<string[]>([])
+  const lastRule = useRef<string>('')
+
+  const bubbleTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+  const moodTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  // Show a bubble + talking mood, then settle back. `proactive` messages respect
+  // the spacing floor; user-triggered ones (cheers) always go through.
+  const say = useCallback(
+    (b: Bubble, opts?: { proactive?: boolean; celebrate?: boolean; sound?: SoundName }) => {
+    const t = now()
+    if (opts?.proactive) {
+      if (bubble) return
+      if (t - lastProactive.current < PROACTIVE_GAP) return
+      lastProactive.current = t
+    }
+    sleeping.current = false
+    // A sound to match the bubble: callers can name a specific one (the milestone
+    // fanfare, the "haiya" on errors); everything else gets a rotating pop so the
+    // same blip never repeats back to back.
+    if (opts?.sound) playSound(opts.sound)
+    else playPop()
+    setBubble(b)
+    setMood(opts?.celebrate ? 'celebrate' : 'talking')
+    clearTimeout(bubbleTimer.current)
+    clearTimeout(moodTimer.current)
+    const dur = readBubbleMs(b)
+    bubbleTimer.current = setTimeout(() => setBubble(null), dur)
+    moodTimer.current = setTimeout(() => setMood('idle'), dur)
+  }, [bubble])
+
+  // Choose the next spontaneous tip. Prefer a real, context-aware note from the
+  // rules-based prose checker (it's actionable and clearly about *her* writing);
+  // fall back to a generic encouragement-style tip when the text reads clean or
+  // every finding was shown recently. Avoids repeating a finding or the same
+  // rule family back-to-back so the companion never feels like a broken record.
+  const nextTip = useCallback((): Bubble => {
+    // Applyable hints (those with a `fix`) surface as one-click suggestion cards,
+    // so the companion skips them — a span shouldn't be both a bubble and a card.
+    // What's left is the awareness notes (run-ons, splices, …) the kitten alone gives.
+    const hints = analyzeProse(textRef.current).filter((h) => !h.fix)
+    const fresh = hints.find(
+      (h) => !recentHints.current.includes(h.id) && h.rule !== lastRule.current,
+    )
+    const hint = fresh ?? hints.find((h) => !recentHints.current.includes(h.id))
+    if (hint) {
+      lastRule.current = hint.rule
+      recentHints.current = [hint.id, ...recentHints.current].slice(0, 8)
+      return { zh: hint.zh, en: hint.en, tone: 'tip' }
+    }
+    return { ...pick(TIPS), tone: 'tip' }
+  }, [])
+
+  const dismiss = useCallback(() => {
+    clearTimeout(bubbleTimer.current)
+    clearTimeout(moodTimer.current)
+    setBubble(null)
+    setMood('idle')
+  }, [])
+
+  // Pause the auto-dismiss while she hovers a bubble — so a longer note never
+  // vanishes mid-read. Releasing leaves it up for a short, fixed grace so it
+  // doesn't linger forever once she looks away.
+  const holdBubble = useCallback(() => {
+    clearTimeout(bubbleTimer.current)
+    clearTimeout(moodTimer.current)
+  }, [])
+
+  const releaseBubble = useCallback(() => {
+    clearTimeout(bubbleTimer.current)
+    clearTimeout(moodTimer.current)
+    bubbleTimer.current = setTimeout(() => setBubble(null), HOVER_GRACE_MS)
+    moodTimer.current = setTimeout(() => setMood('idle'), HOVER_GRACE_MS)
+  }, [])
+
+  // Opening hello (once), after a short beat so it doesn't race the first paint.
+  useEffect(() => {
+    const id = setTimeout(() => say({ ...GREETING, tone: 'tip' }), 1200)
+    return () => clearTimeout(id)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Edits: record activity and wake from a nap with a warm welcome-back.
+  const firstEdit = useRef(true)
+  useEffect(() => {
+    if (firstEdit.current) {
+      firstEdit.current = false
+      return
+    }
+    lastActivity.current = now()
+    if (sleeping.current) {
+      sleeping.current = false
+      sessionStart.current = now() // a fresh stretch starts on return
+      say({ ...WELCOME_BACK, tone: 'cheer' })
+    } else if (mood === 'sleeping') {
+      setMood('idle')
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editTick])
+
+  // Accepts: always cheer (it's a direct response to her action).
+  const firstAccept = useRef(true)
+  useEffect(() => {
+    if (firstAccept.current) {
+      firstAccept.current = false
+      return
+    }
+    say({ ...pick(ENCOURAGEMENTS), tone: 'cheer' }, { celebrate: true })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [acceptTick])
+
+  // Word-count milestones: cheer the first time each threshold is crossed.
+  useEffect(() => {
+    while (
+      nextMilestone.current < MILESTONES.length &&
+      wordCount >= MILESTONES[nextMilestone.current]
+    ) {
+      const n = MILESTONES[nextMilestone.current]
+      nextMilestone.current += 1
+      // Skip silently if we're just loading a long doc (no edits yet).
+      if (!firstEdit.current)
+        say({ ...milestoneLine(n), tone: 'cheer' }, { celebrate: true, sound: 'milestone' })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [wordCount])
+
+  // Trouble — a save failed or the writing-assist LLM went unreachable. Play the
+  // playful "haiya" and reassure her, but never spam: at most one per gap, and
+  // only on the *transition* into trouble (not while it lingers).
+  const lastError = useRef(0)
+  const ERROR_GAP = 20_000
+  const wasLlmDown = useRef(false)
+  const haiya = useCallback(() => {
+    const t = now()
+    if (t - lastError.current < ERROR_GAP) {
+      playSound('error') // still acknowledge it, just without a fresh bubble
+      return
+    }
+    lastError.current = t
+    say({ ...pick(ERRORS), tone: 'error' }, { sound: 'error' })
+  }, [say])
+
+  useEffect(() => {
+    if (saveStatus === 'error') haiya()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [saveStatus])
+
+  useEffect(() => {
+    if (llmDown && !wasLlmDown.current) haiya()
+    wasLlmDown.current = llmDown
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [llmDown])
+
+  // Occasional gentle cheer on a successful save (kept rare so it isn't noise).
+  useEffect(() => {
+    if (saveStatus === 'saved' && Math.random() < 0.18) {
+      say({ ...pick(ENCOURAGEMENTS), tone: 'cheer' }, { proactive: true })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [saveStatus])
+
+  // Heartbeat: nap when idle, suggest breaks, and drop the odd writing tip.
+  useEffect(() => {
+    const id = setInterval(() => {
+      const t = now()
+      const idleFor = t - lastActivity.current
+
+      if (idleFor > IDLE_MS) {
+        sleeping.current = true
+        if (!bubble) setMood('sleeping')
+        return // resting — no nudges while she's away
+      }
+
+      // Active: time for a break?
+      if (t - sessionStart.current > BREAK_MS && t - lastBreak.current > BREAK_MS) {
+        lastBreak.current = t
+        sessionStart.current = t
+        say({ ...pick(BREAKS), tone: 'break' }, { proactive: true })
+        return
+      }
+
+      // Burning the midnight oil? Gently suggest bed — caring, low-frequency,
+      // and only while she's actually still at it (the idle branch above already
+      // returned if she's away/napping).
+      if (isBedtime() && t - lastBedtime.current > BEDTIME_GAP) {
+        lastBedtime.current = t
+        say({ ...pick(BEDTIME), tone: 'bedtime' }, { proactive: true })
+        return
+      }
+
+      // Otherwise an occasional tip — context-aware when her text gives us
+      // something concrete to gently point at, generic warmth otherwise.
+      if (t - lastTip.current > TIP_MIN_GAP) {
+        lastTip.current = t
+        say(nextTip(), { proactive: true })
+      }
+    }, 10_000)
+    return () => clearInterval(id)
+  }, [bubble, say, nextTip])
+
+  useEffect(
+    () => () => {
+      clearTimeout(bubbleTimer.current)
+      clearTimeout(moodTimer.current)
+    },
+    [],
+  )
+
+  return { mood, bubble, dismiss, holdBubble, releaseBubble }
+}

web/src/components/DocList/DocList.tsx

@@ -0,0 +1,154 @@
+import { useMemo, useState } from 'react'
+import { api, type DocSummary, type Tag, type TagColor } from '../../api/client'
+import { DocListItem } from './DocListItem'
+import { SearchBox } from './SearchBox'
+import { TagChip } from './TagChip'
+
+interface Props {
+  docs: DocSummary[]
+  roster: Tag[]
+  selectedId: string | null
+  onSelect: (id: string) => void
+  onCreate: () => void
+  onDelete: (id: string) => void
+  onDuplicate: (id: string) => void
+  onToggleTag: (docId: string, tag: Tag) => void
+  onCreateTag: (docId: string, name: string, color: TagColor) => void
+}
+
+// Sidebar sort orders. 'recent' keeps the server's updated_at-desc ordering.
+type SortMode = 'recent' | 'title' | 'longest'
+const SORTS: { value: SortMode; label: string }[] = [
+  { value: 'recent', label: '最近 · Recent' },
+  { value: 'title', label: '标题 · Title' },
+  { value: 'longest', label: '字数 · Longest' },
+]
+
+// DocList is the sidebar: a cross-document search box, a tag filter bar, the New
+// button, and the document browser (each row showing its tag chips).
+export function DocList({
+  docs,
+  roster,
+  selectedId,
+  onSelect,
+  onCreate,
+  onDelete,
+  onDuplicate,
+  onToggleTag,
+  onCreateTag,
+}: Props) {
+  // Active tag filter (null = show all). Cleared automatically if the tag
+  // disappears from the roster.
+  const [filterId, setFilterId] = useState<string | null>(null)
+  const activeFilter = filterId && roster.some((t) => t.id === filterId) ? filterId : null
+  const [sort, setSort] = useState<SortMode>('recent')
+
+  const filtered = useMemo(() => {
+    const base = activeFilter ? docs.filter((d) => d.tags.some((t) => t.id === activeFilter)) : docs
+    if (sort === 'recent') return base // already updated_at-desc from the server
+    const arr = [...base]
+    if (sort === 'title') {
+      arr.sort((a, b) =>
+        (a.title || 'Untitled').localeCompare(b.title || 'Untitled', undefined, { sensitivity: 'base' }),
+      )
+    } else {
+      arr.sort((a, b) => b.word_count - a.word_count)
+    }
+    return arr
+  }, [docs, activeFilter, sort])
+
+  // Only surface tags that are actually in use, so the filter bar stays tidy.
+  const usedTags = useMemo(() => roster.filter((t) => (t.doc_count ?? 0) > 0), [roster])
+
+  return (
+    <aside
+      className="flex h-full w-[280px] flex-col gap-2 p-3"
+      style={{ borderRight: '1px solid var(--color-border)' }}
+    >
+      <SearchBox onSelect={onSelect} />
+
+      {usedTags.length > 0 && (
+        <div className="flex flex-wrap gap-1 pb-0.5">
+          {usedTags.map((t) => (
+            <TagChip
+              key={t.id}
+              tag={t}
+              count={t.doc_count}
+              active={activeFilter === t.id}
+              onClick={() => setFilterId((cur) => (cur === t.id ? null : t.id))}
+            />
+          ))}
+        </div>
+      )}
+
+      <button
+        type="button"
+        onClick={onCreate}
+        className="petal-tap flex items-center justify-center gap-2 text-sm font-bold text-white"
+        style={{ minHeight: 44, borderRadius: 'var(--radius-pill)', background: 'var(--color-accent)' }}
+        onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-accent-hover)')}
+        onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-accent)')}
+      >
+        <span className="text-base leading-none">＋</span> New Doc
+      </button>
+
+      {docs.length > 1 && (
+        <div className="flex items-center justify-end gap-1.5 px-1 text-xs" style={{ color: 'var(--color-muted)' }}>
+          <span aria-hidden>↕</span>
+          <select
+            aria-label="Sort documents"
+            value={sort}
+            onChange={(e) => setSort(e.target.value as SortMode)}
+            className="bg-transparent text-xs font-semibold focus:outline-none"
+            style={{ color: 'var(--color-plum)' }}
+          >
+            {SORTS.map((s) => (
+              <option key={s.value} value={s.value}>
+                {s.label}
+              </option>
+            ))}
+          </select>
+        </div>
+      )}
+
+      <div className="flex flex-1 flex-col gap-0.5 overflow-y-auto">
+        {filtered.length === 0 ? (
+          <p className="px-3 py-6 text-center text-xs" style={{ color: 'var(--color-muted)' }}>
+            {activeFilter ? 'No documents with this tag.' : 'No documents yet.'}
+          </p>
+        ) : (
+          filtered.map((doc) => (
+            <DocListItem
+              key={doc.id}
+              doc={doc}
+              active={doc.id === selectedId}
+              roster={roster}
+              onSelect={() => onSelect(doc.id)}
+              onDelete={() => onDelete(doc.id)}
+              onDuplicate={() => onDuplicate(doc.id)}
+              onToggleTag={onToggleTag}
+              onCreateTag={onCreateTag}
+            />
+          ))
+        )}
+      </div>
+
+      {/* Whole-corpus backup — "download all my writing". Plain download links so
+          the browser saves the zip; no extra app state needed. */}
+      {docs.length > 0 && (
+        <div
+          className="flex items-center gap-2 px-1 pt-1 text-xs"
+          style={{ color: 'var(--color-muted)', borderTop: '1px solid var(--color-border)' }}
+        >
+          <span className="font-semibold">备份 · Back up all:</span>
+          <a href={api.exportAllUrl('docx')} download className="font-bold hover:underline" style={{ color: 'var(--color-accent-hover)' }}>
+            Word
+          </a>
+          <a href={api.exportAllUrl('md')} download className="font-bold hover:underline" style={{ color: 'var(--color-accent-hover)' }}>
+            Markdown
+          </a>
+        </div>
+      )}
+    </aside>
+  )
+}

web/src/components/DocList/DocListItem.tsx

@@ -0,0 +1,116 @@
+import { useState } from 'react'
+import type { DocSummary, Tag, TagColor } from '../../api/client'
+import { TagChip } from './TagChip'
+import { TagPicker } from './TagPicker'
+
+interface Props {
+  doc: DocSummary
+  active: boolean
+  roster: Tag[]
+  onSelect: () => void
+  onDelete: () => void
+  onDuplicate: () => void
+  onToggleTag: (docId: string, tag: Tag) => void
+  onCreateTag: (docId: string, name: string, color: TagColor) => void
+}
+
+// One row in the sidebar: title + word count, its tag chips, a tag affordance and
+// a delete affordance on hover, and a rose wash when it's the open document.
+export function DocListItem({
+  doc,
+  active,
+  roster,
+  onSelect,
+  onDelete,
+  onDuplicate,
+  onToggleTag,
+  onCreateTag,
+}: Props) {
+  const [picking, setPicking] = useState(false)
+  const assignedIds = new Set(doc.tags.map((t) => t.id))
+
+  return (
+    <div
+      onClick={onSelect}
+      className="group relative flex cursor-pointer flex-col gap-1 px-3 py-2.5"
+      style={{
+        borderRadius: 'var(--radius-card)',
+        background: active ? 'var(--color-surface)' : 'transparent',
+        boxShadow: active ? 'var(--shadow-soft)' : 'none',
+      }}
+    >
+      <div className="flex items-center gap-2">
+        <div className="min-w-0 flex-1">
+          <div
+            className="truncate text-sm font-semibold"
+            style={{ color: active ? 'var(--color-plum)' : 'var(--color-muted)' }}
+          >
+            {doc.title || 'Untitled'}
+          </div>
+          <div className="text-xs" style={{ color: 'var(--color-muted)' }}>
+            {doc.word_count} {doc.word_count === 1 ? 'word' : 'words'}
+          </div>
+        </div>
+
+        {/* Tag + delete affordances: always reachable on touch (no hover), fade in
+            on hover for the pointer experience. */}
+        <button
+          type="button"
+          aria-label="Tag document"
+          title="Tags"
+          onClick={(e) => {
+            e.stopPropagation()
+            setPicking((v) => !v)
+          }}
+          className="petal-row-action flex h-7 w-7 shrink-0 items-center justify-center text-sm"
+          style={{ borderRadius: 'var(--radius-pill)', color: 'var(--color-muted)' }}
+        >
+          🏷️
+        </button>
+        <button
+          type="button"
+          aria-label="Duplicate document"
+          title="副本 · Duplicate"
+          onClick={(e) => {
+            e.stopPropagation()
+            onDuplicate()
+          }}
+          className="petal-row-action flex h-7 w-7 shrink-0 items-center justify-center text-sm"
+          style={{ borderRadius: 'var(--radius-pill)', color: 'var(--color-muted)' }}
+        >
+          ⧉
+        </button>
+        <button
+          type="button"
+          aria-label="Delete document"
+          onClick={(e) => {
+            e.stopPropagation()
+            onDelete()
+          }}
+          className="petal-row-action flex h-7 w-7 shrink-0 items-center justify-center text-base"
+          style={{ borderRadius: 'var(--radius-pill)', color: 'var(--color-muted)' }}
+        >
+          ×
+        </button>
+
+        {picking && (
+          <TagPicker
+            roster={roster}
+            assignedIds={assignedIds}
+            onToggle={(t) => onToggleTag(doc.id, t)}
+            onCreate={(name, color) => onCreateTag(doc.id, name, color)}
+            onClose={() => setPicking(false)}
+          />
+        )}
+      </div>
+
+      {doc.tags.length > 0 && (
+        <div className="flex flex-wrap gap-1">
+          {doc.tags.map((t) => (
+            <TagChip key={t.id} tag={t} onRemove={() => onToggleTag(doc.id, t)} />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

web/src/components/DocList/SearchBox.tsx

@@ -0,0 +1,145 @@
+import { useEffect, useRef, useState } from 'react'
+import { api, splitSnippet, type SearchResult } from '../../api/client'
+
+interface Props {
+  // Called when a result is chosen — opens that document.
+  onSelect: (id: string) => void
+}
+
+const DEBOUNCE_MS = 220
+
+// SearchBox is the cross-document finder at the top of the sidebar. Typing
+// debounces a full-text query; results drop in below with a highlighted snippet.
+// Clearing (× or empty) returns the sidebar to the normal document list.
+export function SearchBox({ onSelect }: Props) {
+  const [q, setQ] = useState('')
+  const [results, setResults] = useState<SearchResult[] | null>(null)
+  const [busy, setBusy] = useState(false)
+  const runRef = useRef(0)
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  useEffect(() => {
+    clearTimeout(debounceRef.current)
+    const term = q.trim()
+    if (!term) {
+      setResults(null)
+      setBusy(false)
+      return
+    }
+    setBusy(true)
+    const run = ++runRef.current
+    debounceRef.current = setTimeout(async () => {
+      try {
+        const hits = await api.search(term)
+        if (run === runRef.current) setResults(hits)
+      } catch (err) {
+        console.error('search failed', err)
+        if (run === runRef.current) setResults([])
+      } finally {
+        if (run === runRef.current) setBusy(false)
+      }
+    }, DEBOUNCE_MS)
+    return () => clearTimeout(debounceRef.current)
+  }, [q])
+
+  const clear = () => {
+    setQ('')
+    setResults(null)
+  }
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="relative">
+        <span
+          aria-hidden
+          className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm"
+          style={{ color: 'var(--color-muted)' }}
+        >
+          🔍
+        </span>
+        <input
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          placeholder="搜索 · Search"
+          aria-label="Search documents"
+          className="petal-tap w-full bg-transparent pl-9 pr-8 text-sm focus:outline-none"
+          style={{
+            height: 40,
+            borderRadius: 'var(--radius-pill)',
+            border: '1px solid var(--color-border)',
+            background: 'var(--color-surface)',
+            color: 'var(--color-plum)',
+          }}
+        />
+        {q && (
+          <button
+            type="button"
+            aria-label="Clear search"
+            onClick={clear}
+            className="absolute right-2 top-1/2 flex h-6 w-6 -translate-y-1/2 items-center justify-center"
+            style={{ borderRadius: 'var(--radius-pill)', color: 'var(--color-muted)' }}
+          >
+            ×
+          </button>
+        )}
+      </div>
+
+      {results !== null && (
+        <div className="petal-search-results flex flex-col gap-0.5">
+          {busy && results.length === 0 ? (
+            <p className="px-2 py-3 text-center text-xs" style={{ color: 'var(--color-muted)' }}>
+              查找中… · Searching…
+            </p>
+          ) : results.length === 0 ? (
+            <p className="px-2 py-3 text-center text-xs" style={{ color: 'var(--color-muted)' }}>
+              没有找到 · No matches
+            </p>
+          ) : (
+            results.map((r) => (
+              <button
+                key={r.id}
+                type="button"
+                onClick={() => onSelect(r.id)}
+                className="petal-tap flex flex-col items-start gap-0.5 px-3 py-2 text-left"
+                style={{ borderRadius: 'var(--radius-card)' }}
+                onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+                onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+              >
+                <span
+                  className="w-full truncate text-sm font-bold"
+                  style={{ color: 'var(--color-plum)' }}
+                >
+                  {r.title || 'Untitled'}
+                </span>
+                {r.snippet && (
+                  <span
+                    className="line-clamp-2 text-xs"
+                    style={{ color: 'var(--color-muted)', lineHeight: 1.4 }}
+                  >
+                    {splitSnippet(r.snippet).map((seg, i) =>
+                      seg.hit ? (
+                        <mark
+                          key={i}
+                          style={{
+                            background: 'color-mix(in srgb, var(--color-accent) 35%, white)',
+                            color: 'var(--color-plum)',
+                            borderRadius: 3,
+                            padding: '0 1px',
+                          }}
+                        >
+                          {seg.text}
+                        </mark>
+                      ) : (
+                        <span key={i}>{seg.text}</span>
+                      ),
+                    )}
+                  </span>
+                )}
+              </button>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

web/src/components/DocList/TagChip.tsx

@@ -0,0 +1,75 @@
+import { tagColorVar, type Tag } from '../../api/client'
+
+interface Props {
+  tag: Tag
+  // When set, renders an interactive chip (filter toggle); `active` fills it.
+  onClick?: () => void
+  active?: boolean
+  // When set, shows a small × to remove the tag (used on document rows).
+  onRemove?: () => void
+  // Optional trailing count (used in the filter bar).
+  count?: number
+  size?: 'sm' | 'md'
+}
+
+// TagChip is the pill used everywhere a tag appears: on document rows, in the
+// filter bar, and in the assign popover. The palette color tints a soft wash; a
+// filled variant marks an active filter. Keeps tap targets comfortable on touch.
+export function TagChip({ tag, onClick, active, onRemove, count, size = 'sm' }: Props) {
+  const color = tagColorVar(tag.color)
+  const interactive = !!onClick
+  const pad = size === 'md' ? '0.3rem 0.7rem' : '0.12rem 0.5rem'
+  const font = size === 'md' ? '0.8rem' : '0.7rem'
+
+  return (
+    <span
+      onClick={
+        onClick
+          ? (e) => {
+              e.stopPropagation()
+              onClick()
+            }
+          : undefined
+      }
+      className={`petal-tag-chip inline-flex items-center gap-1 whitespace-nowrap font-bold${interactive ? ' cursor-pointer' : ''}`}
+      style={{
+        borderRadius: 'var(--radius-pill)',
+        padding: pad,
+        fontSize: font,
+        lineHeight: 1.2,
+        background: active ? color : 'color-mix(in srgb, ' + color + ' 22%, white)',
+        color: active ? 'white' : 'var(--color-plum)',
+        border: `1px solid ${active ? color : 'color-mix(in srgb, ' + color + ' 45%, white)'}`,
+      }}
+    >
+      <span
+        aria-hidden
+        className="inline-block shrink-0"
+        style={{
+          width: 7,
+          height: 7,
+          borderRadius: 'var(--radius-pill)',
+          background: active ? 'white' : color,
+        }}
+      />
+      {tag.name}
+      {typeof count === 'number' && (
+        <span style={{ opacity: 0.7, fontWeight: 700 }}>{count}</span>
+      )}
+      {onRemove && (
+        <button
+          type="button"
+          aria-label={`Remove ${tag.name}`}
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove()
+          }}
+          className="ml-0.5 inline-flex items-center justify-center"
+          style={{ color: 'inherit', opacity: 0.65, fontSize: '0.85em', lineHeight: 1 }}
+        >
+          ×
+        </button>
+      )}
+    </span>
+  )
+}

web/src/components/DocList/TagPicker.tsx

@@ -0,0 +1,139 @@
+import { useEffect, useRef, useState } from 'react'
+import { tagColorVar, type Tag, type TagColor } from '../../api/client'
+
+const COLORS: TagColor[] = ['rose', 'mint', 'peach', 'lavender', 'sky', 'honey']
+
+interface Props {
+  roster: Tag[]
+  assignedIds: Set<string>
+  onToggle: (tag: Tag) => void
+  onCreate: (name: string, color: TagColor) => void
+  onClose: () => void
+}
+
+// TagPicker is the small popover for managing one document's tags: tap an
+// existing tag to attach/detach it, or type a new name (with a color swatch) to
+// create-and-attach. Closes on outside click or Escape.
+export function TagPicker({ roster, assignedIds, onToggle, onCreate, onClose }: Props) {
+  const [name, setName] = useState('')
+  const [color, setColor] = useState<TagColor>('rose')
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onDown = (e: PointerEvent) => {
+      if (!ref.current?.contains(e.target as Node)) onClose()
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    // Defer so the opening click doesn't immediately close it.
+    const id = setTimeout(() => document.addEventListener('pointerdown', onDown), 0)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      clearTimeout(id)
+      document.removeEventListener('pointerdown', onDown)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [onClose])
+
+  const submit = () => {
+    const n = name.trim()
+    if (!n) return
+    onCreate(n, color)
+    setName('')
+  }
+
+  return (
+    <div
+      ref={ref}
+      onClick={(e) => e.stopPropagation()}
+      className="petal-tag-picker absolute z-20 flex w-60 flex-col gap-2 p-3"
+      style={{
+        top: 'calc(100% + 4px)',
+        right: 0,
+        borderRadius: 'var(--radius-card)',
+        background: 'var(--color-surface)',
+        boxShadow: 'var(--shadow-soft)',
+        border: '1px solid var(--color-border)',
+      }}
+    >
+      <div className="text-xs font-bold" style={{ color: 'var(--color-muted)' }}>
+        标签 · Tags
+      </div>
+
+      {roster.length > 0 && (
+        <div className="flex max-h-40 flex-wrap gap-1.5 overflow-y-auto">
+          {roster.map((t) => {
+            const on = assignedIds.has(t.id)
+            const c = tagColorVar(t.color)
+            return (
+              <button
+                key={t.id}
+                type="button"
+                onClick={() => onToggle(t)}
+                className="petal-tap inline-flex items-center gap-1 whitespace-nowrap text-xs font-bold"
+                style={{
+                  borderRadius: 'var(--radius-pill)',
+                  padding: '0.25rem 0.6rem',
+                  background: on ? c : 'color-mix(in srgb, ' + c + ' 18%, white)',
+                  color: on ? 'white' : 'var(--color-plum)',
+                  border: `1px solid ${on ? c : 'color-mix(in srgb, ' + c + ' 40%, white)'}`,
+                }}
+              >
+                {on && <span aria-hidden>✓</span>}
+                {t.name}
+              </button>
+            )
+          })}
+        </div>
+      )}
+
+      <div className="flex flex-col gap-1.5 pt-1" style={{ borderTop: '1px solid var(--color-border)' }}>
+        <div className="flex items-center gap-1.5">
+          {COLORS.map((c) => (
+            <button
+              key={c}
+              type="button"
+              aria-label={`Color ${c}`}
+              onClick={() => setColor(c)}
+              className="petal-tap-sm"
+              style={{
+                width: 18,
+                height: 18,
+                borderRadius: 'var(--radius-pill)',
+                background: tagColorVar(c),
+                border: color === c ? '2px solid var(--color-plum)' : '2px solid transparent',
+              }}
+            />
+          ))}
+        </div>
+        <div className="flex items-center gap-1.5">
+          <input
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') submit()
+            }}
+            placeholder="新标签 · New tag"
+            aria-label="New tag name"
+            className="petal-tap min-w-0 flex-1 bg-transparent px-2.5 text-sm focus:outline-none"
+            style={{
+              height: 34,
+              borderRadius: 'var(--radius-input)',
+              border: '1px solid var(--color-border)',
+              color: 'var(--color-plum)',
+            }}
+          />
+          <button
+            type="button"
+            onClick={submit}
+            className="petal-tap-sm shrink-0 px-3 text-sm font-bold text-white"
+            style={{ height: 34, borderRadius: 'var(--radius-pill)', background: 'var(--color-accent)' }}
+          >
+            ＋
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

web/src/components/Editor/AskPetal.tsx

@@ -0,0 +1,195 @@
+import { useEffect, useRef, useState } from 'react'
+import { api, streamSuggestionChat, type ChatMessage } from '../../api/client'
+
+interface Props {
+  suggestionId: string
+  // The English explanation (shown in the card body). Petal's opening bubble is
+  // its Simplified-Chinese translation, fetched on open — so the panel doesn't
+  // just repeat the same English text twice. Falls back to this on failure.
+  explanation: string
+}
+
+// CJK fallback stack — Nunito has no Chinese glyphs, and the user asks questions
+// in Mandarin (spec Note #17). Applied to the bubbles specifically, not the
+// serif editor body.
+const CHAT_FONT = "'Nunito', 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', sans-serif"
+
+// AskPetal is the mini chat panel inside an expanded SuggestionCard. The whole
+// conversation lives in this component's state — nothing is persisted; closing
+// the card (unmounting) clears it. Each send streams Petal's reply token-by-
+// token into the latest assistant bubble.
+export function AskPetal({ suggestionId, explanation }: Props) {
+  // Opening bubble starts empty (caret-only) and fills with the Mandarin
+  // translation once it lands; `seeding` drives that loading caret.
+  const [messages, setMessages] = useState<ChatMessage[]>([{ role: 'assistant', content: '' }])
+  const [seeding, setSeeding] = useState(true)
+  const [input, setInput] = useState('')
+  const [streaming, setStreaming] = useState(false)
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  // Keep the latest bubble in view as tokens arrive.
+  useEffect(() => {
+    const el = scrollRef.current
+    if (el) el.scrollTop = el.scrollHeight
+  }, [messages])
+
+  // Focus the input when the panel opens. preventScroll: the card is already on
+  // screen as an absolutely-positioned overlay, and a default focus() would make
+  // the browser scroll its ancestor to "reveal" the input — jumping the document
+  // to the top.
+  useEffect(() => {
+    inputRef.current?.focus({ preventScroll: true })
+  }, [])
+
+  // Fetch the Chinese translation of the explanation to seed the first bubble.
+  // Only replaces the seed bubble if the user hasn't started chatting yet (the
+  // conversation always opens with this one assistant turn). Falls back to the
+  // English explanation if the translation can't be fetched.
+  useEffect(() => {
+    let cancelled = false
+    api
+      .translateSuggestion(suggestionId)
+      .then((res) => {
+        if (cancelled) return
+        const text = res.translation.trim() || explanation
+        setMessages((prev) => (prev.length === 1 ? [{ role: 'assistant', content: text }] : prev))
+      })
+      .catch(() => {
+        if (cancelled) return
+        setMessages((prev) => (prev.length === 1 ? [{ role: 'assistant', content: explanation }] : prev))
+      })
+      .finally(() => {
+        if (!cancelled) setSeeding(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [suggestionId, explanation])
+
+  async function send() {
+    const text = input.trim()
+    if (!text || streaming) return
+    setInput('')
+
+    // Append the user turn plus an empty assistant bubble to stream into.
+    const history: ChatMessage[] = [...messages, { role: 'user', content: text }]
+    setMessages([...history, { role: 'assistant', content: '' }])
+    setStreaming(true)
+
+    try {
+      await streamSuggestionChat(suggestionId, history, (token) => {
+        setMessages((prev) => {
+          const next = prev.slice()
+          const last = next[next.length - 1]
+          next[next.length - 1] = { ...last, content: last.content + token }
+          return next
+        })
+      })
+    } catch (err) {
+      setMessages((prev) => {
+        const next = prev.slice()
+        next[next.length - 1] = {
+          role: 'assistant',
+          content: 'Sorry, I had trouble responding just now. Please try again. 🌸',
+        }
+        return next
+      })
+      console.error('Ask Petal chat failed:', err)
+    } finally {
+      setStreaming(false)
+      inputRef.current?.focus({ preventScroll: true })
+    }
+  }
+
+  return (
+    <div
+      className="mt-3 flex flex-col"
+      style={{
+        borderTop: '1px solid var(--color-border)',
+        paddingTop: '0.625rem',
+        fontFamily: CHAT_FONT,
+      }}
+    >
+      <div
+        ref={scrollRef}
+        className="flex flex-col gap-2 overflow-y-auto pr-1"
+        style={{ maxHeight: 220 }}
+      >
+        {messages.map((m, i) => (
+          <Bubble
+            key={i}
+            role={m.role}
+            content={m.content}
+            streaming={(streaming && i === messages.length - 1) || (seeding && i === 0)}
+          />
+        ))}
+      </div>
+
+      <form
+        className="mt-2 flex items-center gap-1.5"
+        onSubmit={(e) => {
+          e.preventDefault()
+          void send()
+        }}
+      >
+        <input
+          ref={inputRef}
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Ask why… / 问为什么…"
+          className="min-w-0 flex-1 rounded-full px-3 py-1.5 text-xs focus:outline-none"
+          style={{
+            background: 'var(--color-surface-alt)',
+            border: '1px solid var(--color-border)',
+            color: 'var(--color-plum)',
+            fontFamily: CHAT_FONT,
+          }}
+        />
+        <button
+          type="submit"
+          disabled={streaming || input.trim() === ''}
+          className="rounded-full px-3 py-1.5 text-xs font-bold text-white disabled:opacity-50"
+          style={{ background: 'var(--color-accent)' }}
+        >
+          Send
+        </button>
+      </form>
+    </div>
+  )
+}
+
+// Bubble renders one chat turn: Petal rose-tinted and left-aligned, the user
+// lavender and right-aligned. A trailing caret marks the actively streaming
+// reply until its first token lands.
+function Bubble({
+  role,
+  content,
+  streaming,
+}: {
+  role: ChatMessage['role']
+  content: string
+  streaming: boolean
+}) {
+  const isPetal = role === 'assistant'
+  return (
+    <div className={`flex ${isPetal ? 'justify-start' : 'justify-end'}`}>
+      <div
+        className="max-w-[85%] rounded-2xl px-3 py-1.5 text-xs leading-snug"
+        style={{
+          background: isPetal ? 'var(--color-surface-alt)' : 'var(--color-lavender)',
+          color: 'var(--color-plum)',
+          fontFamily: CHAT_FONT,
+          whiteSpace: 'pre-wrap',
+        }}
+      >
+        {content}
+        {streaming && content === '' && (
+          <span className="petal-chat-caret" aria-hidden>
+            ▍
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}

web/src/components/Editor/FindReplace.tsx

@@ -0,0 +1,238 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { Editor } from '@tiptap/react'
+import { clearSearch, getSearchState, setActive, setSearch } from './SearchHighlight'
+
+// FindReplace is the in-document search bar (Ctrl/Cmd+F). It drives the
+// SearchHighlight decoration layer: typing updates the highlighted matches, the
+// arrows step through them (scrolling each into view), and replace / replace-all
+// edit the document in place. Bilingual, zh-first, matching the editor chrome.
+
+interface Props {
+  editor: Editor
+  onClose: () => void
+}
+
+const CJK = "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+
+// Scroll the active match into the middle of the viewport without moving the
+// selection (which would otherwise pop the rewrite bubble).
+function scrollToActive(editor: Editor) {
+  const st = getSearchState(editor.state)
+  if (st.active < 0) return
+  const m = st.matches[st.active]
+  const dom = editor.view.domAtPos(m.from)
+  const el = dom.node.nodeType === Node.TEXT_NODE ? dom.node.parentElement : (dom.node as HTMLElement)
+  el?.scrollIntoView({ block: 'center', behavior: 'smooth' })
+}
+
+export function FindReplace({ editor, onClose }: Props) {
+  const [query, setQuery] = useState('')
+  const [replacement, setReplacement] = useState('')
+  const [caseSensitive, setCaseSensitive] = useState(false)
+  const [showReplace, setShowReplace] = useState(false)
+  // Mirror of the plugin's match count + active index for the "n / m" readout.
+  const [{ count, active }, setCounts] = useState({ count: 0, active: -1 })
+  const findRef = useRef<HTMLInputElement>(null)
+
+  const sync = useCallback(() => {
+    const st = getSearchState(editor.state)
+    setCounts({ count: st.matches.length, active: st.active })
+  }, [editor])
+
+  // Push the query into the decoration layer whenever it (or case-sensitivity)
+  // changes, then jump to the first match.
+  useEffect(() => {
+    setSearch(editor.state, editor.view.dispatch, query, caseSensitive)
+    sync()
+    scrollToActive(editor)
+  }, [editor, query, caseSensitive, sync])
+
+  // Tear the highlight layer down when the bar closes.
+  useEffect(() => () => clearSearch(editor.state, editor.view.dispatch), [editor])
+
+  // Focus the find field on open.
+  useEffect(() => {
+    findRef.current?.focus()
+    findRef.current?.select()
+  }, [])
+
+  const go = useCallback(
+    (delta: number) => {
+      const st = getSearchState(editor.state)
+      if (!st.matches.length) return
+      setActive(editor.state, editor.view.dispatch, st.active + delta)
+      sync()
+      scrollToActive(editor)
+    },
+    [editor, sync],
+  )
+
+  const replaceActive = useCallback(() => {
+    const st = getSearchState(editor.state)
+    if (st.active < 0) return
+    const m = st.matches[st.active]
+    const tr = editor.state.tr
+    if (replacement) tr.insertText(replacement, m.from, m.to)
+    else tr.delete(m.from, m.to)
+    editor.view.dispatch(tr)
+    sync()
+    scrollToActive(editor)
+  }, [editor, replacement, sync])
+
+  const replaceAll = useCallback(() => {
+    const st = getSearchState(editor.state)
+    if (!st.matches.length) return
+    const tr = editor.state.tr
+    // Apply back-to-front so earlier edits don't shift later match positions.
+    for (let i = st.matches.length - 1; i >= 0; i--) {
+      const m = st.matches[i]
+      if (replacement) tr.insertText(replacement, m.from, m.to)
+      else tr.delete(m.from, m.to)
+    }
+    editor.view.dispatch(tr)
+    sync()
+  }, [editor, replacement, sync])
+
+  const inputStyle: React.CSSProperties = {
+    borderRadius: 'var(--radius-input)',
+    border: '1px solid var(--color-border)',
+    color: 'var(--color-plum)',
+    fontFamily: CJK,
+  }
+
+  return (
+    <div
+      className="petal-no-print absolute right-2 top-2 z-40 flex flex-col gap-1.5 p-2"
+      role="dialog"
+      aria-label="Find and replace"
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') {
+          e.preventDefault()
+          onClose()
+        }
+      }}
+      style={{
+        width: 320,
+        background: 'var(--color-surface)',
+        border: '1px solid var(--color-border)',
+        borderRadius: 'var(--radius-card)',
+        boxShadow: 'var(--shadow-soft)',
+      }}
+    >
+      <div className="flex items-center gap-1.5">
+        <button
+          type="button"
+          onClick={() => setShowReplace((v) => !v)}
+          aria-label={showReplace ? 'Hide replace' : 'Show replace'}
+          title={showReplace ? 'Hide replace' : 'Show replace'}
+          className="flex h-8 w-6 items-center justify-center text-xs"
+          style={{ color: 'var(--color-muted)' }}
+        >
+          {showReplace ? '▾' : '▸'}
+        </button>
+        <input
+          ref={findRef}
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              go(e.shiftKey ? -1 : 1)
+            }
+          }}
+          placeholder="查找 · Find"
+          className="min-w-0 flex-1 px-2 py-1.5 text-sm focus:outline-none"
+          style={inputStyle}
+        />
+        <span
+          className="w-14 shrink-0 text-center text-xs tabular-nums"
+          style={{ color: 'var(--color-muted)' }}
+        >
+          {count ? `${active + 1} / ${count}` : query ? '无 · 0' : ''}
+        </span>
+        <FindBtn label="Previous match" disabled={!count} onClick={() => go(-1)}>↑</FindBtn>
+        <FindBtn label="Next match" disabled={!count} onClick={() => go(1)}>↓</FindBtn>
+        <FindBtn
+          label="Match case"
+          active={caseSensitive}
+          onClick={() => setCaseSensitive((v) => !v)}
+          title="Match case · 区分大小写"
+        >
+          Aa
+        </FindBtn>
+        <FindBtn label="Close" onClick={onClose} title="Close · 关闭">✕</FindBtn>
+      </div>
+
+      {showReplace && (
+        <div className="flex items-center gap-1.5 pl-7">
+          <input
+            value={replacement}
+            onChange={(e) => setReplacement(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                e.preventDefault()
+                replaceActive()
+              }
+            }}
+            placeholder="替换为 · Replace"
+            className="min-w-0 flex-1 px-2 py-1.5 text-sm focus:outline-none"
+            style={inputStyle}
+          />
+          <button
+            type="button"
+            onClick={replaceActive}
+            disabled={!count}
+            className="h-8 shrink-0 whitespace-nowrap px-2.5 text-xs font-semibold disabled:opacity-40"
+            style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+          >
+            替换
+          </button>
+          <button
+            type="button"
+            onClick={replaceAll}
+            disabled={!count}
+            className="h-8 shrink-0 whitespace-nowrap px-2.5 text-xs font-bold disabled:opacity-40"
+            style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-accent)', color: '#fff' }}
+          >
+            全部
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function FindBtn({
+  children,
+  onClick,
+  label,
+  title,
+  active,
+  disabled,
+}: {
+  children: React.ReactNode
+  onClick: () => void
+  label: string
+  title?: string
+  active?: boolean
+  disabled?: boolean
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={title ?? label}
+      aria-pressed={active}
+      disabled={disabled}
+      onClick={onClick}
+      className="flex h-8 min-w-8 items-center justify-center px-1.5 text-sm font-semibold disabled:opacity-40"
+      style={{
+        borderRadius: 'var(--radius-input)',
+        color: active ? 'var(--color-accent-hover)' : 'var(--color-muted)',
+        background: active ? 'var(--color-surface-alt)' : 'transparent',
+      }}
+    >
+      {children}
+    </button>
+  )
+}

web/src/components/Editor/FontSize.ts

@@ -0,0 +1,51 @@
+import { Extension } from '@tiptap/core'
+
+// FontSize adds a `fontSize` attribute to the textStyle mark so a writer can
+// pick a size preset (Small / Normal / Large / Title) from the toolbar. It rides
+// on TextStyle (already loaded) rather than introducing a new mark, so it stacks
+// cleanly with color and other inline styling.
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    fontSize: {
+      setFontSize: (size: string) => ReturnType
+      unsetFontSize: () => ReturnType
+    }
+  }
+}
+
+export const FontSize = Extension.create({
+  name: 'fontSize',
+
+  addOptions() {
+    return { types: ['textStyle'] }
+  },
+
+  addGlobalAttributes() {
+    return [
+      {
+        types: this.options.types,
+        attributes: {
+          fontSize: {
+            default: null,
+            parseHTML: (element) => element.style.fontSize || null,
+            renderHTML: (attributes) =>
+              attributes.fontSize ? { style: `font-size: ${attributes.fontSize}` } : {},
+          },
+        },
+      },
+    ]
+  },
+
+  addCommands() {
+    return {
+      setFontSize:
+        (size) =>
+        ({ chain }) =>
+          chain().setMark('textStyle', { fontSize: size }).run(),
+      unsetFontSize:
+        () =>
+        ({ chain }) =>
+          chain().setMark('textStyle', { fontSize: null }).removeEmptyTextStyle().run(),
+    }
+  },
+})

web/src/components/Editor/GlossTip.tsx

@@ -0,0 +1,32 @@
+// GlossTip is the inline hover gloss: rest the pointer on an English word and a
+// small bubble shows its Chinese meaning, pulled instantly from the offline
+// gloss dataset. It's a pure reading aid — pointer-events are off so it never
+// steals hover or blocks a click, and it sits just under the word. Bilingual
+// chrome elsewhere puts zh first; here the gloss IS the content (the word is
+// already on screen), so the bubble shows only the 中文.
+
+interface Props {
+  gloss: string
+  style: React.CSSProperties
+}
+
+export function GlossTip({ gloss, style }: Props) {
+  return (
+    <div
+      className="petal-gloss-tip pointer-events-none absolute z-20 px-2.5 py-1.5 text-sm"
+      role="tooltip"
+      style={{
+        maxWidth: 280,
+        background: 'var(--color-plum)',
+        color: 'var(--color-surface)',
+        borderRadius: 'var(--radius-input)',
+        boxShadow: 'var(--shadow-soft)',
+        lineHeight: 1.35,
+        fontFamily: "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif",
+        ...style,
+      }}
+    >
+      {gloss}
+    </div>
+  )
+}