Checkpoint: auto-retry after a failed pass; release rate-limit slot on failure

A paste fires exactly one grammar checkpoint, and a failed one never retried
until the next keystroke — stranding the writer on "Petal's helper is resting"
after a paste. Long docs make it worse: their 15-25s checks have a wide window
to catch a transient 502 from the shared Ollama (co-tenant apps load other
models and evict the 9B). A failed pass also burned the per-document rate-limit
slot, so a retry within 30s hit the throttle path and got an empty set back.

- llm.RateLimiter.Release rolls back a slot when its pass fails; Allow now
  returns the recorded timestamp so Release only frees its own slot.
- suggestions.runPass releases the slot on LLM failure before returning 502.
- useCheckpoint auto-retries a failed checkpoint with backoff (3/12/35s),
  keeping the breathing dot up and only flagging "resting" once retries exhaust.

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

@@ -74,12 +74,51 @@ Multi-session build. **Source of truth for what's done and what's next.** Update
 - [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}`.
+
 ### 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)
+
 ## Session log
+- 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.

cmd/server/main.go

@@ -15,9 +15,11 @@ import (
 	"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/web"
 )
 
@@ -62,15 +64,39 @@ func main() {
 
 		// Document CRUD plus the doc-scoped checkpoint/list suggestion routes,
 		// both under /api/docs.
-		docsRouter := docs.New(database).Routes()
+		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 word lookups (definition + synonyms) for the right-click popover.
-		api.Mount("/word", lexicon.NewHandler().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())
+
+		// 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).

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; }

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

@@ -176,6 +176,92 @@ CREATE INDEX idx_plagiarism_doc_id ON plagiarism_reports(doc_id);
 			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;
+`,
+		},
 	}
 }
 

internal/db/models.go

@@ -27,6 +27,53 @@ type Document struct {
 	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;

internal/docs/export.go

@@ -0,0 +1,900 @@
+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"
+)
+
+// 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 {
+		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 {
+			serverError(w, err)
+			return
+		}
+		body, err := format.render(doc)
+		if err != nil {
+			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 {
+			serverError(w, err)
+			return
+		}
+		if _, err := f.Write(body); err != nil {
+			serverError(w, err)
+			return
+		}
+	}
+	if err := rows.Err(); err != nil {
+		serverError(w, err)
+		return
+	}
+	if err := zw.Close(); err != nil {
+		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 {
+		serverError(w, err)
+		return
+	}
+
+	body, err := format.render(doc)
+	if err != nil {
+		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

@@ -7,6 +7,7 @@ import (
 	"database/sql"
 	"encoding/json"
 	"errors"
+	"log"
 	"net/http"
 
 	"github.com/go-chi/chi/v5"
@@ -33,19 +34,25 @@ func (h *Handler) Routes() chi.Router {
 	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.
+// 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"`
+	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.
+// 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
@@ -61,6 +68,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 	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 {
@@ -68,11 +76,24 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		out = append(out, d)
+		ids = append(ids, d.ID)
 	}
 	if err := rows.Err(); err != nil {
 		serverError(w, err)
 		return
 	}
+
+	byDoc, err := h.tagsByDoc(ids)
+	if err != nil {
+		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{}
+		}
+	}
 	writeJSON(w, http.StatusOK, out)
 }
 
@@ -155,6 +176,16 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 		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)
+		}
+	}
+
 	writeJSON(w, http.StatusOK, doc)
 }
 
@@ -208,3 +239,4 @@ func serverError(w http.ResponseWriter, err error) {
 
 func badRequest(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusBadRequest, msg) }
 func notFound(w http.ResponseWriter)               { errorJSON(w, http.StatusNotFound, "document not found") }
+func notFoundMsg(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusNotFound, msg) }

internal/docs/search.go

@@ -0,0 +1,261 @@
+package docs
+
+import (
+	"net/http"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// 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 == "" {
+		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 {
+			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 {
+				serverError(w, err)
+				return
+			}
+			rows = append(rows, rw)
+		}
+		if err := sqlRows.Err(); err != nil {
+			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 {
+			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 {
+				serverError(w, err)
+				return
+			}
+			rows = append(rows, rw)
+		}
+		if err := sqlRows.Err(); err != nil {
+			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 {
+		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{}
+		}
+	}
+	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,303 @@
+package docs
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// 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 {
+		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 {
+			serverError(w, err)
+			return
+		}
+		out = append(out, t)
+	}
+	if err := rows.Err(); err != nil {
+		serverError(w, err)
+		return
+	}
+	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 {
+		serverError(w, err)
+		return
+	}
+	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 {
+		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 {
+		serverError(w, err)
+		return
+	}
+	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 {
+		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 {
+		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 {
+		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,245 @@
+package docs
+
+import (
+	"database/sql"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+// 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 {
+		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 {
+			serverError(w, err)
+			return
+		}
+		out = append(out, v)
+	}
+	if err := rows.Err(); err != nil {
+		serverError(w, err)
+		return
+	}
+	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 {
+		serverError(w, err)
+		return
+	}
+	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 {
+		serverError(w, err)
+		return
+	}
+
+	v, err := h.insertVersion(doc, db.VersionKindManual)
+	if err != nil {
+		serverError(w, err)
+		return
+	}
+	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 {
+		serverError(w, err)
+		return
+	}
+
+	current, err := h.fetch(docID)
+	if err != nil {
+		serverError(w, err)
+		return
+	}
+	if _, err := h.insertVersion(current, db.VersionKindPreRestore); err != nil {
+		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 {
+		serverError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		notFound(w)
+		return
+	}
+
+	doc, err := h.fetch(docID)
+	if err != nil {
+		serverError(w, err)
+		return
+	}
+	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/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

@@ -1,9 +1,10 @@
-// Package lexicon serves offline word lookups — a definition and a list of
-// synonyms for a single word — from two public-domain 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. Both are gzipped JSON, decompressed
-// lazily on first use so a writer who never right-clicks a word pays nothing.
+// 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"
@@ -19,3 +20,19 @@ var definitionsGz []byte
 //
 //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

@@ -25,6 +25,15 @@ func (h *Handler) Routes() chi.Router {
 	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.
@@ -48,3 +57,25 @@ func (h *Handler) lookup(w http.ResponseWriter, r *http.Request) {
 	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

@@ -20,13 +20,25 @@ type Meaning struct {
 
 // 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.
+// 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.
@@ -44,6 +56,8 @@ type Lexicon struct {
 	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.
@@ -59,6 +73,14 @@ func (l *Lexicon) load() {
 			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
+		}
 	})
 }
 
@@ -78,6 +100,11 @@ func (l *Lexicon) Lookup(word string) (Result, error) {
 		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))
@@ -97,6 +124,32 @@ func (l *Lexicon) Lookup(word string) (Result, error) {
 	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.

internal/lexicon/lexicon_test.go

@@ -51,6 +51,48 @@ func TestLookupUnknownWord(t *testing.T) {
 	}
 }
 
+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",

internal/llm/checkpoint.go

@@ -127,17 +127,33 @@ func NewRateLimiter(interval time.Duration) *RateLimiter {
 }
 
 // Allow reports whether a checkpoint may run for docID now. When allowed it
-// records the time and returns (true, 0); when throttled it returns
-// (false, retryAfter) where retryAfter is the wait until the next allowed run.
-func (rl *RateLimiter) Allow(docID string) (bool, time.Duration) {
+// 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
+			return false, rl.interval - elapsed, time.Time{}
 		}
 	}
 	rl.last[docID] = now
-	return true, 0
+	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

@@ -65,16 +65,31 @@ func TestParseCheckpoint(t *testing.T) {
 func TestRateLimiter(t *testing.T) {
 	rl := NewRateLimiter(30 * time.Second)
 
-	if ok, _ := rl.Allow("doc1"); !ok {
+	ok, _, at := rl.Allow("doc1")
+	if !ok {
 		t.Fatal("first call should be allowed")
 	}
-	if ok, retry := rl.Allow("doc1"); ok || retry <= 0 {
+	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 {
+	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) {

internal/llm/prompts.go

@@ -120,3 +120,69 @@ Keep responses concise (2-4 sentences). This is a chat, not an essay. Be encoura
 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/suggestions/handlers.go

@@ -44,6 +44,7 @@ func New(database *db.DB, client llm.LLMClient) *Handler {
 func (h *Handler) RegisterDocRoutes(r chi.Router) {
 	r.Post("/{id}/check", h.check)
 	r.Post("/{id}/voice", h.voice)
+	r.Post("/{id}/rewrite", h.rewrite)
 	r.Get("/{id}/suggestions", h.listForDoc)
 }
 
@@ -54,6 +55,7 @@ func (h *Handler) Routes() chi.Router {
 	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
 }
 
@@ -100,7 +102,8 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 		return
 	}
 
-	if ok, _ := limiter.Allow(docID); !ok {
+	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)
@@ -114,6 +117,10 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 
 	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)
 		errorJSON(w, http.StatusBadGateway, "llm pass failed: "+err.Error())
 		return
 	}
@@ -153,6 +160,14 @@ var (
 // 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 the user already accepted or dismissed are suppressed from the
+// fresh batch: the model has no memory between passes, so without this it would
+// re-propose the identical edit on the very next checkpoint — re-nagging a
+// sentence the user already resolved. This matters most when an accept silently
+// no-ops (the `original` text couldn't be anchored in the editor, so the doc
+// never changed): the sentence is unaltered, yet the user shouldn't see the same
+// card again.
 func (h *Handler) replacePending(docID, contentText string, raw []llm.RawSuggestion, scope pendingScope) error {
 	tx, err := h.DB.Begin()
 	if err != nil {
@@ -167,7 +182,15 @@ func (h *Handler) replacePending(docID, contentText string, raw []llm.RawSuggest
 		return err
 	}
 
+	actioned, err := actionedKeys(tx, docID)
+	if err != nil {
+		return err
+	}
+
 	for _, s := range raw {
+		if _, seen := actioned[suggestionKey(s.Original, s.Replacement)]; seen {
+			continue
+		}
 		typ := scope.forceType
 		if typ == "" {
 			typ = normalizeType(s.Type)
@@ -185,6 +208,39 @@ func (h *Handler) replacePending(docID, contentText string, raw []llm.RawSuggest
 	return tx.Commit()
 }
 
+// actionedKeys returns the set of original→replacement keys the user has already
+// accepted or rejected for this document, so a fresh checkpoint can skip
+// re-proposing them. Keyed on the trimmed original+replacement pair, matching the
+// normalization ParseCheckpoint applies, so a genuinely different edit on the same
+// sentence is not suppressed.
+func actionedKeys(tx *sql.Tx, docID string) (map[string]struct{}, error) {
+	rows, err := tx.Query(
+		`SELECT original, replacement FROM suggestions
+		  WHERE doc_id = ? AND status IN (?, ?)`,
+		docID, db.SuggestionStatusAccepted, db.SuggestionStatusRejected,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	keys := make(map[string]struct{})
+	for rows.Next() {
+		var original, replacement string
+		if err := rows.Scan(&original, &replacement); err != nil {
+			return nil, err
+		}
+		keys[suggestionKey(original, replacement)] = struct{}{}
+	}
+	return keys, rows.Err()
+}
+
+// suggestionKey is the dedup identity for a suggestion: its trimmed original and
+// replacement text. Two suggestions with the same key are "the same edit."
+func suggestionKey(original, replacement string) string {
+	return strings.TrimSpace(original) + "\x00" + strings.TrimSpace(replacement)
+}
+
 // 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) {

internal/suggestions/handlers_test.go

@@ -127,6 +127,44 @@ func TestCheckpointFlow(t *testing.T) {
 	}
 }
 
+// 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)
+	}
+}
+
 // 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.

internal/suggestions/rewrite.go

@@ -0,0 +1,76 @@
+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/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 {
+		errorJSON(w, http.StatusBadRequest, "invalid request body")
+		return
+	}
+
+	text := strings.TrimSpace(body.Text)
+	if text == "" {
+		errorJSON(w, http.StatusBadRequest, "no text to rewrite")
+		return
+	}
+	if len([]rune(text)) > llm.RewriteMaxRunes {
+		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) {
+		errorJSON(w, http.StatusNotFound, "document not found")
+		return
+	}
+	if err != nil {
+		serverError(w, err)
+		return
+	}
+
+	out, err := llm.RunRewrite(r.Context(), h.Client, text, body.Style)
+	if err != nil {
+		errorJSON(w, http.StatusBadGateway, "rewrite failed: "+err.Error())
+		return
+	}
+
+	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,57 @@
+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/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) {
+		errorJSON(w, http.StatusNotFound, "suggestion not found")
+		return
+	}
+	if err != nil {
+		serverError(w, err)
+		return
+	}
+
+	explanation = strings.TrimSpace(explanation)
+	if explanation == "" {
+		writeJSON(w, http.StatusOK, translateResponse{Translation: ""})
+		return
+	}
+
+	out, err := llm.RunTranslate(r.Context(), h.Client, explanation)
+	if err != nil {
+		errorJSON(w, http.StatusBadGateway, "translate failed: "+err.Error())
+		return
+	}
+
+	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)))
+	}
+}

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,7 +9,15 @@
       "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",
@@ -28,7 +36,8 @@
         "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": {
@@ -1178,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",
@@ -1560,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",
@@ -1644,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",
@@ -1672,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",
@@ -1685,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",
@@ -1751,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",
@@ -1934,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",
@@ -2010,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",
@@ -2084,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",
@@ -2176,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",
@@ -2240,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",
@@ -2642,6 +2946,12 @@
         "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",
@@ -2746,12 +3056,33 @@
         "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",
@@ -3103,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",
@@ -3113,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",
@@ -3134,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",
@@ -3151,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",
@@ -3295,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,11 +6,21 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "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",
@@ -29,6 +39,7 @@
     "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/src/App.tsx

@@ -1,15 +1,20 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { api, type DocSummary, type Document, type Suggestion } from './api/client'
+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 { 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 { playSuggestionSound } from './audio/sounds'
 
 export default function App() {
   const updateAvailable = useVersionWatch()
@@ -25,30 +30,105 @@ export default function App() {
   // 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 [editorEpoch, setEditorEpoch] = useState(0)
+
+  // Live mirrors of the current doc's editable fields so the "discard blank
+  // drafts on navigation" logic can read the latest values without rebuilding
+  // callbacks on every keystroke.
+  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,
+    llmDown,
     schedule: scheduleCheckpoint,
     runVoice,
     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)
@@ -56,8 +136,14 @@ export default function App() {
       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],
+    [saveNow, isBlankDraft],
   )
 
   // Initial load: fetch the list, opening the first doc (or creating one).
@@ -70,7 +156,7 @@ export default function App() {
         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 }]
+          list = [{ id: fresh.id, title: fresh.title, word_count: 0, updated_at: fresh.updated_at, tags: [] }]
           setDocs(list)
           setCurrentDoc(fresh)
           setTitle(fresh.title)
@@ -90,10 +176,13 @@ export default function App() {
   }, [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 },
+      { id: fresh.id, title: fresh.title, word_count: 0, updated_at: fresh.updated_at, tags: [] },
       ...prev,
     ])
     setCurrentDoc(fresh)
@@ -101,7 +190,39 @@ export default function App() {
     setWordCount(0)
     setTone(fresh.tone || 'general')
     setDocText('')
-  }, [saveNow])
+  }, [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) => {
@@ -179,6 +300,21 @@ export default function App() {
     [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
@@ -207,28 +343,78 @@ export default function App() {
     [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">
+      <PetalFall />
       <header
         onMouseDown={handleChromeDown}
-        className="flex h-12 shrink-0 items-center gap-2 px-5"
+        className="petal-no-print flex h-12 shrink-0 items-center gap-2 px-5"
         style={{ borderBottom: '1px solid var(--color-border)' }}
       >
+        <button
+          type="button"
+          aria-label="Toggle document list"
+          onClick={() => {
+            setFocusMode(false)
+            setDrawerOpen((v) => !v)
+          }}
+          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)' }}
+        >
+          ☰
+        </button>
         <span className="text-xl">🌸</span>
         <span className="text-lg font-extrabold text-plum">Petal</span>
       </header>
 
-      <div className="flex min-h-0 flex-1">
-        <div className={`petal-sidebar shrink-0${focusMode ? ' petal-sidebar-hidden' : ''}`}>
+      <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}
           />
         </div>
 
+        <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 ? (
             <>
@@ -246,10 +432,32 @@ export default function App() {
                       className="min-w-0 flex-1 bg-transparent text-3xl font-extrabold text-plum focus:outline-none"
                       style={{ fontFamily: 'var(--font-ui)' }}
                     />
-                    <ToneSelect value={tone} onChange={handleToneChange} />
+                    <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}
+                    key={`${currentDoc.id}:${editorEpoch}`}
                     docId={currentDoc.id}
                     initialContent={currentDoc.content}
                     onChange={handleEditorChange}
@@ -264,13 +472,14 @@ export default function App() {
                   />
                 </div>
               </div>
-              <div onMouseDown={handleChromeDown}>
+              <div className="petal-no-print" onMouseDown={handleChromeDown}>
                 <StatusBar
                   wordCount={wordCount}
                   text={docText}
                   saveStatus={status}
                   checking={checking}
                   voicing={voicing}
+                  llmDown={llmDown}
                 />
               </div>
             </>
@@ -285,14 +494,26 @@ export default function App() {
         </main>
       </div>
 
+      {historyOpen && currentDoc && (
+        <HistoryPanel
+          docId={currentDoc.id}
+          onClose={() => setHistoryOpen(false)}
+          onRestored={handleRestored}
+        />
+      )}
+
       {updateAvailable && <UpdateBanner />}
 
-      <PetalCompanion
-        wordCount={wordCount}
-        saveStatus={status}
-        editTick={editTick}
-        acceptTick={acceptTick}
-      />
+      <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

@@ -1,11 +1,34 @@
 // 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 {
@@ -37,16 +60,41 @@ export interface WordMeaning {
   example?: string
 }
 
-// The offline lookup for one word: a few definition senses and a list of
-// synonyms. Either list may be empty when the word isn't a headword.
+// 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'
 
+// 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
@@ -99,15 +147,133 @@ export const api = {
     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' }),
 
-  // Offline word lookup (definition + synonyms) for the right-click popover.
+  // 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' }),
 
   // 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 {

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,104 @@
+// 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
+
+function stopCurrent(): void {
+  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)
+}
+
+// speak reads `text` aloud, cancelling anything already in flight so rapid taps
+// don't queue up. `lang` defaults to US English (the language she's learning);
+// pass a zh locale to hear a Chinese passage. 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 = 'en-US'): void {
+  if (!text.trim()) return
+  stopCurrent()
+  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

@@ -11,6 +11,8 @@ interface Props {
   animationData?: object
   loop?: boolean
   className?: string
+  // Mirror the animation left↔right (for assets drawn facing the wrong way).
+  flip?: boolean
   fallback: React.ReactNode
 }
 
@@ -48,7 +50,7 @@ function fitToContent(anim: AnimationItem, svg: SVGSVGElement) {
 // 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, fallback }: Props) {
+export function LottiePlayer({ animationData, loop = true, className, flip, fallback }: Props) {
   const ref = useRef<HTMLDivElement>(null)
   const anim = useRef<AnimationItem | null>(null)
 
@@ -74,5 +76,12 @@ export function LottiePlayer({ animationData, loop = true, className, fallback }
   }, [animationData, loop])
 
   if (!animationData) return <>{fallback}</>
-  return <div ref={ref} className={className} aria-hidden />
+  return (
+    <div
+      ref={ref}
+      className={className}
+      style={flip ? { transform: 'scaleX(-1)' } : undefined}
+      aria-hidden
+    />
+  )
 }

web/src/components/Companion/PetalCompanion.tsx

@@ -7,8 +7,10 @@ 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.
@@ -26,8 +28,15 @@ const STORAGE_KEY = 'petal.companion'
 // 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, editTick, acceptTick }: Props) {
-  const { mood, bubble, dismiss } = useCompanion({ wordCount, saveStatus, editTick, acceptTick })
+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 {
@@ -136,7 +145,9 @@ export function PetalCompanion({ wordCount, saveStatus, editTick, acceptTick }:
         <div
           role="status"
           onClick={dismiss}
-          className="petal-bubble pointer-events-auto max-w-[260px] cursor-pointer p-3 pr-3.5"
+          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)',
@@ -147,10 +158,16 @@ export function PetalCompanion({ wordCount, saveStatus, editTick, acceptTick }:
           }}
           title="Click to dismiss"
         >
-          <p className="text-sm font-bold leading-snug" style={{ color: 'var(--color-plum)' }}>
+          <p
+            className="font-bold leading-snug"
+            style={{ color: 'var(--color-plum)', fontSize: '1.4rem' }}
+          >
             {bubble.zh}
           </p>
-          <p className="mt-0.5 text-xs leading-snug" style={{ color: 'var(--color-muted)' }}>
+          <p
+            className="mt-0.5 leading-snug"
+            style={{ color: 'var(--color-muted)', fontSize: '1.15rem' }}
+          >
             {bubble.en}
           </p>
         </div>
@@ -163,8 +180,9 @@ export function PetalCompanion({ wordCount, saveStatus, editTick, acceptTick }:
         aria-label="Choose a companion"
         className={`petal-companion pointer-events-auto select-none ${napping ? 'petal-companion-sleep' : ''}`}
         style={{
-          width: 144,
-          height: 144,
+          // 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)',
@@ -178,8 +196,13 @@ export function PetalCompanion({ wordCount, saveStatus, editTick, acceptTick }:
         <LottiePlayer
           key={companion.id}
           animationData={animationData}
-          className="h-32 w-32"
-          fallback={<span style={{ fontSize: 72, lineHeight: 1 }}>{MOOD_EMOJI[renderMood]}</span>}
+          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)' }}>

web/src/components/Companion/companions.ts

@@ -1,6 +1,9 @@
 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
@@ -12,6 +15,9 @@ export interface Companion {
   // 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
@@ -44,6 +50,43 @@ export const COMPANIONS: Companion[] = [
       // 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,250 @@
+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')
+  })
+})

web/src/components/Companion/prose.ts

@@ -0,0 +1,577 @@
+// 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.
+
+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
+}
+
+// ── 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)
+}
+
+// ── individual rules ────────────────────────────────────────────────────────
+// Each rule pushes at most a couple of findings; the caller shows one at a time.
+
+// Run-on / overly long sentences — the single most common readability problem
+// for ESL writers, who often chain clauses that a period would serve better.
+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.
+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).
+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.
+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 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 = /\ba\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 = /\ban\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
+  let found = 0
+  A_BEFORE_VOWEL_RE.lastIndex = 0
+  while ((m = A_BEFORE_VOWEL_RE.exec(text)) && found < 1) {
+    if (CONSONANT_SOUND_RE.test(m[1])) continue
+    found++
+    out.push({
+      id: `article-an:${key(m[1])}`,
+      rule: 'article',
+      zh: `元音开头的词前用 “an”：“an ${m[1]}”。`,
+      en: `Before a vowel sound, use “an”: “an ${m[1]}”.`,
+    })
+  }
+  AN_BEFORE_CONSONANT_RE.lastIndex = 0
+  while ((m = AN_BEFORE_CONSONANT_RE.exec(text)) && found < 2) {
+    if (VOWEL_SOUND_RE.test(m[1])) continue
+    found++
+    out.push({
+      id: `article-a:${key(m[1])}`,
+      rule: 'article',
+      zh: `辅音开头的词前用 “a”：“a ${m[1]}”。`,
+      en: `Before a consonant sound, use “a”: “a ${m[1]}”.`,
+    })
+  }
+}
+
+// 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
+  let found = 0
+  DOUBLE_RE.lastIndex = 0
+  while ((m = DOUBLE_RE.exec(text)) && found < 1) {
+    const w = m[1].toLowerCase()
+    if (LEGIT_DOUBLES.has(w)) continue
+    found++
+    out.push({
+      id: `double:${key(m[0])}`,
+      rule: 'double',
+      zh: `“${m[1]}” 好像写了两遍，检查一下哦。`,
+      en: `“${m[1]} ${m[1]}” — looks like a word got doubled.`,
+    })
+  }
+}
+
+// Lowercase standalone “I”. Conservative: only when bounded by spaces / line
+// edge, to avoid tangling with “i.e.” and the like.
+const LOWER_I_RE = /(?:^|\s)i(?=\s|$)/m
+
+function pronounI(text: string, out: ProseHint[]) {
+  if (LOWER_I_RE.test(text)) {
+    out.push({
+      id: 'cap-i',
+      rule: 'cap-i',
+      zh: '英文里的 “I”（我）任何时候都要大写哦。',
+      en: 'In English, “I” is always written as a capital letter.',
+    })
+  }
+}
+
+// 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).
+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.',
+    })
+  }
+}
+
+// A stray space *before* punctuation (a common habit carried from CJK spacing).
+const SPACE_BEFORE_PUNCT_RE = /[A-Za-z] +([,;:!?]|\.(?!\.))/
+
+function spaceBeforePunct(text: string, out: ProseHint[]) {
+  if (SPACE_BEFORE_PUNCT_RE.test(text)) {
+    out.push({
+      id: 'space-punct',
+      rule: 'space-punct',
+      zh: '标点前面不用空格，逗号、句号紧跟在前一个词后面就好。',
+      en: 'No space before punctuation — it tucks right against the word.',
+    })
+  }
+}
+
+// ── Chinese-L1 interference rules (Tier 1) ──────────────────────────────────
+// Mandarin lacks plural inflection, articles, and verb agreement, so these
+// patterns are the predictable places that grammar "leaks" into her English.
+// All are closed-list or strong-signal to keep false positives near zero.
+
+// 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/i
+
+function uncountables(text: string, out: ProseHint[]) {
+  const m = UNCOUNTABLE_PLURAL_RE.exec(text)
+  UNCOUNTABLE_PLURAL_RE.lastIndex = 0
+  if (m) {
+    const singular = m[1].replace(/s$/i, '')
+    out.push({
+      id: `uncountable:${m[1].toLowerCase()}`,
+      rule: 'uncountable',
+      zh: `“${m[1]}” 是不可数名词，不用加 s，写 “${singular}” 就好。`,
+      en: `“${m[1]}” is uncountable — drop the “s”: just “${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`)
+
+function properCaps(text: string, out: ProseHint[]) {
+  const m = PROPER_NOUN_RE.exec(text)
+  if (m) {
+    const fixed = m[1][0].toUpperCase() + m[1].slice(1)
+    out.push({
+      id: `propercap:${m[1]}`,
+      rule: 'propercap',
+      zh: `语言、国籍、星期和月份在英文里要大写：“${fixed}”。`,
+      en: `Languages, days, and months are capitalized in English: “${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
+  let found = 0
+  SVA_RE.lastIndex = 0
+  while ((m = SVA_RE.exec(text)) && found < 2) {
+    if (m[1] && CAUSATIVE.has(m[1].toLowerCase())) continue
+    found++
+    const fixed = third(m[3])
+    out.push({
+      id: `sva:${m[2].toLowerCase()}:${m[3].toLowerCase()}`,
+      rule: 'sva',
+      zh: `主语是 he/she/it 时，动词要加 -s：“${m[2]} ${fixed}”。`,
+      en: `After he/she/it the verb takes “-s”: “${m[2]} ${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
+  let found = 0
+  NUMBER_NOUN_RE.lastIndex = 0
+  while ((m = NUMBER_NOUN_RE.exec(text)) && found < 1) {
+    const noun = m[2].toLowerCase()
+    if (noun.endsWith('s') || NON_S_PLURAL.has(noun)) continue
+    found++
+    out.push({
+      id: `plural:${key(m[0])}`,
+      rule: 'plural',
+      zh: `“${m[1]}” 后面的名词要用复数：“${m[1]} ${m[2]}s”。`,
+      en: `After “${m[1]}”, the noun is plural: “${m[1]} ${m[2]}s”.`,
+    })
+  }
+}
+
+// Two stacked determiners (“the my book”, “a the”) — Mandarin uses a bare
+// possessive, so the article often gets stacked on top. One of the two must go.
+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[]) {
+  const m = DOUBLE_DET_RE.exec(text)
+  DOUBLE_DET_RE.lastIndex = 0
+  if (m) {
+    out.push({
+      id: `doubledet:${key(m[0])}`,
+      rule: 'doubledet',
+      zh: `“${m[1]} ${m[2]}” 用了两个限定词，留一个就好（比如去掉 “${m[1]}”）。`,
+      en: `“${m[1]} ${m[2]}” stacks two determiners — keep just one.`,
+    })
+  }
+}
+
+// “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/i
+
+function thereIsPlural(text: string, out: ProseHint[]) {
+  const m = THERE_IS_RE.exec(text)
+  THERE_IS_RE.lastIndex = 0
+  if (m) {
+    out.push({
+      id: `thereis:${m[1].toLowerCase()}`,
+      rule: 'thereis',
+      zh: `后面是复数时用 “there are”：“there are ${m[1]}…”。`,
+      en: `With a plural, use “there are”: “there are ${m[1]}…”.`,
+    })
+  }
+}
+
+// ── confusables (Tier 2) ─────────────────────────────────────────────────────
+
+// 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 = /\bit's\s+own\b/i
+const ITS_ARTICLE_RE = /\bits\s+(a|an)\b/i
+
+function itsConfusion(text: string, out: ProseHint[]) {
+  if (ITS_OWN_RE.test(text)) {
+    out.push({
+      id: 'its-own',
+      rule: 'its',
+      zh: '“it’s” = “it is”；表示“它的”要用 “its”，所以是 “its own”。',
+      en: '“it’s” means “it is” — the possessive is “its”: “its own”.',
+    })
+    return
+  }
+  const m = ITS_ARTICLE_RE.exec(text)
+  ITS_ARTICLE_RE.lastIndex = 0
+  if (m) {
+    out.push({
+      id: 'its-article',
+      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.`,
+    })
+  }
+}
+
+// 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`, 'i')
+
+function thanThen(text: string, out: ProseHint[]) {
+  const m = THAN_THEN_RE.exec(text)
+  if (m) {
+    out.push({
+      id: `than:${m[1].toLowerCase()}`,
+      rule: 'than',
+      zh: `比较的时候用 “than”，不是 “then”：“${m[1]} than”。`,
+      en: `For comparisons use “than”, not “then”: “${m[1]} than”.`,
+    })
+  }
+}
+
+// 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).
+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[]) {
+  let found = false
+  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]}, …”.`,
+      })
+      found = true
+      break
+    }
+  }
+  return found
+}
+
+// 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]/
+const NO_SPACE_PERIOD_RE = /[a-z]{2,}\.[A-Z][a-z]/
+
+function spaceAfterPunct(text: string, out: ProseHint[]) {
+  if (NO_SPACE_COMMA_RE.test(text) || NO_SPACE_PERIOD_RE.test(text)) {
+    out.push({
+      id: 'space-after',
+      rule: 'space-after',
+      zh: '逗号、句号后面要空一格，再接下一个词。',
+      en: 'Add a space after a comma or period before the next word.',
+    })
+  }
+}
+
+// ── 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).
+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
+}

web/src/components/Companion/tips.ts

@@ -17,7 +17,8 @@ export const ENCOURAGEMENTS: Line[] = [
   { zh: '嗯嗯，这样清楚多了 👍', en: 'Mm, that’s much clearer.' },
 ]
 
-// Gentle, periodic writing/ESL tips. Surfaced only when nothing else is showing.
+// 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”." },
@@ -47,8 +48,16 @@ export const WELCOME_BACK: Line = {
   en: 'Welcome back ✨ let’s keep going!',
 }
 
-// Word-count milestones worth a little cheer.
-export const MILESTONES = [50, 100, 250, 500, 1000, 2000]
+// 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 {

web/src/components/Companion/useCompanion.ts

@@ -3,6 +3,7 @@ import type { SaveStatus } from '../../hooks/useAutoSave'
 import {
   BREAKS,
   ENCOURAGEMENTS,
+  ERRORS,
   GREETING,
   MILESTONES,
   TIPS,
@@ -11,12 +12,14 @@ import {
   pick,
   type Line,
 } from './tips'
+import { analyzeProse } from './prose'
+import { playPop, playSound, type SoundName } from '../../audio/sounds'
 
 // 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'
+export type BubbleTone = 'cheer' | 'tip' | 'break' | 'error'
 export interface Bubble extends Line {
   tone: BubbleTone
 }
@@ -24,10 +27,16 @@ export interface Bubble extends Line {
 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.
@@ -35,14 +44,29 @@ 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 BUBBLE_MS = 6_500 // how long a bubble lingers
-const CHEER_MS = 4_500 // shorter for quick cheers
+// 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 : 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, editTick, acceptTick }: Signals) {
+export function useCompanion({ wordCount, saveStatus, llmDown, editTick, acceptTick, text }: Signals) {
   const [mood, setMood] = useState<Mood>('idle')
   const [bubble, setBubble] = useState<Bubble | null>(null)
 
@@ -54,12 +78,22 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
   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 }) => {
+  const say = useCallback(
+    (b: Bubble, opts?: { proactive?: boolean; celebrate?: boolean; sound?: SoundName }) => {
     const t = now()
     if (opts?.proactive) {
       if (bubble) return
@@ -67,15 +101,39 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
       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 = b.tone === 'cheer' ? CHEER_MS : BUBBLE_MS
+    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 => {
+    const hints = analyzeProse(textRef.current)
+    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)
@@ -83,6 +141,21 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
     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)
@@ -128,11 +201,39 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
       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 })
+      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) {
@@ -161,14 +262,15 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
         return
       }
 
-      // Otherwise an occasional tip.
+      // 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({ ...pick(TIPS), tone: 'tip' }, { proactive: true })
+        say(nextTip(), { proactive: true })
       }
     }, 10_000)
     return () => clearInterval(id)
-  }, [bubble, say])
+  }, [bubble, say, nextTip])
 
   useEffect(
     () => () => {
@@ -178,5 +280,5 @@ export function useCompanion({ wordCount, saveStatus, editTick, acceptTick }: Si
     [],
   )
 
-  return { mood, bubble, dismiss }
+  return { mood, bubble, dismiss, holdBubble, releaseBubble }
 }

web/src/components/DocList/DocList.tsx

@@ -1,49 +1,154 @@
-import type { DocSummary } from '../../api/client'
+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
 }
 
-// DocList is the 260px sidebar: the document browser plus a New button.
-export function DocList({ docs, selectedId, onSelect, onCreate, onDelete }: Props) {
+// 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-[260px] flex-col gap-2 p-3"
+      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="flex items-center justify-center gap-2 py-2.5 text-sm font-bold text-white"
-        style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-accent)' }}
+        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">
-        {docs.length === 0 ? (
+        {filtered.length === 0 ? (
           <p className="px-3 py-6 text-center text-xs" style={{ color: 'var(--color-muted)' }}>
-            No documents yet.
+            {activeFilter ? 'No documents with this tag.' : 'No documents yet.'}
           </p>
         ) : (
-          docs.map((doc) => (
+          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

@@ -1,48 +1,116 @@
-import type { DocSummary } from '../../api/client'
+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, a delete affordance on hover, and
-// a rose wash when it's the open document.
-export function DocListItem({ doc, active, onSelect, onDelete }: Props) {
+// 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 flex cursor-pointer items-center gap-2 px-3 py-2.5"
+      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="min-w-0 flex-1">
-        <div
-          className="truncate text-sm font-semibold"
-          style={{ color: active ? 'var(--color-plum)' : 'var(--color-muted)' }}
+      <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)' }}
         >
-          {doc.title || 'Untitled'}
-        </div>
-        <div className="text-xs" style={{ color: 'var(--color-muted)' }}>
-          {doc.word_count} {doc.word_count === 1 ? 'word' : 'words'}
-        </div>
+          🏷️
+        </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>
-      <button
-        type="button"
-        aria-label="Delete document"
-        onClick={(e) => {
-          e.stopPropagation()
-          onDelete()
-        }}
-        className="flex h-6 w-6 shrink-0 items-center justify-center text-base opacity-0 group-hover:opacity-100"
-        style={{ borderRadius: 'var(--radius-pill)', color: 'var(--color-muted)' }}
-      >
-        ×
-      </button>
+
+      {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

@@ -1,9 +1,11 @@
 import { useEffect, useRef, useState } from 'react'
-import { streamSuggestionChat, type ChatMessage } from '../../api/client'
+import { api, streamSuggestionChat, type ChatMessage } from '../../api/client'
 
 interface Props {
   suggestionId: string
-  // Pre-populates Petal's first bubble so the conversation opens with context.
+  // 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
 }
 
@@ -17,9 +19,10 @@ const CHAT_FONT = "'Nunito', 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC
 // 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) {
-  const [messages, setMessages] = useState<ChatMessage[]>([
-    { role: 'assistant', content: explanation },
-  ])
+  // 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)
@@ -36,6 +39,31 @@ export function AskPetal({ suggestionId, explanation }: Props) {
     inputRef.current?.focus()
   }, [])
 
+  // 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
@@ -86,7 +114,12 @@ export function AskPetal({ suggestionId, explanation }: Props) {
         style={{ maxHeight: 220 }}
       >
         {messages.map((m, i) => (
-          <Bubble key={i} role={m.role} content={m.content} streaming={streaming && i === messages.length - 1} />
+          <Bubble
+            key={i}
+            role={m.role}
+            content={m.content}
+            streaming={(streaming && i === messages.length - 1) || (seeding && i === 0)}
+          />
         ))}
       </div>
 

web/src/components/Editor/EditorCore.tsx

@@ -4,14 +4,33 @@ import Underline from '@tiptap/extension-underline'
 import TextAlign from '@tiptap/extension-text-align'
 import Placeholder from '@tiptap/extension-placeholder'
 import CharacterCount from '@tiptap/extension-character-count'
+import Link from '@tiptap/extension-link'
+import { Color } from '@tiptap/extension-color'
+import TextStyle from '@tiptap/extension-text-style'
+import Highlight from '@tiptap/extension-highlight'
+import Image from '@tiptap/extension-image'
+import Table from '@tiptap/extension-table'
+import TableRow from '@tiptap/extension-table-row'
+import TableHeader from '@tiptap/extension-table-header'
+import TableCell from '@tiptap/extension-table-cell'
+import { FontSize } from './FontSize'
+import type { EditorView } from '@tiptap/pm/view'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { Toolbar } from '../Toolbar/Toolbar'
 import { SuggestionCard } from './SuggestionCard'
-import { SuggestionHighlight, setSuggestions, findRange } from './SuggestionHighlight'
+import { SuggestionRail, type RailItem } from './SuggestionRail'
+import { SuggestionHighlight, setSuggestions, setActiveSuggestion, findRange } from './SuggestionHighlight'
 import { SpellCheck, setSpellChecker, wordAt } from './SpellCheck'
 import { MisspellCard } from './MisspellCard'
 import { WordCard } from './WordCard'
+import { GlossTip } from './GlossTip'
+import { SelectionBubble } from './SelectionBubble'
+import { SearchHighlight } from './SearchHighlight'
+import { FindReplace } from './FindReplace'
+import { Typography } from './Typography'
+import { RewritePreview, type RewriteStatus } from './RewritePreview'
 import { api, type Suggestion, type WordInfo } from '../../api/client'
+import { speak, speechSupported } from '../../audio/speech'
 import type { SpellChecker } from '../../hooks/useSpellChecker'
 
 export interface EditorChange {
@@ -100,12 +119,60 @@ function parseDoc(raw: string): object | undefined {
   return undefined
 }
 
+// uploadImageInto sends an image file to the store and inserts the returned URL
+// as an image node — at `pos` if given (a drop point), otherwise at the current
+// selection (a paste). Shared by the paste/drop handlers and the toolbar button.
+export async function uploadImageInto(view: EditorView, file: File, pos?: number) {
+  try {
+    const { url } = await api.uploadImage(file)
+    const { schema } = view.state
+    const node = schema.nodes.image.create({ src: url })
+    const at = pos ?? view.state.selection.from
+    view.dispatch(view.state.tr.insert(at, node))
+  } catch (err) {
+    console.error('image upload failed', err)
+  }
+}
+
 interface HoverState {
   suggestion: Suggestion
   top: number
   left: number
 }
 
+// The inline hover gloss: the word under the resting pointer, its Chinese
+// translation, the PM range it covers (to dedupe re-fetches), and where to anchor.
+interface GlossState {
+  word: string
+  gloss: string
+  from: number
+  to: number
+  top: number
+  left: number
+}
+
+// A non-empty text selection that the rewrite bubble hovers over.
+interface SelectionState {
+  from: number
+  to: number
+  text: string
+  top: number
+  left: number
+}
+
+// An in-flight or completed tone-rewrite preview, pinned over the selection it
+// came from. `from`/`to` are the PM range the accepted rewrite replaces.
+interface RewriteState {
+  from: number
+  to: number
+  original: string
+  style: string
+  top: number
+  left: number
+  status: RewriteStatus
+  rewrite: string
+}
+
 // EditorCore is the Tiptap instance: StarterKit formatting plus underline, text
 // alignment, a placeholder, character counting, and the suggestion-highlight
 // decoration layer. Hovering a highlight opens its SuggestionCard.
@@ -138,31 +205,118 @@ export function EditorCore({
   // While the Ask Petal panel is expanded the card is pinned: the hover-close
   // timer is suppressed so chatting doesn't dismiss it. A click outside closes.
   const [pinned, setPinned] = useState(false)
+  // Inline hover gloss (rest the pointer on a word → its Chinese meaning).
+  const [gloss, setGloss] = useState<GlossState | null>(null)
+  const glossTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+  const glossReqRef = useRef(0)
+  // The rewrite affordances: a bubble over the current selection, and the
+  // preview that replaces it once a style is chosen.
+  const [selection, setSelection] = useState<SelectionState | null>(null)
+  // True while a pointer is held down (a drag-select in progress). The rewrite
+  // bubble stays hidden until release so it never appears — or re-anchors — under
+  // a still-moving cursor, which is where the user is trying to click.
+  const [dragging, setDragging] = useState(false)
+  const [rewrite, setRewrite] = useState<RewriteState | null>(null)
+  const rewriteReqRef = useRef(0)
+  // The in-document Find & Replace bar (Ctrl/Cmd+F).
+  const [findOpen, setFindOpen] = useState(false)
+  // The right-margin comment rail. `railItems` carries each anchored suggestion's
+  // vertical offset; `railEnabled` is true only when the viewport has room for the
+  // column beside the editor (otherwise we fall back to the inline hover cards).
+  // `railExpandedId` is the card showing its full explanation + Ask Petal, and
+  // `activeId` is the suggestion currently emphasized (hovered text or card).
+  const [railItems, setRailItems] = useState<RailItem[]>([])
+  const [railEnabled, setRailEnabled] = useState(false)
+  const [railExpandedId, setRailExpandedId] = useState<string | null>(null)
+  const [activeId, setActiveId] = useState<string | null>(null)
+  // A stable handle to the latest recompute so the editor's onUpdate (captured
+  // once at construction) can trigger a re-measure without stale closures.
+  const recomputeRailRef = useRef<() => void>(() => {})
 
   const editor = useEditor({
     extensions: [
       StarterKit,
       Underline,
+      TextStyle,
+      Color,
+      FontSize,
+      Highlight.configure({ multicolor: true }),
+      Link.configure({ openOnClick: false, autolink: true, HTMLAttributes: { rel: 'noopener noreferrer nofollow' } }),
+      Image.configure({ inline: false, HTMLAttributes: { class: 'petal-image' } }),
+      Table.configure({ resizable: true, HTMLAttributes: { class: 'petal-table' } }),
+      TableRow,
+      TableHeader,
+      TableCell,
       TextAlign.configure({ types: ['heading', 'paragraph'] }),
       Placeholder.configure({ placeholder: 'Start writing…' }),
       CharacterCount,
       SuggestionHighlight,
       SpellCheck,
+      SearchHighlight,
+      Typography,
     ],
     content: parseDoc(initialContent),
     editorProps: {
       attributes: { class: 'petal-prose focus:outline-none' },
+      // Dropping or pasting an image file uploads it and inserts it at the drop
+      // point (or the cursor for a paste). Returns true to consume the event so
+      // ProseMirror doesn't also try to handle the raw file. Non-image pastes
+      // fall through to the default handler.
+      handleDrop: (view, event) => {
+        const files = (event as DragEvent).dataTransfer?.files
+        const image = files && Array.from(files).find((f) => f.type.startsWith('image/'))
+        if (!image) return false
+        event.preventDefault()
+        const coords = view.posAtCoords({ left: (event as DragEvent).clientX, top: (event as DragEvent).clientY })
+        uploadImageInto(view, image, coords?.pos)
+        return true
+      },
+      handlePaste: (view, event) => {
+        const files = event.clipboardData?.files
+        const image = files && Array.from(files).find((f) => f.type.startsWith('image/'))
+        if (!image) return false
+        event.preventDefault()
+        uploadImageInto(view, image)
+        return true
+      },
     },
     onFocus: () => onFocusMode?.(),
     onUpdate: ({ editor }) => {
       // Any edit shifts positions, stranding the popover anchors.
       setMisspell(null)
       setWordInfo(null)
+      setGloss(null)
+      setSelection(null)
+      // A stale rewrite preview points at a range that just moved — drop it.
+      rewriteReqRef.current++
+      setRewrite(null)
       onChange({
         content: JSON.stringify(editor.getJSON()),
         content_text: editor.getText(),
         word_count: editor.storage.characterCount.words(),
       })
+      // Edits reflow the text, so the rail anchors need re-measuring.
+      recomputeRailRef.current()
+    },
+    onSelectionUpdate: ({ editor }) => {
+      // A selection supersedes the hover gloss; an empty one clears the bubble.
+      setGloss(null)
+      const { from, to, empty } = editor.state.selection
+      const wrapper = wrapperRef.current
+      if (empty || !wrapper) {
+        setSelection(null)
+        return
+      }
+      const text = editor.state.doc.textBetween(from, to, ' ').trim()
+      if (!text) {
+        setSelection(null)
+        return
+      }
+      const start = editor.view.coordsAtPos(from)
+      const wrapRect = wrapper.getBoundingClientRect()
+      const left = Math.max(0, Math.min(start.left - wrapRect.left, wrapper.clientWidth - 360))
+      const top = start.top - wrapRect.top
+      setSelection({ from, to, text, top, left })
     },
   })
 
@@ -174,6 +328,10 @@ export function EditorCore({
     setHover(null)
     setMisspell(null)
     setWordInfo(null)
+    setGloss(null)
+    setSelection(null)
+    rewriteReqRef.current++
+    setRewrite(null)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [docId, editor])
 
@@ -190,8 +348,87 @@ export function EditorCore({
     setSuggestions(editor.state, editor.view.dispatch, suggestions)
     // Close the card if its suggestion is gone.
     setHover((h) => (h && suggestions.some((s) => s.id === h.suggestion.id) ? h : null))
+    // Drop any rail expand/emphasis that points at a now-removed suggestion.
+    setRailExpandedId((id) => (id && suggestions.some((s) => s.id === id) ? id : null))
+    setActiveId((id) => (id && suggestions.some((s) => s.id === id) ? id : null))
   }, [editor, suggestions])
 
+  // Re-measure the margin rail: whether there's room for the column beside the
+  // editor, and where each suggestion's highlight sits vertically. Anchors are
+  // taken from the live decoration DOM (keyed by data-suggestion-id) relative to
+  // the wrapper — stable under scroll since text and wrapper scroll together.
+  // Deferred a frame so decoration DOM and reflow have settled.
+  const recomputeRail = useCallback(() => {
+    requestAnimationFrame(() => {
+      const wrapper = wrapperRef.current
+      if (!wrapper) return
+      const wrapRect = wrapper.getBoundingClientRect()
+      // Need room for the 300px column + its 32px gutter (see .petal-rail), plus
+      // a little breathing space to the viewport edge.
+      setRailEnabled(window.innerWidth - wrapRect.right >= 348)
+      const seen = new Set<string>()
+      const items: RailItem[] = []
+      wrapper.querySelectorAll<HTMLElement>('.petal-suggestion[data-suggestion-id]').forEach((el) => {
+        const id = el.getAttribute('data-suggestion-id')
+        if (!id || seen.has(id)) return
+        const s = suggestions.find((x) => x.id === id)
+        if (!s) return
+        seen.add(id)
+        items.push({ suggestion: s, anchorTop: el.getBoundingClientRect().top - wrapRect.top })
+      })
+      setRailItems(items)
+    })
+  }, [suggestions])
+
+  useEffect(() => {
+    recomputeRailRef.current = recomputeRail
+  }, [recomputeRail])
+
+  // Re-anchor when the suggestion set changes (after the decorations repaint),
+  // and keep the rail in sync with viewport/editor width changes (room + reflow).
+  useEffect(() => {
+    recomputeRail()
+    const wrapper = wrapperRef.current
+    const ro = wrapper ? new ResizeObserver(() => recomputeRail()) : null
+    if (wrapper && ro) ro.observe(wrapper)
+    window.addEventListener('resize', recomputeRail)
+    return () => {
+      ro?.disconnect()
+      window.removeEventListener('resize', recomputeRail)
+    }
+  }, [recomputeRail])
+
+  // Emphasize the flagged text for the active suggestion, mirroring the rail
+  // card ↔ text link both ways. Driven through the decoration plugin (not an
+  // imperative DOM class) so it survives the repaints that fire on every edit.
+  useEffect(() => {
+    if (!editor) return
+    setActiveSuggestion(editor.state, editor.view.dispatch, railEnabled ? activeId : null)
+  }, [editor, activeId, railEnabled])
+
+  // Scroll a suggestion's highlight to the middle of the viewport (clicking its
+  // rail card jumps the editor to the flagged text).
+  const scrollToSuggestion = useCallback((id: string) => {
+    const el = wrapperRef.current?.querySelector(
+      `.petal-suggestion[data-suggestion-id="${CSS.escape(id)}"]`,
+    )
+    el?.scrollIntoView({ block: 'center', behavior: 'smooth' })
+  }, [])
+
+  // Clicking a rail card's body jumps to the text and toggles its detail panel.
+  const activateRailCard = useCallback(
+    (id: string) => {
+      setActiveId(id)
+      scrollToSuggestion(id)
+      setRailExpandedId((cur) => (cur === id ? null : id))
+    },
+    [scrollToSuggestion],
+  )
+
+  const toggleRailExpand = useCallback((id: string) => {
+    setRailExpandedId((cur) => (cur === id ? null : id))
+  }, [])
+
   const openCardFor = useCallback(
     (id: string, el: HTMLElement) => {
       const wrapper = wrapperRef.current
@@ -223,10 +460,17 @@ export function EditorCore({
       if (!target) return
       const id = target.getAttribute('data-suggestion-id')
       if (!id) return
+      // With the rail open the card already lives in the margin — hovering the
+      // text just emphasizes its card (and the highlight) rather than popping a
+      // second, redundant floating card.
+      if (railEnabled) {
+        setActiveId(id)
+        return
+      }
       clearTimeout(closeTimer.current)
       openCardFor(id, target)
     },
-    [openCardFor],
+    [openCardFor, railEnabled],
   )
 
   const scheduleClose = useCallback(() => {
@@ -246,35 +490,53 @@ export function EditorCore({
   // pointer can bridge the small gap from text to card.
   const handleMouseOut = useCallback(
     (e: React.MouseEvent) => {
-      if ((e.target as HTMLElement).closest('.petal-suggestion')) scheduleClose()
+      if (!(e.target as HTMLElement).closest('.petal-suggestion')) return
+      if (railEnabled) {
+        setActiveId(null)
+        return
+      }
+      scheduleClose()
     },
-    [scheduleClose],
+    [scheduleClose, railEnabled],
   )
 
   const keepOpen = useCallback(() => clearTimeout(closeTimer.current), [])
 
   // Accept applies the replacement to the document, plays a little confetti
-  // burst where the card sat, then notifies the parent.
+  // burst over the flagged text, then notifies the parent. The confetti is
+  // anchored to the highlight itself (captured before the replacement removes it),
+  // so it fires in the right spot whether the accept came from the hover card or
+  // the margin rail.
   const handleAccept = useCallback(
     (s: Suggestion) => {
+      const wrapper = wrapperRef.current
+      const el = wrapper?.querySelector(
+        `.petal-suggestion[data-suggestion-id="${CSS.escape(s.id)}"]`,
+      ) as HTMLElement | null
+      let burst: { top: number; left: number } | null = null
+      if (wrapper && el) {
+        const wrapRect = wrapper.getBoundingClientRect()
+        const elRect = el.getBoundingClientRect()
+        burst = { top: elRect.top - wrapRect.top, left: elRect.right - wrapRect.left }
+      }
       if (editor && s.replacement.trim() !== '') {
         const range = findRange(editor.state.doc, s.original)
         if (range) {
           editor.chain().focus().insertContentAt(range, s.replacement).run()
         }
       }
-      setHover((h) => {
-        if (h) {
-          setConfetti({ top: h.top, left: h.left + 16 })
-          clearTimeout(confettiTimer.current)
-          confettiTimer.current = setTimeout(() => setConfetti(null), 720)
-        }
-        return h
-      })
+      // Fall back to the hover card's position if the highlight wasn't found.
+      if (!burst && hover) burst = { top: hover.top, left: hover.left + 16 }
+      if (burst) {
+        setConfetti(burst)
+        clearTimeout(confettiTimer.current)
+        confettiTimer.current = setTimeout(() => setConfetti(null), 720)
+      }
       closeCard()
+      setRailExpandedId(null)
       onAccept(s)
     },
-    [editor, onAccept, closeCard],
+    [editor, onAccept, closeCard, hover],
   )
 
   const handleDismiss = useCallback(
@@ -288,8 +550,26 @@ export function EditorCore({
   // Click a red-underlined word to open its spelling popover, anchored under the
   // word. posAtCoords→wordAt resolves the exact PM span (robust to the same
   // misspelling appearing elsewhere); nspell supplies the corrections.
+  //
+  // Tapping an AI-suggestion highlight also opens its card here — on touch there's
+  // no hover, so the tap is the only way in (mouse users still get hover).
   const handleSpellClick = useCallback(
     (e: React.MouseEvent) => {
+      const suggestionEl = (e.target as HTMLElement).closest('.petal-suggestion') as HTMLElement | null
+      if (suggestionEl) {
+        const id = suggestionEl.getAttribute('data-suggestion-id')
+        if (id) {
+          // With the rail open, a tap emphasizes and expands its margin card
+          // instead of opening a floating one.
+          if (railEnabled) {
+            setActiveId(id)
+            setRailExpandedId(id)
+          } else {
+            openCardFor(id, suggestionEl)
+          }
+        }
+        return
+      }
       if (!editor || !spellChecker) return
       const target = (e.target as HTMLElement).closest('.petal-misspelling') as HTMLElement | null
       if (!target) return
@@ -309,7 +589,7 @@ export function EditorCore({
       setWordInfo(null)
       setMisspell({ ...range, suggestions: spellChecker.suggest(range.word), top, left })
     },
-    [editor, spellChecker, closeCard],
+    [editor, spellChecker, closeCard, openCardFor, railEnabled],
   )
 
   const replaceMisspelling = useCallback(
@@ -327,20 +607,17 @@ export function EditorCore({
     setMisspell(null)
   }, [misspell, onAddWord])
 
-  // Right-click a word to look it up: resolve the exact word span under the
-  // pointer, anchor a popover beneath it, and kick off the offline lookup. The
-  // card opens immediately in a loading state and fills in when the (local)
-  // lookup returns. Right-clicking off any word falls through to the native menu.
-  const handleContextMenu = useCallback(
-    (e: React.MouseEvent) => {
+  // openWordLookup resolves the exact word span at a document position, anchors a
+  // popover beneath it, and kicks off the offline lookup. The card opens
+  // immediately in a loading state and fills in when the (local) lookup returns.
+  // Shared by right-click, the keyboard shortcut (caret), and touch long-press.
+  const openWordLookup = useCallback(
+    (pos: number) => {
       if (!editor) return
-      const coords = editor.view.posAtCoords({ left: e.clientX, top: e.clientY })
-      if (!coords) return
-      const range = wordAt(editor.state.doc, coords.pos)
+      const range = wordAt(editor.state.doc, pos)
       if (!range) return
       const wrapper = wrapperRef.current
       if (!wrapper) return
-      e.preventDefault()
       // Anchor under the word itself (not the click point) so the card lines up
       // with the text the way the spelling popover does.
       const start = editor.view.coordsAtPos(range.from)
@@ -371,6 +648,37 @@ export function EditorCore({
     [editor, closeCard],
   )
 
+  // Right-click a word to look it up. Right-clicking off any word falls through
+  // to the native menu (so copy/paste-by-menu still works — see the Selection fix).
+  const handleContextMenu = useCallback(
+    (e: React.MouseEvent) => {
+      if (!editor) return
+      const coords = editor.view.posAtCoords({ left: e.clientX, top: e.clientY })
+      if (!coords) return
+      if (!wordAt(editor.state.doc, coords.pos)) return
+      e.preventDefault()
+      openWordLookup(coords.pos)
+    },
+    [editor, openWordLookup],
+  )
+
+  // Touch has no hover or right-click, so a long-press (~500ms without moving)
+  // opens the word lookup at the finger — the touch equivalent of right-click.
+  const longPressTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+  const handleTouchStart = useCallback(
+    (e: React.TouchEvent) => {
+      if (!editor || e.touches.length !== 1) return
+      const { clientX, clientY } = e.touches[0]
+      clearTimeout(longPressTimer.current)
+      longPressTimer.current = setTimeout(() => {
+        const coords = editor.view.posAtCoords({ left: clientX, top: clientY })
+        if (coords) openWordLookup(coords.pos)
+      }, 500)
+    },
+    [editor, openWordLookup],
+  )
+  const cancelLongPress = useCallback(() => clearTimeout(longPressTimer.current), [])
+
   const replaceWord = useCallback(
     (synonym: string) => {
       if (editor && wordInfo) {
@@ -381,6 +689,143 @@ export function EditorCore({
     [editor, wordInfo],
   )
 
+  // Hover gloss: rest the pointer on an English word and, after a short delay,
+  // show its Chinese meaning from the offline gloss dataset. Suppressed while a
+  // selection, preview, or another popover is active, or over a word that has its
+  // own affordance (a suggestion highlight / a misspelling).
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      if (!editor) return
+      if (selection || rewrite || misspell || wordInfo || pinned) return
+      if (!editor.state.selection.empty) return
+      const t = e.target as HTMLElement
+      const clear = () => {
+        clearTimeout(glossTimer.current)
+        glossReqRef.current++
+        setGloss(null)
+      }
+      if (t.closest('.petal-suggestion') || t.closest('.petal-misspelling')) {
+        clear()
+        return
+      }
+      const coords = editor.view.posAtCoords({ left: e.clientX, top: e.clientY })
+      if (!coords) {
+        clear()
+        return
+      }
+      const range = wordAt(editor.state.doc, coords.pos)
+      if (!range) {
+        clear()
+        return
+      }
+      // Already showing this exact word — leave it be (no flicker on micro-moves).
+      if (gloss && gloss.from === range.from && gloss.to === range.to) return
+      clearTimeout(glossTimer.current)
+      const token = ++glossReqRef.current
+      glossTimer.current = setTimeout(() => {
+        api
+          .glossWord(range.word)
+          .then((g) => {
+            if (token !== glossReqRef.current) return
+            const wrapper = wrapperRef.current
+            if (!g.gloss || !wrapper) {
+              setGloss(null)
+              return
+            }
+            const start = editor.view.coordsAtPos(range.from)
+            const end = editor.view.coordsAtPos(range.to)
+            const wrapRect = wrapper.getBoundingClientRect()
+            const left = Math.max(0, Math.min(start.left - wrapRect.left, wrapper.clientWidth - 280))
+            const top = end.bottom - wrapRect.top + 6
+            setGloss({ word: range.word, gloss: g.gloss, from: range.from, to: range.to, top, left })
+          })
+          .catch(() => {
+            if (token === glossReqRef.current) setGloss(null)
+          })
+      }, 350)
+    },
+    [editor, selection, rewrite, misspell, wordInfo, pinned, gloss],
+  )
+
+  // Leaving the editor surface drops any pending/shown gloss.
+  const handleMouseLeave = useCallback(() => {
+    clearTimeout(glossTimer.current)
+    glossReqRef.current++
+    setGloss(null)
+  }, [])
+
+  // runRewrite fires the LLM rewrite for a captured range + style and tracks it
+  // through loading → ready/error. A request token discards a response whose
+  // preview has since been cancelled or superseded.
+  const runRewrite = useCallback(
+    (from: number, to: number, original: string, style: string, top: number, left: number) => {
+      const token = ++rewriteReqRef.current
+      setRewrite({ from, to, original, style, top, left, status: 'loading', rewrite: '' })
+      api
+        .rewriteSelection(docId, original, style)
+        .then((res) => {
+          if (token === rewriteReqRef.current) {
+            setRewrite((r) => (r ? { ...r, status: 'ready', rewrite: res.rewrite } : null))
+          }
+        })
+        .catch((err) => {
+          console.error('rewrite failed', err)
+          if (token === rewriteReqRef.current) {
+            setRewrite((r) => (r ? { ...r, status: 'error' } : null))
+          }
+        })
+    },
+    [docId],
+  )
+
+  // Picking a style in the selection bubble: capture the selection's range +
+  // text, anchor a preview below it, and kick off the rewrite.
+  const handleRewrite = useCallback(
+    (style: string) => {
+      if (!editor || !selection) return
+      const wrapper = wrapperRef.current
+      if (!wrapper) return
+      const start = editor.view.coordsAtPos(selection.from)
+      const end = editor.view.coordsAtPos(selection.to)
+      const wrapRect = wrapper.getBoundingClientRect()
+      const left = Math.max(0, Math.min(start.left - wrapRect.left, wrapper.clientWidth - 340))
+      const top = end.bottom - wrapRect.top + 6
+      setSelection(null)
+      setGloss(null)
+      runRewrite(selection.from, selection.to, selection.text, style, top, left)
+    },
+    [editor, selection, runRewrite],
+  )
+
+  const acceptRewrite = useCallback(() => {
+    if (editor && rewrite && rewrite.rewrite) {
+      editor.chain().focus().insertContentAt({ from: rewrite.from, to: rewrite.to }, rewrite.rewrite).run()
+    }
+    rewriteReqRef.current++
+    setRewrite(null)
+  }, [editor, rewrite])
+
+  const cancelRewrite = useCallback(() => {
+    rewriteReqRef.current++
+    setRewrite(null)
+  }, [])
+
+  const retryRewrite = useCallback(() => {
+    if (rewrite) runRewrite(rewrite.from, rewrite.to, rewrite.original, rewrite.style, rewrite.top, rewrite.left)
+  }, [rewrite, runRewrite])
+
+  // A pointer-down outside the rewrite preview dismisses it.
+  useEffect(() => {
+    if (!rewrite) return
+    const onDown = (e: MouseEvent) => {
+      if ((e.target as HTMLElement).closest('.petal-rewrite-card')) return
+      rewriteReqRef.current++
+      setRewrite(null)
+    }
+    document.addEventListener('mousedown', onDown)
+    return () => document.removeEventListener('mousedown', onDown)
+  }, [rewrite])
+
   // A pointer-down outside the word popover (and not on another word, which would
   // reopen it via the context menu) closes it.
   useEffect(() => {
@@ -406,9 +851,52 @@ export function EditorCore({
     return () => document.removeEventListener('mousedown', onDown)
   }, [misspell])
 
+  // A pointer-down in the editor starts a (possible) drag-select, which keeps the
+  // rewrite bubble hidden until release. A pointer-down on the bubble itself is
+  // excluded so its buttons stay clickable. Release always re-arms the bubble.
+  const handlePointerDown = useCallback((e: React.PointerEvent) => {
+    if ((e.target as HTMLElement).closest('.petal-selection-bubble')) return
+    setDragging(true)
+  }, [])
+
+  useEffect(() => {
+    const onUp = () => setDragging(false)
+    document.addEventListener('pointerup', onUp)
+    return () => document.removeEventListener('pointerup', onUp)
+  }, [])
+
+  // Editor keyboard shortcuts, so the ESL helpers aren't mouse-only:
+  //   Ctrl/Cmd+F — Find & Replace (overrides the browser find, which can't see
+  //                into the editor's content anyway)
+  //   Ctrl/Cmd+D — look up the word at the caret (the keyboard "right-click")
+  //   Ctrl/Cmd+J — rewrite the current selection more naturally (✨更自然)
+  useEffect(() => {
+    if (!editor) return
+    const onKey = (e: KeyboardEvent) => {
+      if (!(e.ctrlKey || e.metaKey) || e.altKey) return
+      const k = e.key.toLowerCase()
+      if (k === 'f') {
+        e.preventDefault()
+        setFindOpen(true)
+      } else if (k === 'd') {
+        e.preventDefault()
+        openWordLookup(editor.state.selection.from)
+      } else if (k === 'j') {
+        if (!editor.state.selection.empty) {
+          e.preventDefault()
+          handleRewrite('natural')
+        }
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [editor, openWordLookup, handleRewrite])
+
   useEffect(() => () => {
     clearTimeout(closeTimer.current)
     clearTimeout(confettiTimer.current)
+    clearTimeout(glossTimer.current)
+    clearTimeout(longPressTimer.current)
   }, [])
 
   // While pinned (Ask Petal open), a pointer-down outside the card closes it —
@@ -422,6 +910,20 @@ export function EditorCore({
     return () => document.removeEventListener('mousedown', onDown)
   }, [pinned, closeCard])
 
+  // Touch has no hover, so the card is opened by a tap and can't close itself on
+  // mouse-leave. Whenever a card is open, a pointer-down outside both the card and
+  // any highlight dismisses it. Excluding `.petal-suggestion` lets a tap on
+  // another highlight reopen for that one (via the click handler) without flicker.
+  useEffect(() => {
+    if (!hover) return
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as HTMLElement
+      if (!t.closest('.petal-suggestion-card') && !t.closest('.petal-suggestion')) closeCard()
+    }
+    document.addEventListener('pointerdown', onDown)
+    return () => document.removeEventListener('pointerdown', onDown)
+  }, [hover, closeCard])
+
   return (
     <div className="flex flex-1 flex-col">
       <Toolbar editor={editor} onVoiceCheck={onVoiceCheck} voicing={voicing} />
@@ -430,11 +932,38 @@ export function EditorCore({
         className="relative flex-1"
         onMouseOver={handleMouseOver}
         onMouseOut={handleMouseOut}
+        onMouseMove={handleMouseMove}
+        onMouseLeave={handleMouseLeave}
+        onPointerDown={handlePointerDown}
         onClick={handleSpellClick}
         onContextMenu={handleContextMenu}
+        onTouchStart={handleTouchStart}
+        onTouchMove={cancelLongPress}
+        onTouchEnd={cancelLongPress}
       >
         <EditorContent editor={editor} className="h-full" />
+        {findOpen && editor && <FindReplace editor={editor} onClose={() => setFindOpen(false)} />}
         {confetti && <Confetti top={confetti.top} left={confetti.left} />}
+        {gloss && <GlossTip gloss={gloss.gloss} style={{ top: gloss.top, left: gloss.left }} />}
+        {selection && !rewrite && !dragging && (
+          <SelectionBubble
+            style={{ top: selection.top, left: selection.left, transform: 'translateY(calc(-100% - 8px))' }}
+            onRewrite={handleRewrite}
+            onSpeak={speechSupported() ? () => speak(selection.text) : null}
+          />
+        )}
+        {rewrite && (
+          <RewritePreview
+            style={rewrite.style}
+            status={rewrite.status}
+            original={rewrite.original}
+            rewrite={rewrite.rewrite}
+            cardStyle={{ top: rewrite.top, left: rewrite.left }}
+            onAccept={acceptRewrite}
+            onCancel={cancelRewrite}
+            onRetry={retryRewrite}
+          />
+        )}
         {wordInfo && (
           <WordCard
             word={wordInfo.word}
@@ -453,7 +982,7 @@ export function EditorCore({
             onAdd={addMisspellingToDict}
           />
         )}
-        {hover && (
+        {hover && !railEnabled && (
           <SuggestionCard
             suggestion={hover.suggestion}
             style={{ top: hover.top, left: hover.left }}
@@ -464,6 +993,18 @@ export function EditorCore({
             onExpandChange={setPinned}
           />
         )}
+        {railEnabled && railItems.length > 0 && (
+          <SuggestionRail
+            items={railItems}
+            activeId={activeId}
+            expandedId={railExpandedId}
+            onAccept={handleAccept}
+            onDismiss={handleDismiss}
+            onHover={setActiveId}
+            onActivate={activateRailCard}
+            onToggleExpand={toggleRailExpand}
+          />
+        )}
       </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>
+  )
+}

web/src/components/Editor/RewritePreview.tsx

@@ -0,0 +1,136 @@
+import { REWRITE_STYLES } from './SelectionBubble'
+
+// RewritePreview shows the result of a tone-rewrite before it touches the
+// document: the writer's original passage, the model's rewrite beneath it, and
+// accept/cancel. It mirrors the SuggestionCard's warm, bilingual chrome. While
+// the model runs it shows a breathing dot; on failure it offers a gentle retry.
+
+export type RewriteStatus = 'loading' | 'ready' | 'error'
+
+interface Props {
+  style: string // the chosen rewrite style key (for the header label)
+  status: RewriteStatus
+  original: string
+  rewrite: string
+  cardStyle: React.CSSProperties
+  onAccept: () => void
+  onCancel: () => void
+  onRetry: () => void
+}
+
+const CJK = "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+
+export function RewritePreview({
+  style,
+  status,
+  original,
+  rewrite,
+  cardStyle,
+  onAccept,
+  onCancel,
+  onRetry,
+}: Props) {
+  const meta = REWRITE_STYLES.find((s) => s.value === style) ?? REWRITE_STYLES[0]
+
+  return (
+    <div
+      className="petal-rewrite-card absolute z-30 p-3.5 text-sm"
+      role="dialog"
+      aria-label="Rewrite preview"
+      onMouseDown={(e) => e.stopPropagation()}
+      style={{
+        width: 340,
+        background: 'var(--color-surface)',
+        border: '1px solid var(--color-border)',
+        borderRadius: 'var(--radius-card)',
+        boxShadow: 'var(--shadow-soft)',
+        fontFamily: CJK,
+        ...cardStyle,
+      }}
+    >
+      <div className="flex items-center gap-1.5">
+        <span
+          className="inline-flex items-center gap-1 rounded-full px-2.5 py-0.5 text-xs font-bold"
+          style={{ background: 'var(--color-accent)', color: 'var(--color-plum)' }}
+        >
+          <span aria-hidden>{meta.emoji}</span>
+          {meta.zh} · {meta.en}
+        </span>
+        <span className="text-xs font-semibold" style={{ color: 'var(--color-muted)' }}>
+          改写 · Rewrite
+        </span>
+      </div>
+
+      {/* Original passage, dimmed — what's being replaced. */}
+      <p
+        className="mt-3 leading-snug"
+        style={{ color: 'var(--color-muted)', textDecoration: 'line-through', textDecorationColor: 'var(--color-border)' }}
+      >
+        {original}
+      </p>
+
+      {status === 'loading' && (
+        <div className="mt-3 inline-flex items-center gap-1.5" style={{ color: 'var(--color-muted)' }}>
+          <span
+            className="petal-checkpoint-dot inline-block h-2 w-2 rounded-full"
+            style={{ background: 'var(--color-accent)' }}
+            aria-hidden
+          />
+          改写中… · Rewriting…
+        </div>
+      )}
+
+      {status === 'error' && (
+        <div className="mt-3">
+          <p className="leading-snug" style={{ color: 'var(--color-muted)' }}>
+            改写失败，请再试一次 · Couldn’t rewrite — try again
+          </p>
+          <div className="mt-2.5 flex justify-end gap-2">
+            <button
+              type="button"
+              onClick={onCancel}
+              className="rounded-full px-3 py-1 text-xs font-semibold"
+              style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+            >
+              取消 · Cancel
+            </button>
+            <button
+              type="button"
+              onClick={onRetry}
+              className="rounded-full px-3 py-1 text-xs font-bold"
+              style={{ background: 'var(--color-accent)', color: 'var(--color-plum)' }}
+            >
+              重试 · Retry
+            </button>
+          </div>
+        </div>
+      )}
+
+      {status === 'ready' && (
+        <>
+          <p className="mt-2 leading-snug" style={{ color: 'var(--color-plum)' }}>
+            {rewrite}
+          </p>
+          <div className="mt-3 flex justify-end gap-2">
+            <button
+              type="button"
+              onClick={onCancel}
+              className="rounded-full px-3 py-1 text-xs font-semibold"
+              style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+            >
+              取消 · Cancel
+            </button>
+            <button
+              type="button"
+              onClick={onAccept}
+              className="rounded-full px-3 py-1 text-xs font-bold"
+              style={{ background: 'var(--color-accent)', color: 'var(--color-plum)' }}
+            >
+              用这个 · Use this
+            </button>
+          </div>
+        </>
+      )}
+    </div>
+  )
+}

web/src/components/Editor/SearchHighlight.ts

@@ -0,0 +1,143 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import type { EditorState, Transaction } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import type { Node as PMNode } from '@tiptap/pm/model'
+import { mapOffset } from './SuggestionHighlight'
+
+// SearchHighlight powers the in-document Find & Replace bar. Like the suggestion
+// layer it uses ProseMirror *decorations* (not stored marks), so matches are
+// recomputed from the live document on every edit and never leave a stale
+// highlight behind. Matches are found per-textblock (a query never spans a
+// paragraph break), mirroring how the rest of the editor anchors text.
+
+export interface Match {
+  from: number
+  to: number
+}
+
+interface PluginState {
+  query: string
+  caseSensitive: boolean
+  matches: Match[]
+  active: number // index into matches, or -1 when there are none
+  decorations: DecorationSet
+}
+
+export const searchPluginKey = new PluginKey<PluginState>('petalSearch')
+
+// findMatches collects every occurrence of `query` across the document's
+// textblocks and maps each to an absolute ProseMirror range.
+function findMatches(doc: PMNode, query: string, caseSensitive: boolean): Match[] {
+  if (!query) return []
+  const needle = caseSensitive ? query : query.toLowerCase()
+  const matches: Match[] = []
+  doc.descendants((node, pos) => {
+    if (!node.isTextblock) return true
+    const haystackRaw = node.textContent
+    const haystack = caseSensitive ? haystackRaw : haystackRaw.toLowerCase()
+    let idx = haystack.indexOf(needle)
+    while (idx >= 0) {
+      matches.push({
+        from: mapOffset(node, pos, idx),
+        to: mapOffset(node, pos, idx + query.length),
+      })
+      idx = haystack.indexOf(needle, idx + query.length)
+    }
+    return false // don't descend into inline children
+  })
+  return matches
+}
+
+function build(doc: PMNode, query: string, caseSensitive: boolean, preferred: number): PluginState {
+  const matches = findMatches(doc, query, caseSensitive)
+  const active = matches.length === 0 ? -1 : Math.max(0, Math.min(preferred, matches.length - 1))
+  const decos = matches.map((m, i) =>
+    Decoration.inline(m.from, m.to, {
+      class: i === active ? 'petal-find-match petal-find-match-active' : 'petal-find-match',
+    }),
+  )
+  return { query, caseSensitive, matches, active, decorations: DecorationSet.create(doc, decos) }
+}
+
+const EMPTY: PluginState = {
+  query: '',
+  caseSensitive: false,
+  matches: [],
+  active: -1,
+  decorations: DecorationSet.empty,
+}
+
+// setSearch updates the query / case-sensitivity and recomputes matches. Passing
+// an empty query clears the layer.
+export function setSearch(
+  state: EditorState,
+  dispatch: (tr: Transaction) => void,
+  query: string,
+  caseSensitive: boolean,
+) {
+  dispatch(state.tr.setMeta(searchPluginKey, { kind: 'search', query, caseSensitive }))
+}
+
+// setActive moves the highlighted (current) match by index.
+export function setActive(state: EditorState, dispatch: (tr: Transaction) => void, index: number) {
+  dispatch(state.tr.setMeta(searchPluginKey, { kind: 'active', index }))
+}
+
+// clearSearch tears the layer down (on close).
+export function clearSearch(state: EditorState, dispatch: (tr: Transaction) => void) {
+  dispatch(state.tr.setMeta(searchPluginKey, { kind: 'clear' }))
+}
+
+// getSearchState reads the live plugin state (match list + active index) so the
+// Find bar can render "n / m" and drive navigation/replacement.
+export function getSearchState(state: EditorState): PluginState {
+  return searchPluginKey.getState(state) ?? EMPTY
+}
+
+type Meta =
+  | { kind: 'search'; query: string; caseSensitive: boolean }
+  | { kind: 'active'; index: number }
+  | { kind: 'clear' }
+
+export const SearchHighlight = Extension.create({
+  name: 'searchHighlight',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin<PluginState>({
+        key: searchPluginKey,
+        state: {
+          init: () => EMPTY,
+          apply(tr, value, _oldState, newState): PluginState {
+            const meta = tr.getMeta(searchPluginKey) as Meta | undefined
+            if (meta?.kind === 'search') {
+              return build(newState.doc, meta.query, meta.caseSensitive, value.active < 0 ? 0 : value.active)
+            }
+            if (meta?.kind === 'active') {
+              if (value.matches.length === 0) return value
+              const active = ((meta.index % value.matches.length) + value.matches.length) % value.matches.length
+              const decos = value.matches.map((m, i) =>
+                Decoration.inline(m.from, m.to, {
+                  class: i === active ? 'petal-find-match petal-find-match-active' : 'petal-find-match',
+                }),
+              )
+              return { ...value, active, decorations: DecorationSet.create(newState.doc, decos) }
+            }
+            if (meta?.kind === 'clear') return EMPTY
+            // Re-anchor on any document change so highlights track edits/replaces.
+            if (tr.docChanged && value.query) {
+              return build(newState.doc, value.query, value.caseSensitive, value.active)
+            }
+            return value
+          },
+        },
+        props: {
+          decorations(state) {
+            return searchPluginKey.getState(state)?.decorations
+          },
+        },
+      }),
+    ]
+  },
+})

web/src/components/Editor/SelectionBubble.tsx

@@ -0,0 +1,107 @@
+// SelectionBubble floats above a text selection and offers to rewrite it: a
+// prominent "✨ 更自然 Say it naturally" action plus the tone vocabulary (学术,
+// 轻松, …) mirrored from the document-tone picker. Picking one hands the style up
+// to EditorCore, which calls the LLM and shows a preview. Buttons use
+// onMouseDown→preventDefault so clicking them doesn't collapse the selection
+// before the handler captures its range.
+
+export interface RewriteStyle {
+  value: string
+  emoji: string
+  zh: string
+  en: string
+}
+
+// 'natural' is the default "say it more naturally" rewrite; the rest mirror the
+// llm styleGuidance keys (and the ToneSelect labels) so the two stay in step.
+export const REWRITE_STYLES: RewriteStyle[] = [
+  { value: 'natural', emoji: '✨', zh: '更自然', en: 'Natural' },
+  { value: 'academic', emoji: '🎓', zh: '学术', en: 'Academic' },
+  { value: 'professional', emoji: '💼', zh: '专业', en: 'Professional' },
+  { value: 'casual', emoji: '☕', zh: '轻松', en: 'Casual' },
+  { value: 'humorous', emoji: '😄', zh: '幽默', en: 'Humorous' },
+  { value: 'creative', emoji: '🎨', zh: '创意', en: 'Creative' },
+  { value: 'persuasive', emoji: '📣', zh: '说服', en: 'Persuasive' },
+]
+
+interface Props {
+  style: React.CSSProperties
+  onRewrite: (style: string) => void
+  // Read the selected text aloud (null when speech isn't available — the button
+  // is then hidden).
+  onSpeak: (() => void) | null
+}
+
+const CJK = "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+
+export function SelectionBubble({ style, onRewrite, onSpeak }: Props) {
+  const [natural, ...tones] = REWRITE_STYLES
+
+  return (
+    <div
+      className="petal-selection-bubble absolute z-30 flex max-w-[360px] flex-wrap items-center gap-1.5 p-2"
+      role="toolbar"
+      aria-label="Rewrite the selection"
+      style={{
+        background: 'var(--color-surface)',
+        border: '1px solid var(--color-border)',
+        borderRadius: 'var(--radius-pill)',
+        boxShadow: 'var(--shadow-soft)',
+        fontFamily: CJK,
+        // Only the buttons capture the pointer; clicks landing on the bubble's
+        // padding/gaps fall through to the text underneath so it never blocks
+        // where the user is trying to click.
+        pointerEvents: 'none',
+        ...style,
+      }}
+    >
+      <button
+        type="button"
+        onMouseDown={(e) => e.preventDefault()} // keep the editor selection
+        onClick={() => onRewrite(natural.value)}
+        className="inline-flex h-8 items-center gap-1.5 whitespace-nowrap px-3 text-sm font-bold"
+        style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-accent)', color: 'var(--color-plum)', pointerEvents: 'auto' }}
+        title="Rewrite the selection to sound more natural"
+      >
+        <span aria-hidden>{natural.emoji}</span>
+        <span>{natural.zh}</span>
+        <span className="font-semibold" style={{ color: 'var(--color-plum)', opacity: 0.7 }}>
+          {natural.en}
+        </span>
+      </button>
+
+      {onSpeak && (
+        <button
+          type="button"
+          onMouseDown={(e) => e.preventDefault()} // keep the editor selection
+          onClick={onSpeak}
+          className="inline-flex h-8 items-center justify-center px-2 text-sm"
+          style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-surface-alt)', color: 'var(--color-plum)', pointerEvents: 'auto' }}
+          title="朗读所选 · Read selection aloud"
+          aria-label="Read selection aloud"
+        >
+          🔊
+        </button>
+      )}
+
+      <span className="mx-0.5 h-5 w-px shrink-0" style={{ background: 'var(--color-border)' }} />
+
+      {tones.map((t) => (
+        <button
+          key={t.value}
+          type="button"
+          onMouseDown={(e) => e.preventDefault()} // keep the editor selection
+          onClick={() => onRewrite(t.value)}
+          className="inline-flex h-8 items-center gap-1 whitespace-nowrap px-2.5 text-sm font-semibold"
+          style={{ borderRadius: 'var(--radius-pill)', background: 'var(--color-surface-alt)', color: 'var(--color-plum)', pointerEvents: 'auto' }}
+          onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-lavender)')}
+          onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+          title={`Rewrite in a ${t.en.toLowerCase()} tone`}
+        >
+          <span aria-hidden>{t.emoji}</span>
+          <span>{t.zh}</span>
+        </button>
+      ))}
+    </div>
+  )
+}

web/src/components/Editor/SuggestionCard.tsx

@@ -1,15 +1,7 @@
 import { useState } from 'react'
-import type { Suggestion, SuggestionType } from '../../api/client'
+import type { Suggestion } from '../../api/client'
 import { AskPetal } from './AskPetal'
-
-// Per-type accent color + human label, mirroring the design tokens.
-const TYPE_META: Record<SuggestionType, { color: string; label: string }> = {
-  grammar: { color: 'var(--color-mint)', label: 'Grammar' },
-  phrasing: { color: 'var(--color-peach)', label: 'Phrasing' },
-  idiom: { color: 'var(--color-lavender)', label: 'Idiom' },
-  clarity: { color: 'var(--color-sky)', label: 'Clarity' },
-  voice: { color: 'var(--color-honey)', label: 'Voice' },
-}
+import { TYPE_META } from './suggestionMeta'
 
 interface Props {
   suggestion: Suggestion

web/src/components/Editor/SuggestionHighlight.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest'
+import { foldTypography, findRange } from './SuggestionHighlight'
+import { Schema, type Node as PMNode } from '@tiptap/pm/model'
+
+// A minimal doc/paragraph/text schema, enough to exercise findRange's textblock
+// walk without pulling in the full editor.
+const schema = new Schema({
+  nodes: {
+    doc: { content: 'block+' },
+    paragraph: { group: 'block', content: 'inline*', toDOM: () => ['p', 0] },
+    text: { group: 'inline' },
+  },
+})
+
+// Build a single-paragraph doc with the given plaintext.
+const para = (text: string): PMNode => schema.node('doc', null, [schema.node('paragraph', null, text ? [schema.text(text)] : [])])
+
+describe('foldTypography', () => {
+  it('folds curly quotes back to straight ASCII', () => {
+    expect(foldTypography('“He’s here,” she said').folded).toBe('"He\'s here," she said')
+  })
+
+  it('folds dashes and ellipsis, keeping a source-index map across length changes', () => {
+    const { folded, map } = foldTypography('wait—really...')
+    expect(folded).toBe('wait—really…')
+    // The em dash is already one glyph; the `...` collapsed 3 source chars to 1,
+    // so the trailing sentinel still points just past the last source char.
+    expect(map[map.length - 1]).toBe('wait—really...'.length)
+  })
+
+  it('treats `--` and `...` typed-but-unconverted as their canonical glyphs', () => {
+    expect(foldTypography('a--b...c').folded).toBe('a—b…c')
+  })
+})
+
+describe('findRange typographic anchoring', () => {
+  it('anchors a model echo with straight quotes onto curly-quote document text', () => {
+    const doc = para('She said “hello” to me')
+    const range = findRange(doc, '“hello”'.replace(/[“”]/g, '"')) // model echoed "hello"
+    expect(range).not.toBeNull()
+    // The matched span must cover the curly-quoted region in the real document.
+    expect(doc.textBetween(range!.from - 1, range!.to - 1)).toContain('hello')
+  })
+
+  it('anchors an ASCII `--` echo onto an em-dash in the document', () => {
+    const doc = para('I waited—forever')
+    const range = findRange(doc, 'waited--forever')
+    expect(range).not.toBeNull()
+  })
+
+  it('still returns null when the text genuinely is not present', () => {
+    expect(findRange(para('nothing to see'), 'absent phrase')).toBeNull()
+  })
+})

web/src/components/Editor/SuggestionHighlight.ts

@@ -16,9 +16,17 @@ export const suggestionPluginKey = new PluginKey<PluginState>('petalSuggestions'
 
 interface PluginState {
   suggestions: Suggestion[]
+  // The suggestion currently emphasized from its margin card / a hover, or null.
+  // Carried in plugin state (not an imperative DOM class) so it survives the
+  // decoration repaints that fire on every document change.
+  activeId: string | null
   decorations: DecorationSet
 }
 
+// Meta carried on a transaction to update the plugin: either a fresh suggestion
+// list or a change to which suggestion is emphasized.
+type SuggestionMeta = { suggestions: Suggestion[] } | { activeId: string | null }
+
 // mapOffset converts a character offset within a textblock's flattened text into
 // an absolute ProseMirror position, accounting for inline atoms (e.g. hard
 // breaks) that occupy a position but contribute no text.
@@ -42,21 +50,87 @@ export function mapOffset(block: PMNode, blockPos: number, targetOffset: number)
   return result
 }
 
+// foldTypography canonicalizes the typographic variants that the editor's
+// Typography input rules introduce (curly quotes, em/en dashes, single-glyph
+// ellipsis) and the unicode spaces a paste can carry. The model echoes a
+// suggestion's `original` from the same text but often normalizes these back to
+// plain ASCII — straight quotes, `--`, `...` — so an exact match would miss and
+// the suggestion could be neither highlighted nor applied.
+//
+// It returns the folded string plus `map`, where map[k] is the source index at
+// which folded character k begins. A multi-character source run (`...`, `--`)
+// folds to one glyph, so lengths differ; map projects a match in folded space
+// back onto real document offsets. map has a trailing sentinel (= source length)
+// so map[start + folded.length] yields the offset just past the match.
+export function foldTypography(text: string): { folded: string; map: number[] } {
+  let folded = ''
+  const map: number[] = []
+  let i = 0
+  while (i < text.length) {
+    // Multi-character ASCII sequences the Typography rules would have replaced.
+    if (text.startsWith('...', i)) {
+      folded += '…'
+      map.push(i)
+      i += 3
+      continue
+    }
+    if (text[i] === '-' && text[i + 1] === '-') {
+      folded += '—'
+      map.push(i)
+      i += 2
+      continue
+    }
+    folded += foldChar(text[i])
+    map.push(i)
+    i++
+  }
+  map.push(text.length)
+  return { folded, map }
+}
+
+// foldChar maps a single character onto its canonical form (length-preserving).
+function foldChar(c: string): string {
+  switch (c) {
+    case '‘':
+    case '’':
+    case '‚':
+    case '‛':
+      return "'"
+    case '“':
+    case '”':
+    case '„':
+    case '‟':
+      return '"'
+    case '–': // en dash → em dash, the canonical form `--` also folds to
+      return '—'
+    case ' ': // non-breaking space
+    case ' ': // thin space
+    case ' ': // narrow no-break space
+      return ' '
+    default:
+      return c
+  }
+}
+
 // findRange locates the first occurrence of `search` within a single textblock
 // and returns its ProseMirror range, or null if the string isn't present (the
-// user may have edited or removed it since the checkpoint ran). Exported so the
-// accept flow can resolve the same span to replace.
+// user may have edited or removed it since the checkpoint ran). Matching is done
+// in canonical typographic space (see foldTypography) so curly-quote/dash/ellipsis
+// differences between the model's echo and the live document don't strand the
+// anchor. Exported so the accept flow can resolve the same span to replace.
 export function findRange(doc: PMNode, search: string): { from: number; to: number } | null {
-  if (!search) return null
+  const needle = foldTypography(search).folded
+  if (!needle) return null
   let result: { from: number; to: number } | null = null
   doc.descendants((node, pos) => {
     if (result) return false
     if (!node.isTextblock) return true // keep descending to the textblock
-    const idx = node.textContent.indexOf(search)
+    const { folded, map } = foldTypography(node.textContent)
+    const idx = folded.indexOf(needle)
     if (idx >= 0) {
       result = {
-        from: mapOffset(node, pos, idx),
-        to: mapOffset(node, pos, idx + search.length),
+        from: mapOffset(node, pos, map[idx]),
+        to: mapOffset(node, pos, map[idx + needle.length]),
       }
     }
     return false // never descend into a textblock's inline children
@@ -64,14 +138,15 @@ export function findRange(doc: PMNode, search: string): { from: number; to: numb
   return result
 }
 
-function buildDecorations(doc: PMNode, suggestions: Suggestion[]): DecorationSet {
+function buildDecorations(doc: PMNode, suggestions: Suggestion[], activeId: string | null): DecorationSet {
   const decos: Decoration[] = []
   for (const s of suggestions) {
     const range = findRange(doc, s.original)
     if (!range) continue
+    const active = s.id === activeId ? ' petal-suggestion-active' : ''
     decos.push(
       Decoration.inline(range.from, range.to, {
-        class: `petal-suggestion petal-suggestion-${s.type}`,
+        class: `petal-suggestion petal-suggestion-${s.type}${active}`,
         'data-suggestion-id': s.id,
       }),
     )
@@ -82,10 +157,22 @@ function buildDecorations(doc: PMNode, suggestions: Suggestion[]): DecorationSet
 // setSuggestions pushes a new suggestion list into the plugin. Decorations are
 // rebuilt against the current document immediately.
 export function setSuggestions(state: EditorState, dispatch: (tr: Transaction) => void, suggestions: Suggestion[]) {
-  const tr = state.tr.setMeta(suggestionPluginKey, suggestions)
+  const tr = state.tr.setMeta(suggestionPluginKey, { suggestions } satisfies SuggestionMeta)
   dispatch(tr)
 }
 
+// setActiveSuggestion marks one suggestion (or none) as emphasized, rebuilding
+// the decorations so the flagged text gets the active wash. Driven by the margin
+// rail's hover/selection so the card↔text link reads both ways.
+export function setActiveSuggestion(
+  state: EditorState,
+  dispatch: (tr: Transaction) => void,
+  activeId: string | null,
+) {
+  if (suggestionPluginKey.getState(state)?.activeId === activeId) return
+  dispatch(state.tr.setMeta(suggestionPluginKey, { activeId } satisfies SuggestionMeta))
+}
+
 export const SuggestionHighlight = Extension.create({
   name: 'suggestionHighlight',
 
@@ -94,17 +181,29 @@ export const SuggestionHighlight = Extension.create({
       new Plugin<PluginState>({
         key: suggestionPluginKey,
         state: {
-          init: () => ({ suggestions: [], decorations: DecorationSet.empty }),
+          init: () => ({ suggestions: [], activeId: null, decorations: DecorationSet.empty }),
           apply(tr, value, _oldState, newState) {
-            const meta = tr.getMeta(suggestionPluginKey) as Suggestion[] | undefined
-            if (meta) {
-              return { suggestions: meta, decorations: buildDecorations(newState.doc, meta) }
+            const meta = tr.getMeta(suggestionPluginKey) as SuggestionMeta | undefined
+            if (meta && 'suggestions' in meta) {
+              return {
+                suggestions: meta.suggestions,
+                activeId: value.activeId,
+                decorations: buildDecorations(newState.doc, meta.suggestions, value.activeId),
+              }
+            }
+            if (meta && 'activeId' in meta) {
+              return {
+                suggestions: value.suggestions,
+                activeId: meta.activeId,
+                decorations: buildDecorations(newState.doc, value.suggestions, meta.activeId),
+              }
             }
             // On any document change, re-anchor by string against the new doc.
             if (tr.docChanged) {
               return {
                 suggestions: value.suggestions,
-                decorations: buildDecorations(newState.doc, value.suggestions),
+                activeId: value.activeId,
+                decorations: buildDecorations(newState.doc, value.suggestions, value.activeId),
               }
             }
             return value

web/src/components/Editor/SuggestionRail.tsx

@@ -0,0 +1,211 @@
+import { forwardRef, useLayoutEffect, useRef, useState } from 'react'
+import type { Suggestion } from '../../api/client'
+import { AskPetal } from './AskPetal'
+import { TYPE_META } from './suggestionMeta'
+
+// Vertical breathing room kept between stacked cards when their natural anchors
+// would otherwise collide.
+const CARD_GAP = 12
+
+export interface RailItem {
+  suggestion: Suggestion
+  // Vertical offset (px) of the suggestion's highlight, relative to the editor
+  // wrapper — the position the card wants to sit beside.
+  anchorTop: number
+}
+
+interface Props {
+  items: RailItem[]
+  // The suggestion currently emphasized (its highlight hovered, or this card
+  // hovered) — gets a lifted, ring-accented treatment so the text↔card link reads.
+  activeId: string | null
+  // The card expanded to show the full explanation + Ask Petal, or null.
+  expandedId: string | null
+  onAccept: (s: Suggestion) => void
+  onDismiss: (s: Suggestion) => void
+  // Pointer entering/leaving a card, so the matching highlight can light up.
+  onHover: (id: string | null) => void
+  // A card's body was clicked — scroll its highlight into view and toggle expand.
+  onActivate: (id: string) => void
+  onToggleExpand: (id: string) => void
+}
+
+// SuggestionRail is the right-margin "comment column": every outstanding
+// suggestion as a card, vertically aligned to the text it flags, so the writer
+// sees the whole queue at once instead of hunting highlight by highlight. Cards
+// are anchored to their highlight's vertical position and pushed down only as far
+// as needed to avoid overlapping their neighbor above (a la doc-editor comments).
+export function SuggestionRail({
+  items,
+  activeId,
+  expandedId,
+  onAccept,
+  onDismiss,
+  onHover,
+  onActivate,
+  onToggleExpand,
+}: Props) {
+  // Measured resolved tops keyed by suggestion id (after collision avoidance).
+  const [tops, setTops] = useState<Record<string, number>>({})
+  const cardRefs = useRef<Map<string, HTMLDivElement>>(new Map())
+  // Bumped whenever a card's own height changes (Ask Petal streaming in, wrapping
+  // text) so the stack re-packs and cards below don't get overlapped.
+  const [measureTick, setMeasureTick] = useState(0)
+  const observerRef = useRef<ResizeObserver | null>(null)
+  if (!observerRef.current && typeof ResizeObserver !== 'undefined') {
+    observerRef.current = new ResizeObserver(() => setMeasureTick((t) => t + 1))
+  }
+  useLayoutEffect(() => () => observerRef.current?.disconnect(), [])
+
+  // Sort by anchor, then greedily stack: each card sits at its anchor unless that
+  // would overlap the previous card, in which case it slides down just enough.
+  // Re-runs whenever the anchors or the expanded card (which changes a height)
+  // shift. Reads live offsetHeight so variable-length explanations pack tightly.
+  const ordered = [...items].sort((a, b) => a.anchorTop - b.anchorTop)
+  const layoutKey = ordered.map((i) => `${i.suggestion.id}:${Math.round(i.anchorTop)}`).join('|')
+  useLayoutEffect(() => {
+    let cursor = -Infinity
+    const next: Record<string, number> = {}
+    for (const { suggestion, anchorTop } of ordered) {
+      const h = cardRefs.current.get(suggestion.id)?.offsetHeight ?? 96
+      const top = Math.max(anchorTop, cursor)
+      next[suggestion.id] = top
+      cursor = top + h + CARD_GAP
+    }
+    setTops((prev) => {
+      const ids = Object.keys(next)
+      if (ids.length === Object.keys(prev).length && ids.every((id) => prev[id] === next[id])) return prev
+      return next
+    })
+    // layoutKey captures anchor positions; expandedId/measureTick capture height
+    // changes (toggling detail, Ask Petal streaming in).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layoutKey, expandedId, measureTick])
+
+  return (
+    <div className="petal-rail petal-no-print" aria-label="Suggestions">
+      {ordered.map(({ suggestion }) => (
+        <RailCard
+          key={suggestion.id}
+          ref={(el) => {
+            const prev = cardRefs.current.get(suggestion.id)
+            if (prev && prev !== el) observerRef.current?.unobserve(prev)
+            if (el) {
+              cardRefs.current.set(suggestion.id, el)
+              observerRef.current?.observe(el)
+            } else {
+              cardRefs.current.delete(suggestion.id)
+            }
+          }}
+          suggestion={suggestion}
+          top={tops[suggestion.id] ?? 0}
+          active={activeId === suggestion.id}
+          expanded={expandedId === suggestion.id}
+          onAccept={onAccept}
+          onDismiss={onDismiss}
+          onHover={onHover}
+          onActivate={onActivate}
+          onToggleExpand={onToggleExpand}
+        />
+      ))}
+    </div>
+  )
+}
+
+interface CardProps {
+  suggestion: Suggestion
+  top: number
+  active: boolean
+  expanded: boolean
+  onAccept: (s: Suggestion) => void
+  onDismiss: (s: Suggestion) => void
+  onHover: (id: string | null) => void
+  onActivate: (id: string) => void
+  onToggleExpand: (id: string) => void
+}
+
+const RailCard = forwardRef<HTMLDivElement, CardProps>(function RailCard(
+  { suggestion, top, active, expanded, onAccept, onDismiss, onHover, onActivate, onToggleExpand },
+  ref,
+) {
+  const meta = TYPE_META[suggestion.type]
+  const hasReplacement = suggestion.replacement.trim() !== ''
+
+  return (
+    <div
+      ref={ref}
+      role="group"
+      aria-label={`${meta.label} suggestion`}
+      onMouseEnter={() => onHover(suggestion.id)}
+      onMouseLeave={() => onHover(null)}
+      className={`petal-rail-card${active ? ' petal-rail-card-active' : ''}`}
+      style={{ top, borderLeftColor: meta.color }}
+    >
+      <div className="flex items-center justify-between">
+        <span
+          className="inline-flex items-center rounded-full px-2 py-0.5 text-[0.68rem] font-bold"
+          style={{ background: meta.color, color: 'var(--color-plum)' }}
+        >
+          {meta.label}
+        </span>
+        <button
+          type="button"
+          aria-label="Dismiss suggestion"
+          onClick={() => onDismiss(suggestion)}
+          className="petal-rail-x"
+        >
+          ✕
+        </button>
+      </div>
+
+      {/* The body toggles the expanded explanation + Ask Petal and points the
+          editor at the flagged text. */}
+      <button type="button" onClick={() => onActivate(suggestion.id)} className="mt-2 block w-full text-left">
+        {hasReplacement && (
+          <span className="flex flex-col gap-0.5" style={{ fontFamily: 'var(--font-body)' }}>
+            <span className="truncate text-[0.9rem] line-through" style={{ color: 'var(--color-muted)' }}>
+              {suggestion.original}
+            </span>
+            <span className="truncate text-[0.9rem] font-medium" style={{ color: 'var(--color-plum)' }}>
+              {suggestion.replacement}
+            </span>
+          </span>
+        )}
+        <span
+          className={`mt-1.5 block text-[0.82rem] leading-snug${expanded ? '' : ' line-clamp-2'}`}
+          style={{ color: 'var(--color-plum)' }}
+        >
+          {suggestion.explanation}
+        </span>
+      </button>
+
+      {expanded && <AskPetal suggestionId={suggestion.id} explanation={suggestion.explanation} />}
+
+      <div className="mt-2.5 flex items-center gap-2">
+        {hasReplacement && (
+          <button
+            type="button"
+            onClick={() => onAccept(suggestion)}
+            className="rounded-full px-3 py-1 text-xs font-bold text-white"
+            style={{ background: 'var(--color-accent)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-accent-hover)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-accent)')}
+          >
+            Accept
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={() => onToggleExpand(suggestion.id)}
+          className="rounded-full px-2.5 py-1 text-xs font-bold transition-colors"
+          style={{
+            background: expanded ? 'var(--color-surface-alt)' : 'transparent',
+            color: 'var(--color-accent-hover)',
+          }}
+        >
+          {expanded ? 'Hide Petal' : 'Ask Petal ✨'}
+        </button>
+      </div>
+    </div>
+  )
+})

web/src/components/Editor/Typography.ts

@@ -0,0 +1,29 @@
+import { Extension, textInputRule } from '@tiptap/core'
+
+// Typography adds the small print-shop niceties as you type: curly quotes,
+// em-dashes, and a single-character ellipsis. Implemented as input rules (no
+// dependency, offline-friendly — matching FontSize.ts's hand-rolled approach),
+// and every one is plain Undo-able if it ever fires when you didn't want it.
+//
+// CJK is untouched: these rules only rewrite ASCII quotes/dashes/dots, never the
+// fullwidth forms a Mandarin sentence uses.
+export const Typography = Extension.create({
+  name: 'petalTypography',
+
+  addInputRules() {
+    return [
+      // “ opening double quote — after start, whitespace, or an opening bracket.
+      textInputRule({ find: /(?:^|[\s{[(<'"‘“])(")$/, replace: '“' }),
+      // ” closing double quote — any other time you type a ".
+      textInputRule({ find: /"$/, replace: '”' }),
+      // ‘ opening single quote.
+      textInputRule({ find: /(?:^|[\s{[(<'"‘“])(')$/, replace: '‘' }),
+      // ’ closing single quote / apostrophe.
+      textInputRule({ find: /'$/, replace: '’' }),
+      // — em dash from a double hyphen.
+      textInputRule({ find: /--$/, replace: '—' }),
+      // … ellipsis from three dots.
+      textInputRule({ find: /\.\.\.$/, replace: '…' }),
+    ]
+  },
+})

web/src/components/Editor/WordCard.tsx

@@ -1,4 +1,5 @@
 import type { WordInfo } from '../../api/client'
+import { speak, speechSupported } from '../../audio/speech'
 
 // WordCard is the right-click popover for any word: its dictionary definition(s)
 // on top and tappable synonym pills below. Clicking a synonym replaces the word
@@ -17,7 +18,9 @@ interface Props {
 export function WordCard({ word, info, loading, style, onReplace }: Props) {
   const definitions = info?.definitions ?? []
   const synonyms = info?.synonyms ?? []
-  const empty = !loading && definitions.length === 0 && synonyms.length === 0
+  const gloss = info?.gloss ?? ''
+  const phonetic = info?.phonetic ?? ''
+  const empty = !loading && !gloss && definitions.length === 0 && synonyms.length === 0
 
   return (
     <div
@@ -45,8 +48,41 @@ export function WordCard({ word, info, loading, style, onReplace }: Props) {
         <span className="font-bold" style={{ color: 'var(--color-plum)' }}>
           {word}
         </span>
+        {speechSupported() && (
+          <button
+            type="button"
+            onClick={() => speak(word)}
+            aria-label={`Pronounce ${word}`}
+            title="朗读 · Read aloud"
+            className="ml-auto flex h-7 w-7 items-center justify-center rounded-full text-sm"
+            style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+          >
+            🔊
+          </button>
+        )}
       </div>
 
+      {/* How to say it — the pronunciation aid for an English learner, paired
+          with the 🔊 button above. */}
+      {phonetic && (
+        <p className="mt-1.5 text-sm" style={{ color: 'var(--color-muted)' }}>
+          /{phonetic}/
+        </p>
+      )}
+
+      {/* Chinese gloss first — it's what the Mandarin-speaking writer reaches for. */}
+      {gloss && (
+        <p
+          className="mt-2.5 leading-snug"
+          style={{
+            color: 'var(--color-plum)',
+            fontFamily: "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif",
+          }}
+        >
+          {gloss}
+        </p>
+      )}
+
       {loading && (
         <div className="mt-3 inline-flex items-center gap-1.5" style={{ color: 'var(--color-muted)' }}>
           <span

web/src/components/Editor/suggestionMeta.ts

@@ -0,0 +1,12 @@
+import type { SuggestionType } from '../../api/client'
+
+// Per-type accent color + human label, mirroring the design tokens. Shared by the
+// inline hover SuggestionCard and the margin SuggestionRail so a given suggestion
+// type reads the same color/name wherever it surfaces.
+export const TYPE_META: Record<SuggestionType, { color: string; label: string }> = {
+  grammar: { color: 'var(--color-mint)', label: 'Grammar' },
+  phrasing: { color: 'var(--color-peach)', label: 'Phrasing' },
+  idiom: { color: 'var(--color-lavender)', label: 'Idiom' },
+  clarity: { color: 'var(--color-sky)', label: 'Clarity' },
+  voice: { color: 'var(--color-honey)', label: 'Voice' },
+}

web/src/components/Export/ExportMenu.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useState } from 'react'
+import { api, type ExportFormat } from '../../api/client'
+
+// ExportMenu is the "get your writing out of Petal" dropdown. File formats are
+// plain <a download> links to the server's export endpoint (which sets the
+// Content-Disposition filename, CJK and all). "Print / Save as PDF" calls the
+// browser print dialog against the print stylesheet, so PDF stays CJK-safe with
+// no server-side font embedding. Bilingual zh·en labels match Petal's chrome.
+
+interface FormatOption {
+  format: ExportFormat
+  emoji: string
+  zh: string
+  en: string
+}
+
+const FORMATS: FormatOption[] = [
+  { format: 'docx', emoji: '📄', zh: 'Word 文档', en: 'Word (.docx)' },
+  { format: 'md', emoji: '📝', zh: 'Markdown', en: 'Markdown (.md)' },
+  { format: 'html', emoji: '🌐', zh: '网页', en: 'Web page (.html)' },
+  { format: 'txt', emoji: '🧾', zh: '纯文本', en: 'Plain text (.txt)' },
+]
+
+interface Props {
+  docId: string
+}
+
+export function ExportMenu({ docId }: Props) {
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', onDown)
+    return () => document.removeEventListener('mousedown', onDown)
+  }, [open])
+
+  return (
+    <div ref={ref} className="relative shrink-0">
+      <button
+        type="button"
+        aria-label="Export document"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen((o) => !o)}
+        className="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)',
+        }}
+        title="Save or print your writing"
+      >
+        <span aria-hidden>⬇</span>
+        <span>导出</span>
+        <span style={{ color: 'var(--color-muted)' }}>· Export</span>
+      </button>
+
+      {open && (
+        <div
+          role="menu"
+          className="petal-word-card absolute right-0 z-30 mt-1.5 p-1.5"
+          style={{
+            width: 220,
+            background: 'var(--color-surface)',
+            border: '1px solid var(--color-border)',
+            borderRadius: 'var(--radius-card)',
+            boxShadow: 'var(--shadow-soft)',
+          }}
+        >
+          {FORMATS.map((f) => (
+            <a
+              key={f.format}
+              role="menuitem"
+              href={api.exportUrl(docId, f.format)}
+              download
+              onClick={() => setOpen(false)}
+              className="flex w-full items-center gap-2 rounded-xl px-2.5 py-1.5 text-left text-sm font-semibold no-underline"
+              style={{ color: 'var(--color-plum)' }}
+              onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+              onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+            >
+              <span aria-hidden>{f.emoji}</span>
+              <span>{f.zh}</span>
+              <span className="font-normal" style={{ color: 'var(--color-muted)' }}>
+                {f.en}
+              </span>
+            </a>
+          ))}
+
+          <div className="my-1 h-px" style={{ background: 'var(--color-border)' }} />
+
+          <button
+            type="button"
+            role="menuitem"
+            onClick={() => {
+              setOpen(false)
+              // Defer so the menu unmounts before the print dialog snapshots.
+              setTimeout(() => window.print(), 50)
+            }}
+            className="flex w-full items-center gap-2 rounded-xl px-2.5 py-1.5 text-left text-sm font-semibold"
+            style={{ background: 'transparent', color: 'var(--color-plum)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+          >
+            <span aria-hidden>🖨️</span>
+            <span>打印 / PDF</span>
+            <span className="font-normal" style={{ color: 'var(--color-muted)' }}>
+              Print / PDF
+            </span>
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}

web/src/components/History/HistoryPanel.tsx

@@ -0,0 +1,230 @@
+import { useCallback, useEffect, useState } from 'react'
+import { api, type Document, type DocumentVersion } from '../../api/client'
+
+// HistoryPanel is the "time machine" drawer: every snapshot Petal kept of this
+// document, newest first, with a one-click preview and restore. It's the safety
+// net that makes trusting Petal with real writing reasonable — a bad edit or a
+// regretted rewrite is always recoverable, and restoring is itself undoable
+// (the server keeps a pre_restore copy). Bilingual, zh-first, to match chrome.
+
+interface Props {
+  docId: string
+  onClose: () => void
+  // Called after a successful restore with the freshly-restored document so the
+  // editor can reload it.
+  onRestored: (doc: Document) => void
+}
+
+// kindLabel maps a snapshot kind to its bilingual badge + accent color.
+const KIND: Record<DocumentVersion['kind'], { zh: string; en: string; color: string }> = {
+  manual: { zh: '保存点', en: 'Saved point', color: 'var(--color-accent)' },
+  auto: { zh: '自动', en: 'Auto', color: 'var(--color-muted)' },
+  pre_restore: { zh: '恢复前', en: 'Before restore', color: 'var(--color-lavender)' },
+}
+
+// relativeTime renders a UTC timestamp as a gentle "x minutes ago" string.
+function relativeTime(iso: string): string {
+  const then = new Date(iso).getTime()
+  const secs = Math.max(0, Math.round((Date.now() - then) / 1000))
+  if (secs < 60) return 'just now · 刚刚'
+  const mins = Math.round(secs / 60)
+  if (mins < 60) return `${mins} min ago · ${mins} 分钟前`
+  const hrs = Math.round(mins / 60)
+  if (hrs < 24) return `${hrs} hr ago · ${hrs} 小时前`
+  const days = Math.round(hrs / 24)
+  return `${days} day${days > 1 ? 's' : ''} ago · ${days} 天前`
+}
+
+export function HistoryPanel({ docId, onClose, onRestored }: Props) {
+  const [versions, setVersions] = useState<DocumentVersion[] | null>(null)
+  const [error, setError] = useState(false)
+  const [selected, setSelected] = useState<DocumentVersion | null>(null)
+  const [preview, setPreview] = useState<DocumentVersion | null>(null)
+  const [busy, setBusy] = useState(false)
+
+  const load = useCallback(async () => {
+    setError(false)
+    try {
+      setVersions(await api.listVersions(docId))
+    } catch {
+      setError(true)
+    }
+  }, [docId])
+
+  useEffect(() => {
+    void load()
+  }, [load])
+
+  // Escape closes the drawer.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  const choose = useCallback(
+    async (v: DocumentVersion) => {
+      setSelected(v)
+      setPreview(null)
+      try {
+        setPreview(await api.getVersion(docId, v.id))
+      } catch {
+        setPreview(null)
+      }
+    },
+    [docId],
+  )
+
+  const restore = useCallback(async () => {
+    if (!selected) return
+    setBusy(true)
+    try {
+      const doc = await api.restoreVersion(docId, selected.id)
+      onRestored(doc)
+      onClose()
+    } catch {
+      setBusy(false)
+    }
+  }, [docId, selected, onRestored, onClose])
+
+  return (
+    <div className="petal-no-print fixed inset-0 z-40 flex justify-end">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0"
+        style={{ background: 'rgba(61, 46, 57, 0.18)' }}
+        onClick={onClose}
+      />
+
+      <aside
+        className="relative flex h-full w-full max-w-[380px] flex-col"
+        style={{
+          background: 'var(--color-surface)',
+          borderLeft: '1px solid var(--color-border)',
+          boxShadow: 'var(--shadow-soft)',
+        }}
+      >
+        <header
+          className="flex items-center justify-between px-5 py-4"
+          style={{ borderBottom: '1px solid var(--color-border)' }}
+        >
+          <div>
+            <div className="text-base font-extrabold text-plum">历史 · History</div>
+            <div className="text-xs" style={{ color: 'var(--color-muted)' }}>
+              Every saved moment — nothing is ever lost 🌸
+            </div>
+          </div>
+          <button
+            type="button"
+            aria-label="Close history"
+            onClick={onClose}
+            className="flex h-8 w-8 items-center justify-center rounded-full text-lg"
+            style={{ color: 'var(--color-muted)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+          >
+            ✕
+          </button>
+        </header>
+
+        <div className="min-h-0 flex-1 overflow-y-auto px-3 py-3">
+          {error ? (
+            <div className="px-2 py-6 text-center text-sm" style={{ color: 'var(--color-muted)' }}>
+              Couldn’t load history just now.
+              <button onClick={load} className="ml-1 font-bold text-plum underline">
+                Try again
+              </button>
+            </div>
+          ) : versions === null ? (
+            <div className="px-2 py-6 text-center text-sm" style={{ color: 'var(--color-muted)' }}>
+              Loading…
+            </div>
+          ) : versions.length === 0 ? (
+            <div className="px-2 py-8 text-center text-sm" style={{ color: 'var(--color-muted)' }}>
+              No snapshots yet. Keep writing — Petal saves restore points as you go.
+            </div>
+          ) : (
+            <ul className="flex flex-col gap-1.5">
+              {versions.map((v) => {
+                const k = KIND[v.kind]
+                const active = selected?.id === v.id
+                return (
+                  <li key={v.id}>
+                    <button
+                      type="button"
+                      onClick={() => choose(v)}
+                      className="flex w-full flex-col gap-1 rounded-2xl px-3 py-2.5 text-left"
+                      style={{
+                        background: active ? 'var(--color-surface-alt)' : 'transparent',
+                        border: `1px solid ${active ? 'var(--color-border)' : 'transparent'}`,
+                      }}
+                      onMouseEnter={(e) =>
+                        (e.currentTarget.style.background = 'var(--color-surface-alt)')
+                      }
+                      onMouseLeave={(e) =>
+                        (e.currentTarget.style.background = active
+                          ? 'var(--color-surface-alt)'
+                          : 'transparent')
+                      }
+                    >
+                      <div className="flex items-center justify-between gap-2">
+                        <span className="truncate text-sm font-bold text-plum">{v.title || 'Untitled'}</span>
+                        <span
+                          className="shrink-0 rounded-full px-2 py-0.5 text-[10px] font-bold"
+                          style={{ background: k.color, color: '#fff' }}
+                        >
+                          {k.zh} · {k.en}
+                        </span>
+                      </div>
+                      <div className="flex items-center justify-between gap-2 text-xs" style={{ color: 'var(--color-muted)' }}>
+                        <span>{relativeTime(v.created_at)}</span>
+                        <span>{v.word_count} words</span>
+                      </div>
+                    </button>
+                  </li>
+                )
+              })}
+            </ul>
+          )}
+        </div>
+
+        {selected && (
+          <div
+            className="shrink-0 px-4 py-3"
+            style={{ borderTop: '1px solid var(--color-border)', background: 'var(--color-surface-alt)' }}
+          >
+            <div className="mb-2 text-xs font-bold" style={{ color: 'var(--color-muted)' }}>
+              预览 · Preview
+            </div>
+            <div
+              className="mb-3 max-h-32 overflow-y-auto whitespace-pre-wrap rounded-xl px-3 py-2 text-sm"
+              style={{
+                background: 'var(--color-surface)',
+                color: 'var(--color-plum)',
+                fontFamily: 'var(--font-body)',
+              }}
+            >
+              {preview ? preview.content_text || '(empty)' : 'Loading…'}
+            </div>
+            <button
+              type="button"
+              onClick={restore}
+              disabled={busy}
+              className="w-full rounded-full py-2.5 text-sm font-extrabold text-white disabled:opacity-60"
+              style={{ background: 'var(--color-accent)' }}
+              onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-accent-hover)')}
+              onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-accent)')}
+            >
+              {busy ? 'Restoring…' : '恢复这个版本 · Restore this version'}
+            </button>
+            <div className="mt-1.5 text-center text-[11px]" style={{ color: 'var(--color-muted)' }}>
+              Your current draft is saved first, so this is undoable.
+            </div>
+          </div>
+        )}
+      </aside>
+    </div>
+  )
+}

web/src/components/StatusBar/SoundToggle.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react'
+import { isSoundEnabled, onSoundEnabledChange, playPop, setSoundEnabled } from '../../audio/sounds'
+
+// A tiny mute toggle for Petal's cute sounds, tucked at the right of the status
+// bar. Bilingual tooltip (she reads Mandarin first), and a soft confirming pop
+// when sounds are turned back on so the choice is audible.
+export function SoundToggle() {
+  const [on, setOn] = useState(isSoundEnabled)
+
+  // Stay in sync if the setting is flipped elsewhere.
+  useEffect(() => onSoundEnabledChange(setOn), [])
+
+  const toggle = () => {
+    const next = !on
+    setSoundEnabled(next)
+    setOn(next)
+    if (next) playPop() // a little hello when re-enabled
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-pressed={on}
+      title={on ? '声音开 · Sounds on' : '声音关 · Sounds off'}
+      aria-label={on ? 'Mute Petal sounds' : 'Unmute Petal sounds'}
+      className="flex items-center justify-center rounded-full px-2 py-1 text-xl leading-none transition-colors"
+      style={{ color: on ? 'var(--color-accent)' : 'var(--color-muted)', lineHeight: 1 }}
+      onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--color-accent-hover)')}
+      onMouseLeave={(e) =>
+        (e.currentTarget.style.color = on ? 'var(--color-accent)' : 'var(--color-muted)')
+      }
+    >
+      <span aria-hidden>{on ? '🔔' : '🔕'}</span>
+    </button>
+  )
+}

web/src/components/StatusBar/StatusBar.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 import type { SaveStatus } from '../../hooks/useAutoSave'
 import { StatsPanel } from './StatsPanel'
+import { SoundToggle } from './SoundToggle'
 
 interface Props {
   wordCount: number
@@ -11,6 +12,9 @@ interface Props {
   checking: boolean
   // True while a whole-document voice pass runs — shows a breathing honey dot.
   voicing: boolean
+  // True when Petal can't reach its LLM helper — shows a gentle, reassuring note
+  // (the writing still saves locally, so this is awareness, not an error).
+  llmDown: boolean
 }
 
 const SAVE_LABEL: Record<SaveStatus, string> = {
@@ -24,7 +28,7 @@ const SAVE_LABEL: Record<SaveStatus, string> = {
 // StatusBar is the slim footer: word count on the left, save state and the
 // grammar-checkpoint indicator on the right. The checkpoint dot is a soft rose
 // circle that breathes while a check is in flight (spec → Signature animations).
-export function StatusBar({ wordCount, text, saveStatus, checking, voicing }: Props) {
+export function StatusBar({ wordCount, text, saveStatus, checking, voicing, llmDown }: Props) {
   const label = SAVE_LABEL[saveStatus]
   // The expanded stats panel toggles open when the word count is clicked.
   const [statsOpen, setStatsOpen] = useState(false)
@@ -41,7 +45,7 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing }: Pr
 
   return (
     <footer
-      className="flex h-9 shrink-0 items-center gap-3 px-6 text-xs"
+      className="flex h-11 shrink-0 items-center gap-3 px-6 text-sm"
       style={{ borderTop: '1px solid var(--color-border)', color: 'var(--color-muted)' }}
     >
       <div className="relative" ref={statsRef}>
@@ -50,7 +54,7 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing }: Pr
           onClick={() => setStatsOpen((o) => !o)}
           aria-haspopup="dialog"
           aria-expanded={statsOpen}
-          className="rounded-full px-1.5 py-0.5 font-semibold transition-colors"
+          className="rounded-full px-2 py-0.5 text-[0.95rem] font-bold transition-colors"
           style={{ color: statsOpen ? 'var(--color-accent-hover)' : 'inherit' }}
           onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--color-accent-hover)')}
           onMouseLeave={(e) =>
@@ -86,6 +90,20 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing }: Pr
           </span>
         </>
       )}
+      {llmDown && !checking && !voicing && (
+        <>
+          <span aria-hidden>·</span>
+          <span
+            className="inline-flex items-center gap-1.5"
+            title="Petal can't reach its writing helper right now — your text is still saved."
+            style={{ color: 'var(--color-honey)' }}
+          >
+            <span aria-hidden>🌙</span>
+            <span>小助手在休息</span>
+            <span style={{ opacity: 0.75 }}>· Petal's helper is resting · 文字已保存</span>
+          </span>
+        </>
+      )}
       {label && (
         <>
           <span aria-hidden>·</span>
@@ -103,6 +121,9 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing }: Pr
           </span>
         </>
       )}
+      <div className="ml-auto">
+        <SoundToggle />
+      </div>
     </footer>
   )
 }

web/src/components/Toolbar/Toolbar.tsx

@@ -1,5 +1,7 @@
 import type { Editor } from '@tiptap/react'
 import { useEditorState } from '@tiptap/react'
+import { useEffect, useRef, useState } from 'react'
+import { uploadImageInto } from '../Editor/EditorCore'
 
 interface Props {
   editor: Editor | null
@@ -15,18 +17,21 @@ function TBtn({
   active,
   disabled,
   label,
+  title,
   children,
 }: {
   onClick: () => void
   active?: boolean
   disabled?: boolean
   label: string
+  title?: string
   children: React.ReactNode
 }) {
   return (
     <button
       type="button"
       aria-label={label}
+      title={title ?? label}
       aria-pressed={active}
       disabled={disabled}
       onMouseDown={(e) => e.preventDefault()} // keep editor selection
@@ -47,10 +52,125 @@ const Divider = () => (
   <span className="mx-1 h-5 w-px" style={{ background: 'var(--color-border)' }} />
 )
 
+// A popover anchored under its trigger. The trigger + panel share a relative
+// wrapper; `open`/`onClose` are owned by the toolbar so only one is open at once.
+// A pointer-down outside the wrapper closes it.
+function Popover({
+  open,
+  onClose,
+  trigger,
+  children,
+  width = 200,
+}: {
+  open: boolean
+  onClose: () => void
+  trigger: React.ReactNode
+  children: React.ReactNode
+  width?: number
+}) {
+  const ref = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) onClose()
+    }
+    document.addEventListener('mousedown', onDown)
+    return () => document.removeEventListener('mousedown', onDown)
+  }, [open, onClose])
+  return (
+    <div ref={ref} className="relative flex items-center">
+      {trigger}
+      {open && (
+        <div
+          className="absolute left-0 top-full z-40 mt-1.5 p-2"
+          style={{
+            width,
+            borderRadius: 'var(--radius-card)',
+            background: 'var(--color-surface)',
+            border: '1px solid var(--color-border)',
+            boxShadow: 'var(--shadow-soft)',
+          }}
+        >
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+// Text-color swatches. `null` clears the color back to the theme default.
+const TEXT_COLORS: { label: string; value: string | null }[] = [
+  { label: 'Default', value: null },
+  { label: 'Rose', value: '#D98AAF' },
+  { label: 'Coral', value: '#E0785C' },
+  { label: 'Honey', value: '#C68B2E' },
+  { label: 'Green', value: '#4F9E7F' },
+  { label: 'Sky', value: '#4E8FCC' },
+  { label: 'Lavender', value: '#7D63C4' },
+  { label: 'Plum', value: '#3D2E39' },
+]
+
+// Highlighter colors — soft pastels so dark text stays readable on top.
+const HIGHLIGHTS: { label: string; value: string | null }[] = [
+  { label: 'None', value: null },
+  { label: 'Yellow', value: '#FFF1A8' },
+  { label: 'Pink', value: '#FAD4E4' },
+  { label: 'Mint', value: '#CDEFE2' },
+  { label: 'Peach', value: '#FBE0CF' },
+  { label: 'Lavender', value: '#E6DCFA' },
+  { label: 'Sky', value: '#D6E8FB' },
+]
+
+// Font-size presets. `null` clears back to the document default.
+const SIZES: { label: string; value: string | null; em: string }[] = [
+  { label: 'Small', value: '0.85em', em: '0.85em' },
+  { label: 'Normal', value: null, em: '1em' },
+  { label: 'Large', value: '1.3em', em: '1.3em' },
+  { label: 'Title', value: '1.7em', em: '1.7em' },
+]
+
+// A round color chip used in the color/highlight palettes.
+function Swatch({
+  color,
+  active,
+  onClick,
+  title,
+}: {
+  color: string | null
+  active: boolean
+  onClick: () => void
+  title: string
+}) {
+  return (
+    <button
+      type="button"
+      title={title}
+      aria-label={title}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={onClick}
+      className="flex h-7 w-7 items-center justify-center"
+      style={{
+        borderRadius: 'var(--radius-pill)',
+        background: color ?? 'var(--color-surface)',
+        border: active ? '2px solid var(--color-accent)' : '1px solid var(--color-border)',
+        // The "clear" chip (no color) shows a tiny diagonal stroke.
+        backgroundImage: color
+          ? undefined
+          : 'linear-gradient(135deg, transparent 44%, var(--color-accent) 44%, var(--color-accent) 56%, transparent 56%)',
+      }}
+    />
+  )
+}
+
 // Toolbar renders inline formatting controls bound to the live Tiptap editor.
 // useEditorState subscribes to just the flags it reads, so the buttons reflect
 // the current selection without re-rendering the whole tree on every keystroke.
 export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
+  // Which popover (if any) is open. Only one at a time.
+  const [menu, setMenu] = useState<'color' | 'highlight' | 'size' | 'link' | 'table' | 'outline' | null>(null)
+  const [linkUrl, setLinkUrl] = useState('')
+  const fileInputRef = useRef<HTMLInputElement>(null)
+
   const state = useEditorState({
     editor,
     selector: ({ editor }) =>
@@ -59,27 +179,92 @@ export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
             bold: editor.isActive('bold'),
             italic: editor.isActive('italic'),
             underline: editor.isActive('underline'),
+            strike: editor.isActive('strike'),
             h1: editor.isActive('heading', { level: 1 }),
             h2: editor.isActive('heading', { level: 2 }),
+            h3: editor.isActive('heading', { level: 3 }),
             bullet: editor.isActive('bulletList'),
+            ordered: editor.isActive('orderedList'),
             left: editor.isActive({ textAlign: 'left' }),
             center: editor.isActive({ textAlign: 'center' }),
             right: editor.isActive({ textAlign: 'right' }),
+            link: editor.isActive('link'),
+            inTable: editor.isActive('table'),
+            color: editor.getAttributes('textStyle').color ?? null,
+            highlight: editor.getAttributes('highlight').color ?? null,
+            fontSize: editor.getAttributes('textStyle').fontSize ?? null,
+            canUndo: editor.can().undo(),
+            canRedo: editor.can().redo(),
           }
         : null,
   })
 
   if (!editor || !state) return null
 
+  const close = () => setMenu(null)
+
+  // Open the link popover, pre-filling the field with any link already on the
+  // selection so it can be edited rather than retyped.
+  const openLink = () => {
+    setLinkUrl(editor.getAttributes('link').href ?? '')
+    setMenu(menu === 'link' ? null : 'link')
+  }
+
+  const applyLink = () => {
+    const url = linkUrl.trim()
+    if (!url) {
+      editor.chain().focus().extendMarkRange('link').unsetLink().run()
+    } else {
+      // Default to https:// when the writer omits a scheme.
+      const href = /^(https?:|mailto:|\/)/i.test(url) ? url : `https://${url}`
+      editor.chain().focus().extendMarkRange('link').setLink({ href }).run()
+    }
+    close()
+  }
+
+  // Collect the document's headings (with their positions) for the outline. Read
+  // fresh each time the popover opens, so it always reflects the current doc.
+  const headings: { level: number; text: string; pos: number }[] = []
+  if (menu === 'outline') {
+    editor.state.doc.descendants((node, pos) => {
+      if (node.type.name === 'heading') {
+        headings.push({ level: (node.attrs.level as number) || 1, text: node.textContent || '（无标题）', pos })
+      }
+    })
+  }
+
+  // Scroll a heading into view without moving the selection (which would pop the
+  // rewrite bubble). domAtPos resolves the heading's DOM node to scroll to.
+  const gotoHeading = (pos: number) => {
+    const dom = editor.view.domAtPos(pos + 1)
+    const el = dom.node.nodeType === Node.TEXT_NODE ? dom.node.parentElement : (dom.node as HTMLElement)
+    el?.scrollIntoView({ block: 'start', behavior: 'smooth' })
+    close()
+  }
+
+  const onPickImage = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0]
+    if (file) uploadImageInto(editor.view, file)
+    e.target.value = '' // allow re-picking the same file
+  }
+
   return (
     <div
-      className="mb-4 flex items-center gap-0.5 self-start px-2 py-1.5"
+      className="petal-toolbar mb-4 flex items-center gap-0.5 self-start px-2 py-1.5"
       style={{
-        borderRadius: 'var(--radius-pill)',
+        borderRadius: 'var(--radius-card)',
         background: 'var(--color-surface)',
         boxShadow: 'var(--shadow-soft)',
       }}
     >
+      <TBtn label="Undo" disabled={!state.canUndo} onClick={() => editor.chain().focus().undo().run()}>
+        ↶
+      </TBtn>
+      <TBtn label="Redo" disabled={!state.canRedo} onClick={() => editor.chain().focus().redo().run()}>
+        ↷
+      </TBtn>
+      <Divider />
+
       <TBtn label="Bold" active={state.bold} onClick={() => editor.chain().focus().toggleBold().run()}>
         <span className="font-extrabold">B</span>
       </TBtn>
@@ -93,51 +278,301 @@ export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
       >
         <span className="underline">U</span>
       </TBtn>
+      <TBtn label="Strikethrough" active={state.strike} onClick={() => editor.chain().focus().toggleStrike().run()}>
+        <span className="line-through">S</span>
+      </TBtn>
       <Divider />
-      <TBtn
-        label="Heading 1"
-        active={state.h1}
-        onClick={() => editor.chain().focus().toggleHeading({ level: 1 }).run()}
+
+      {/* Text color */}
+      <Popover
+        open={menu === 'color'}
+        onClose={close}
+        width={188}
+        trigger={
+          <TBtn label="Text color" active={menu === 'color'} onClick={() => setMenu(menu === 'color' ? null : 'color')}>
+            <span className="flex flex-col items-center leading-none">
+              <span className="text-sm font-bold">A</span>
+              <span
+                className="mt-0.5 h-1 w-4 rounded-full"
+                style={{ background: state.color ?? 'var(--color-accent)' }}
+              />
+            </span>
+          </TBtn>
+        }
       >
+        <div className="grid grid-cols-4 gap-1.5">
+          {TEXT_COLORS.map((c) => (
+            <Swatch
+              key={c.label}
+              color={c.value}
+              title={c.label}
+              active={state.color === c.value}
+              onClick={() => {
+                if (c.value) editor.chain().focus().setColor(c.value).run()
+                else editor.chain().focus().unsetColor().run()
+                close()
+              }}
+            />
+          ))}
+        </div>
+      </Popover>
+
+      {/* Highlight */}
+      <Popover
+        open={menu === 'highlight'}
+        onClose={close}
+        width={170}
+        trigger={
+          <TBtn
+            label="Highlight"
+            active={menu === 'highlight' || !!state.highlight}
+            onClick={() => setMenu(menu === 'highlight' ? null : 'highlight')}
+          >
+            <span
+              className="flex h-5 w-5 items-center justify-center rounded text-xs font-bold"
+              style={{ background: state.highlight ?? '#FFF1A8', color: 'var(--color-plum)' }}
+            >
+              H
+            </span>
+          </TBtn>
+        }
+      >
+        <div className="grid grid-cols-4 gap-1.5">
+          {HIGHLIGHTS.map((c) => (
+            <Swatch
+              key={c.label}
+              color={c.value}
+              title={c.label}
+              active={state.highlight === c.value}
+              onClick={() => {
+                if (c.value) editor.chain().focus().setHighlight({ color: c.value }).run()
+                else editor.chain().focus().unsetHighlight().run()
+                close()
+              }}
+            />
+          ))}
+        </div>
+      </Popover>
+
+      {/* Font size */}
+      <Popover
+        open={menu === 'size'}
+        onClose={close}
+        width={140}
+        trigger={
+          <TBtn label="Text size" active={menu === 'size'} onClick={() => setMenu(menu === 'size' ? null : 'size')}>
+            <span className="text-xs font-bold tracking-tight">
+              <span className="text-[0.7rem]">A</span>
+              <span className="text-sm">A</span>
+            </span>
+          </TBtn>
+        }
+      >
+        <div className="flex flex-col gap-0.5">
+          {SIZES.map((s) => {
+            const active = state.fontSize === s.value
+            return (
+              <button
+                key={s.label}
+                type="button"
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => {
+                  if (s.value) editor.chain().focus().setFontSize(s.value).run()
+                  else editor.chain().focus().unsetFontSize().run()
+                  close()
+                }}
+                className="flex items-center justify-between rounded px-2 py-1 text-left"
+                style={{
+                  background: active ? 'var(--color-surface-alt)' : 'transparent',
+                  color: active ? 'var(--color-accent-hover)' : 'var(--color-plum)',
+                }}
+              >
+                <span style={{ fontSize: s.em }}>{s.label}</span>
+              </button>
+            )
+          })}
+        </div>
+      </Popover>
+      <Divider />
+
+      <TBtn label="Heading 1" active={state.h1} onClick={() => editor.chain().focus().toggleHeading({ level: 1 }).run()}>
         H1
       </TBtn>
-      <TBtn
-        label="Heading 2"
-        active={state.h2}
-        onClick={() => editor.chain().focus().toggleHeading({ level: 2 }).run()}
-      >
+      <TBtn label="Heading 2" active={state.h2} onClick={() => editor.chain().focus().toggleHeading({ level: 2 }).run()}>
         H2
       </TBtn>
-      <TBtn
-        label="Bullet list"
-        active={state.bullet}
-        onClick={() => editor.chain().focus().toggleBulletList().run()}
-      >
+      <TBtn label="Heading 3" active={state.h3} onClick={() => editor.chain().focus().toggleHeading({ level: 3 }).run()}>
+        H3
+      </TBtn>
+      <TBtn label="Bullet list" active={state.bullet} onClick={() => editor.chain().focus().toggleBulletList().run()}>
         •
       </TBtn>
+      <TBtn label="Numbered list" active={state.ordered} onClick={() => editor.chain().focus().toggleOrderedList().run()}>
+        1.
+      </TBtn>
       <Divider />
-      <TBtn
-        label="Align left"
-        active={state.left}
-        onClick={() => editor.chain().focus().setTextAlign('left').run()}
-      >
+
+      <TBtn label="Align left" active={state.left} onClick={() => editor.chain().focus().setTextAlign('left').run()}>
         ⇤
       </TBtn>
-      <TBtn
-        label="Align center"
-        active={state.center}
-        onClick={() => editor.chain().focus().setTextAlign('center').run()}
-      >
+      <TBtn label="Align center" active={state.center} onClick={() => editor.chain().focus().setTextAlign('center').run()}>
         ↔
       </TBtn>
-      <TBtn
-        label="Align right"
-        active={state.right}
-        onClick={() => editor.chain().focus().setTextAlign('right').run()}
-      >
+      <TBtn label="Align right" active={state.right} onClick={() => editor.chain().focus().setTextAlign('right').run()}>
         ⇥
       </TBtn>
       <Divider />
+
+      {/* Link */}
+      <Popover
+        open={menu === 'link'}
+        onClose={close}
+        width={236}
+        trigger={
+          <TBtn label="Link" active={state.link || menu === 'link'} onClick={openLink}>
+            🔗
+          </TBtn>
+        }
+      >
+        <div className="flex flex-col gap-2">
+          <input
+            autoFocus
+            value={linkUrl}
+            onChange={(e) => setLinkUrl(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') applyLink()
+              if (e.key === 'Escape') close()
+            }}
+            placeholder="https://…"
+            className="w-full px-2 py-1.5 text-sm focus:outline-none"
+            style={{
+              borderRadius: 'var(--radius-input)',
+              border: '1px solid var(--color-border)',
+              color: 'var(--color-plum)',
+            }}
+          />
+          <div className="flex items-center justify-between">
+            {state.link ? (
+              <button
+                type="button"
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => {
+                  editor.chain().focus().extendMarkRange('link').unsetLink().run()
+                  close()
+                }}
+                className="px-2 py-1 text-xs font-semibold"
+                style={{ color: 'var(--color-muted)' }}
+              >
+                Remove
+              </button>
+            ) : (
+              <span />
+            )}
+            <button
+              type="button"
+              onMouseDown={(e) => e.preventDefault()}
+              onClick={applyLink}
+              className="px-3 py-1 text-xs font-bold"
+              style={{
+                borderRadius: 'var(--radius-pill)',
+                background: 'var(--color-accent)',
+                color: '#fff',
+              }}
+            >
+              Apply
+            </button>
+          </div>
+        </div>
+      </Popover>
+
+      {/* Image */}
+      <input ref={fileInputRef} type="file" accept="image/*" hidden onChange={onPickImage} />
+      <TBtn label="Insert image" onClick={() => fileInputRef.current?.click()}>
+        🖼️
+      </TBtn>
+
+      {/* Table */}
+      <Popover
+        open={menu === 'table'}
+        onClose={close}
+        width={state.inTable ? 188 : 150}
+        trigger={
+          <TBtn label="Table" active={state.inTable || menu === 'table'} onClick={() => setMenu(menu === 'table' ? null : 'table')}>
+            ▦
+          </TBtn>
+        }
+      >
+        {state.inTable ? (
+          <div className="flex flex-col gap-0.5 text-sm" style={{ color: 'var(--color-plum)' }}>
+            <TableAction label="Add row below" onClick={() => editor.chain().focus().addRowAfter().run()} />
+            <TableAction label="Add column right" onClick={() => editor.chain().focus().addColumnAfter().run()} />
+            <TableAction label="Toggle header row" onClick={() => editor.chain().focus().toggleHeaderRow().run()} />
+            <TableAction label="Delete row" onClick={() => editor.chain().focus().deleteRow().run()} />
+            <TableAction label="Delete column" onClick={() => editor.chain().focus().deleteColumn().run()} />
+            <TableAction
+              label="Delete table"
+              danger
+              onClick={() => {
+                editor.chain().focus().deleteTable().run()
+                close()
+              }}
+            />
+          </div>
+        ) : (
+          <GridPicker
+            onPick={(rows, cols) => {
+              editor.chain().focus().insertTable({ rows, cols, withHeaderRow: true }).run()
+              close()
+            }}
+          />
+        )}
+      </Popover>
+
+      {/* Outline / document map */}
+      <Popover
+        open={menu === 'outline'}
+        onClose={close}
+        width={240}
+        trigger={
+          <TBtn label="Outline" active={menu === 'outline'} onClick={() => setMenu(menu === 'outline' ? null : 'outline')}>
+            ☰
+          </TBtn>
+        }
+      >
+        <div className="max-h-72 overflow-y-auto">
+          <p className="mb-1.5 px-1 text-xs font-bold" style={{ color: 'var(--color-muted)' }}>
+            大纲 · Outline
+          </p>
+          {headings.length === 0 ? (
+            <p className="px-1 py-2 text-xs leading-snug" style={{ color: 'var(--color-muted)' }}>
+              用 H1/H2/H3 添加标题，这里就会出现导航。<br />
+              Add headings to navigate them here.
+            </p>
+          ) : (
+            <div className="flex flex-col">
+              {headings.map((h, i) => (
+                <button
+                  key={i}
+                  type="button"
+                  onMouseDown={(e) => e.preventDefault()}
+                  onClick={() => gotoHeading(h.pos)}
+                  className="truncate rounded px-1.5 py-1 text-left text-sm hover:bg-[var(--color-surface-alt)]"
+                  style={{
+                    paddingLeft: `${(h.level - 1) * 12 + 6}px`,
+                    color: 'var(--color-plum)',
+                    fontWeight: h.level === 1 ? 700 : 500,
+                  }}
+                  title={h.text}
+                >
+                  {h.text}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      </Popover>
+      <Divider />
+
       <button
         type="button"
         aria-label="Check my voice"
@@ -162,3 +597,58 @@ export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
     </div>
   )
 }
+
+// A row in the in-table editing menu.
+function TableAction({ label, onClick, danger }: { label: string; onClick: () => void; danger?: boolean }) {
+  return (
+    <button
+      type="button"
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={onClick}
+      className="rounded px-2 py-1 text-left"
+      style={{ color: danger ? 'var(--color-accent-hover)' : 'var(--color-plum)' }}
+    >
+      {label}
+    </button>
+  )
+}
+
+// A hover-to-size grid for inserting a table. Hovering a cell highlights the
+// rectangle from the top-left; clicking inserts that many rows × columns.
+function GridPicker({ onPick }: { onPick: (rows: number, cols: number) => void }) {
+  const MAX = 6
+  const [hover, setHover] = useState<{ r: number; c: number }>({ r: 0, c: 0 })
+  return (
+    <div>
+      <div
+        className="grid gap-0.5"
+        style={{ gridTemplateColumns: `repeat(${MAX}, 1fr)` }}
+        onMouseLeave={() => setHover({ r: 0, c: 0 })}
+      >
+        {Array.from({ length: MAX * MAX }).map((_, i) => {
+          const r = Math.floor(i / MAX) + 1
+          const c = (i % MAX) + 1
+          const on = r <= hover.r && c <= hover.c
+          return (
+            <button
+              key={i}
+              type="button"
+              onMouseDown={(e) => e.preventDefault()}
+              onMouseEnter={() => setHover({ r, c })}
+              onClick={() => onPick(r, c)}
+              className="h-4 w-4"
+              style={{
+                borderRadius: 3,
+                background: on ? 'var(--color-accent)' : 'var(--color-surface-alt)',
+                border: '1px solid var(--color-border)',
+              }}
+            />
+          )
+        })}
+      </div>
+      <div className="mt-1.5 text-center text-xs" style={{ color: 'var(--color-muted)' }}>
+        {hover.r > 0 ? `${hover.r} × ${hover.c}` : 'Pick a size'}
+      </div>
+    </div>
+  )
+}

web/src/effects/PetalFall.tsx

@@ -0,0 +1,200 @@
+import { useEffect, useRef } from 'react'
+
+// PetalFall is the cozy ambient layer: a fixed, non-interactive 2D canvas that
+// drifts soft cherry-blossom petals down the page. Each petal is a real
+// petal-shaped sprite (notched sakura silhouette with a gentle gradient and
+// soft alpha), pre-rendered once per color and then blitted many times with
+// rotation + sway. It sits behind the chrome, ignores pointer events, pauses
+// when the tab is hidden, and renders nothing for prefers-reduced-motion.
+
+// Saturated-but-soft blossom colors. Each petal fades from a light, near-white
+// tip to its color at the base, so it reads as a real petal rather than a blob.
+const PALETTE: { r: number; g: number; b: number }[] = [
+  { r: 255, g: 150, b: 190 }, // rose pink
+  { r: 255, g: 184, b: 205 }, // pale blossom
+  { r: 255, g: 158, b: 130 }, // warm peach
+  { r: 209, g: 160, b: 255 }, // lavender
+  { r: 255, g: 122, b: 172 }, // deep rose
+]
+
+const SPRITE_PX = 160 // off-screen render resolution per petal sprite
+
+function rgba(c: { r: number; g: number; b: number }, a: number): string {
+  return `rgba(${Math.round(c.r)}, ${Math.round(c.g)}, ${Math.round(c.b)}, ${a})`
+}
+function mixWhite(c: { r: number; g: number; b: number }, t: number) {
+  return { r: c.r + (255 - c.r) * t, g: c.g + (255 - c.g) * t, b: c.b + (255 - c.b) * t }
+}
+function scale(c: { r: number; g: number; b: number }, t: number) {
+  return { r: c.r * t, g: c.g * t, b: c.b * t }
+}
+
+// Draw one petal sprite: a notched sakura silhouette filled with a tip→base
+// gradient and a faint central highlight, on a transparent canvas.
+function makeSprite(color: { r: number; g: number; b: number }): HTMLCanvasElement {
+  const s = SPRITE_PX
+  const cv = document.createElement('canvas')
+  cv.width = s
+  cv.height = s
+  const g = cv.getContext('2d')!
+  g.translate(s / 2, s / 2)
+
+  const hw = s * 0.3 // half width
+  const hh = s * 0.44 // half height
+
+  g.beginPath()
+  g.moveTo(0, hh) // pointed base
+  g.bezierCurveTo(hw, hh * 0.42, hw * 0.92, -hh * 0.52, hw * 0.2, -hh * 0.92) // right side → near tip
+  g.quadraticCurveTo(0, -hh * 0.72, -hw * 0.2, -hh * 0.92) // the sakura notch
+  g.bezierCurveTo(-hw * 0.92, -hh * 0.52, -hw, hh * 0.42, 0, hh) // left side → base
+  g.closePath()
+
+  const grad = g.createLinearGradient(0, -hh, 0, hh)
+  grad.addColorStop(0, rgba(mixWhite(color, 0.55), 0.78)) // light, soft tip
+  grad.addColorStop(0.45, rgba(color, 0.88))
+  grad.addColorStop(1, rgba(scale(color, 0.8), 0.95)) // deeper base
+  g.fillStyle = grad
+  g.fill()
+
+  // A soft white sheen down the centre for a delicate, glossy feel.
+  const sheen = g.createLinearGradient(-hw * 0.3, 0, hw * 0.3, 0)
+  sheen.addColorStop(0, 'rgba(255,255,255,0)')
+  sheen.addColorStop(0.5, 'rgba(255,255,255,0.28)')
+  sheen.addColorStop(1, 'rgba(255,255,255,0)')
+  g.fillStyle = sheen
+  g.fill()
+
+  return cv
+}
+
+interface Petal {
+  baseX: number
+  y: number
+  size: number
+  vy: number // fall speed (px/s)
+  angle: number
+  spin: number // rad/s
+  swayAmp: number
+  swayFreq: number
+  swayPhase: number
+  alpha: number
+  sprite: number
+}
+
+export function PetalFall() {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+
+  useEffect(() => {
+    const reduce =
+      typeof window !== 'undefined' &&
+      window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+    if (reduce) return // respect users who don't want ambient motion
+
+    const el = canvasRef.current
+    if (!el) return
+    const c2d = el.getContext('2d')
+    if (!c2d) return
+    // Non-null aliases so the render closures keep the narrowed types.
+    const canvas = el
+    const ctx = c2d
+
+    const sprites = PALETTE.map(makeSprite)
+    const dpr = Math.min(window.devicePixelRatio || 1, 2)
+    let W = window.innerWidth
+    let H = window.innerHeight
+
+    // Scale petal count to the viewport so it stays sparse and gentle.
+    const count = Math.round(Math.min(46, Math.max(16, (W * H) / 46000)))
+    const rnd = (a: number, b: number) => a + Math.random() * (b - a)
+
+    const spawn = (initial: boolean): Petal => ({
+      baseX: rnd(0, W),
+      y: initial ? rnd(-H, H) : rnd(-60, -20),
+      size: rnd(16, 38),
+      vy: rnd(22, 52),
+      angle: rnd(0, Math.PI * 2),
+      spin: rnd(-0.9, 0.9),
+      swayAmp: rnd(14, 42),
+      swayFreq: rnd(0.3, 0.85),
+      swayPhase: rnd(0, Math.PI * 2),
+      alpha: rnd(0.5, 0.82),
+      sprite: Math.floor(Math.random() * sprites.length),
+    })
+
+    let petals = Array.from({ length: count }, () => spawn(true))
+
+    function resize() {
+      W = window.innerWidth
+      H = window.innerHeight
+      canvas.width = Math.floor(W * dpr)
+      canvas.height = Math.floor(H * dpr)
+      canvas.style.width = `${W}px`
+      canvas.style.height = `${H}px`
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    }
+    resize()
+    window.addEventListener('resize', resize)
+
+    let raf = 0
+    let running = true
+    let last = performance.now()
+
+    function frame(now: number) {
+      if (!running) return
+      const dt = Math.min(0.05, (now - last) / 1000) // clamp big gaps (tab wake)
+      last = now
+      const t = now / 1000
+      ctx.clearRect(0, 0, W, H)
+
+      for (const p of petals) {
+        p.y += p.vy * dt
+        p.angle += p.spin * dt
+        const x = p.baseX + p.swayAmp * Math.sin(t * p.swayFreq + p.swayPhase)
+
+        // Recycle once fully past the bottom.
+        if (p.y - p.size > H) {
+          Object.assign(p, spawn(false))
+          continue
+        }
+
+        ctx.save()
+        ctx.translate(x, p.y)
+        ctx.rotate(p.angle)
+        ctx.globalAlpha = p.alpha
+        ctx.drawImage(sprites[p.sprite], -p.size / 2, -p.size / 2, p.size, p.size)
+        ctx.restore()
+      }
+      raf = requestAnimationFrame(frame)
+    }
+
+    const onVisibility = () => {
+      if (document.hidden) {
+        running = false
+        cancelAnimationFrame(raf)
+      } else if (!running) {
+        running = true
+        last = performance.now()
+        raf = requestAnimationFrame(frame)
+      }
+    }
+    document.addEventListener('visibilitychange', onVisibility)
+    raf = requestAnimationFrame(frame)
+
+    return () => {
+      running = false
+      cancelAnimationFrame(raf)
+      window.removeEventListener('resize', resize)
+      document.removeEventListener('visibilitychange', onVisibility)
+      petals = []
+    }
+  }, [])
+
+  return (
+    <canvas
+      ref={canvasRef}
+      aria-hidden
+      className="petal-fall pointer-events-none fixed inset-0"
+      style={{ zIndex: 20 }}
+    />
+  )
+}

web/src/hooks/useCheckpoint.ts

@@ -13,28 +13,56 @@ export function useCheckpoint(docId: string | null) {
   const [checking, setChecking] = useState(false)
   // True while a whole-document voice pass is in flight (explicit user action).
   const [voicing, setVoicing] = useState(false)
+  // True when the last LLM pass couldn't reach the model (server 502 or network
+  // error). Drives a gentle, reassuring "helper is resting" note — the writing
+  // itself still saves fine, so this is awareness, not an error. Cleared on the
+  // next success or doc switch.
+  const [llmDown, setLlmDown] = useState(false)
 
   const debounceRef = useRef<ReturnType<typeof setTimeout>>(undefined)
+  // Pending auto-retry timer for a failed checkpoint (see runCheck).
+  const retryRef = useRef<ReturnType<typeof setTimeout>>(undefined)
   const docIdRef = useRef(docId)
   docIdRef.current = docId
 
   // Token to discard responses from a doc we've since navigated away from.
   const runRef = useRef(0)
 
-  const runCheck = useCallback(async () => {
+  // Backoff schedule for re-running a checkpoint that failed. A paste fires
+  // exactly ONE checkpoint, and nothing re-fires until the next keystroke — so a
+  // single transient failure (a momentary stall on the shared inference box)
+  // would otherwise strand the user on "resting" indefinitely after a paste.
+  // These delays clear the server's 30s per-doc floor by the later attempts, and
+  // a failed pass now releases its slot server-side so a retry can truly re-run.
+  const RETRY_DELAYS_MS = [3000, 12000, 35000]
+
+  const runCheck = useCallback(async (attempt = 0) => {
     const id = docIdRef.current
     if (!id) return
+    clearTimeout(retryRef.current)
     const run = ++runRef.current
     setChecking(true)
+    let retrying = false
     try {
       const fresh = await api.checkDoc(id)
       if (run === runRef.current && id === docIdRef.current) {
         setSuggestions(fresh)
+        setLlmDown(false)
       }
     } catch (err) {
       console.error('checkpoint failed', err)
+      if (run !== runRef.current) return
+      if (attempt < RETRY_DELAYS_MS.length) {
+        // Keep trying quietly — don't flag "resting" until retries are exhausted.
+        retrying = true
+        retryRef.current = setTimeout(() => void runCheck(attempt + 1), RETRY_DELAYS_MS[attempt])
+      } else {
+        setLlmDown(true)
+      }
     } finally {
-      if (run === runRef.current) setChecking(false)
+      // Stay in the "checking" state while a retry is queued so the breathing dot
+      // keeps reassuring rather than flickering off between attempts.
+      if (run === runRef.current && !retrying) setChecking(false)
     }
   }, [])
 
@@ -44,15 +72,18 @@ export function useCheckpoint(docId: string | null) {
   const runVoice = useCallback(async () => {
     const id = docIdRef.current
     if (!id) return
+    clearTimeout(retryRef.current) // a voice pass supersedes a queued grammar retry
     const run = ++runRef.current
     setVoicing(true)
     try {
       const full = await api.voiceDoc(id)
       if (run === runRef.current && id === docIdRef.current) {
         setSuggestions(full)
+        setLlmDown(false)
       }
     } catch (err) {
       console.error('voice pass failed', err)
+      if (run === runRef.current) setLlmDown(true)
     } finally {
       if (run === runRef.current) setVoicing(false)
     }
@@ -61,17 +92,20 @@ export function useCheckpoint(docId: string | null) {
   // Call on every edit; schedules a check 4s after typing settles.
   const schedule = useCallback(() => {
     clearTimeout(debounceRef.current)
-    debounceRef.current = setTimeout(runCheck, DEBOUNCE_MS)
+    clearTimeout(retryRef.current) // a fresh edit supersedes any queued retry
+    debounceRef.current = setTimeout(() => void runCheck(), DEBOUNCE_MS)
   }, [runCheck])
 
   // Load existing pending suggestions whenever the document changes, and cancel
   // any in-flight debounce from the previous doc.
   useEffect(() => {
     clearTimeout(debounceRef.current)
+    clearTimeout(retryRef.current)
     runRef.current++
     setSuggestions([])
     setChecking(false)
     setVoicing(false)
+    setLlmDown(false)
     if (!docId) return
     let cancelled = false
     void (async () => {
@@ -87,12 +121,18 @@ export function useCheckpoint(docId: string | null) {
     }
   }, [docId])
 
-  useEffect(() => () => clearTimeout(debounceRef.current), [])
+  useEffect(
+    () => () => {
+      clearTimeout(debounceRef.current)
+      clearTimeout(retryRef.current)
+    },
+    [],
+  )
 
   // Drop one suggestion locally (after accept/dismiss) without a refetch.
   const removeSuggestion = useCallback((id: string) => {
     setSuggestions((prev) => prev.filter((s) => s.id !== id))
   }, [])
 
-  return { suggestions, checking, voicing, schedule, runVoice, removeSuggestion }
+  return { suggestions, checking, voicing, llmDown, schedule, runVoice, removeSuggestion }
 }

web/src/hooks/useTags.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useState } from 'react'
+import { api, type Tag, type TagColor } from '../api/client'
+
+// useTags owns the user's tag roster (the full set the writer has created, with
+// per-tag document counts). Document↔tag assignments live in App alongside the
+// document list; this hook is just the roster plus create/recolor/delete and a
+// refresh used to keep counts current after an assignment changes.
+export function useTags() {
+  const [tags, setTags] = useState<Tag[]>([])
+
+  const refresh = useCallback(async () => {
+    try {
+      setTags(await api.listTags())
+    } catch (err) {
+      console.error('failed to load tags', err)
+    }
+  }, [])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  // Create (or reuse) a tag, returning it. The roster is refreshed so the new
+  // tag appears with a zero count.
+  const createTag = useCallback(
+    async (name: string, color: TagColor): Promise<Tag | null> => {
+      try {
+        const tag = await api.createTag(name, color)
+        await refresh()
+        return tag
+      } catch (err) {
+        console.error('failed to create tag', err)
+        return null
+      }
+    },
+    [refresh],
+  )
+
+  const recolorTag = useCallback(
+    async (id: string, color: TagColor) => {
+      // Optimistic recolor; refresh reconciles.
+      setTags((prev) => prev.map((t) => (t.id === id ? { ...t, color } : t)))
+      try {
+        await api.updateTag(id, { color })
+      } catch (err) {
+        console.error('failed to recolor tag', err)
+        void refresh()
+      }
+    },
+    [refresh],
+  )
+
+  const deleteTag = useCallback(async (id: string) => {
+    setTags((prev) => prev.filter((t) => t.id !== id))
+    try {
+      await api.deleteTag(id)
+    } catch (err) {
+      console.error('failed to delete tag', err)
+    }
+  }, [])
+
+  return { tags, refresh, createTag, recolorTag, deleteTag }
+}

web/src/index.css

@@ -98,6 +98,93 @@ button, a, input {
   padding: 0.1em 0.35em;
   border-radius: 6px;
 }
+/* Top formatting bar: a single line at rest so it stays slim, expanding to
+   reveal every control on hover (or while a control inside it has focus, e.g.
+   the link input or an open popover). The clipped right edge fades out as a hint
+   that more is available. */
+.petal-toolbar {
+  flex-wrap: nowrap;
+  overflow: hidden;
+  max-width: 100%;
+  -webkit-mask-image: linear-gradient(to right, #000 90%, transparent 100%);
+  mask-image: linear-gradient(to right, #000 90%, transparent 100%);
+}
+.petal-toolbar:hover,
+.petal-toolbar:focus-within {
+  flex-wrap: wrap;
+  overflow: visible;
+  -webkit-mask-image: none;
+  mask-image: none;
+}
+
+/* Highlighter mark — inline background swatch behind the text. */
+.petal-prose mark {
+  border-radius: 4px;
+  padding: 0.05em 0.15em;
+  /* color comes from the inline style the Highlight extension writes */
+}
+/* Inserted images: rounded, soft-shadowed, never wider than the column. The
+   selected-node ring matches the rest of the rose theme. Scoped to the editor's
+   own <img> (not a class) since Tiptap doesn't always carry the configured
+   class through to the rendered node. */
+.petal-prose img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-soft);
+}
+.petal-prose img.ProseMirror-selectednode {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+/* Tables: soft pink grid, rounded outer corners, a tinted header row. Targeted
+   by element within the editor — Tiptap renders the <table> without our
+   configured class, so a `.petal-table` selector would never match. The wrapper
+   Tiptap adds (.tableWrapper) handles horizontal overflow scroll. */
+.petal-prose .tableWrapper {
+  overflow-x: auto;
+}
+.petal-prose table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.4em 0;
+  overflow: hidden;
+  border-radius: var(--radius-input);
+  border: 1px solid var(--color-border);
+  table-layout: fixed;
+}
+.petal-prose td,
+.petal-prose th {
+  border: 1px solid var(--color-border);
+  padding: 0.4em 0.6em;
+  vertical-align: top;
+  position: relative;
+  min-width: 3em;
+}
+.petal-prose th {
+  background: var(--color-surface-alt);
+  font-weight: 700;
+  text-align: left;
+}
+/* The cell being edited / the active selection inside a table. */
+.petal-prose .selectedCell::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: var(--color-surface-alt);
+  opacity: 0.5;
+  pointer-events: none;
+}
+/* The column-resize handle Tiptap draws between columns. */
+.petal-prose .column-resize-handle {
+  position: absolute;
+  right: -2px;
+  top: 0;
+  bottom: -2px;
+  width: 4px;
+  background: var(--color-accent);
+  pointer-events: none;
+}
 /* Placeholder shown on the empty first paragraph (Tiptap Placeholder ext). */
 .petal-prose p.is-editor-empty:first-child::before {
   content: attr(data-placeholder);
@@ -136,6 +223,81 @@ button, a, input {
   animation: petal-suggestion-in 200ms ease both;
 }
 
+/* Text emphasized from its margin card (or a hover) — a soft wash so the
+   card↔text link reads at a glance, both directions. */
+.petal-suggestion-active {
+  background: var(--color-surface-alt);
+  box-shadow: 0 0 0 3px var(--color-surface-alt);
+  border-radius: 3px;
+}
+
+/* --- Suggestion margin rail -------------------------------------------------
+   The right-hand "comment column": every outstanding suggestion as a card,
+   vertically aligned to the text it flags, so the whole queue is visible at a
+   glance instead of one-highlight-at-a-time on hover. It floats in the whitespace
+   just right of the editor column and is only mounted when there's room for it
+   (EditorCore measures the gap). Cards are absolutely positioned by a resolved
+   top (anchor + collision avoidance), so the container only anchors the column. */
+.petal-rail {
+  position: absolute;
+  top: 0;
+  left: 100%;
+  margin-left: 32px;
+  width: 300px;
+  /* Below the companion mascot (z-40): where a stacked card reaches the
+     bottom-right corner it simply tucks behind the sleeping cat. */
+  z-index: 10;
+}
+.petal-rail-card {
+  position: absolute;
+  left: 0;
+  right: 0;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-left: 3px solid var(--color-border); /* type color set inline */
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-soft);
+  padding: 0.7rem 0.85rem;
+  /* `top` eases so re-stacking (accept/dismiss/edit) glides instead of jumping.
+     The entrance uses fill `backwards` so its translateY doesn't linger and fight
+     the active-state transform once it's done. */
+  transition: top 240ms cubic-bezier(0.2, 0.7, 0.3, 1), box-shadow 200ms ease,
+    transform 200ms ease, border-color 200ms ease;
+  animation: petal-suggestion-in 220ms ease backwards;
+}
+.petal-rail-card-active {
+  transform: translateX(-5px);
+  box-shadow: 0 8px 26px rgba(180, 130, 160, 0.24);
+  border-top-color: var(--color-accent);
+  border-right-color: var(--color-accent);
+  border-bottom-color: var(--color-accent);
+}
+.petal-rail-x {
+  color: var(--color-muted);
+  font-size: 0.72rem;
+  line-height: 1;
+  padding: 2px 5px;
+  border-radius: var(--radius-pill);
+}
+.petal-rail-x:hover {
+  background: var(--color-surface-alt);
+  color: var(--color-plum);
+}
+
+/* --- Find & Replace ---------------------------------------------------------
+   In-document search (Ctrl/Cmd+F). Every match gets a soft honey wash; the
+   current match is brighter with a rose ring so it stands out as you step
+   through. Decorations, like every other highlight layer here. */
+.petal-find-match {
+  background: var(--color-highlight, #fff1a8);
+  border-radius: 3px;
+  box-shadow: 0 0 0 1px var(--color-border);
+}
+.petal-find-match-active {
+  background: var(--color-peach);
+  box-shadow: 0 0 0 2px var(--color-accent);
+}
+
 /* --- Spell check ------------------------------------------------------------
    Browser-side nspell flags misspellings with a soft rose wavy underline (a
    gentler take on the classic red squiggle, to fit the pastel palette). Like the
@@ -163,6 +325,18 @@ button, a, input {
   animation: petal-suggestion-in 200ms ease both;
 }
 
+/* --- ESL superpowers (Phase 9) ----------------------------------------------
+   Inline Chinese gloss on hover (a small dark tooltip under the word), and the
+   selection rewrite bubble + its preview card. All share the soft pop-in. The
+   gloss tip fades in a touch faster — it's a fleeting reading aid, not a panel. */
+.petal-gloss-tip {
+  animation: petal-suggestion-in 140ms ease both;
+}
+.petal-selection-bubble,
+.petal-rewrite-card {
+  animation: petal-suggestion-in 200ms ease both;
+}
+
 /* --- Accept confetti --------------------------------------------------------
    A tiny CSS-only burst played where a suggestion is accepted: four colored
    dots spray up-and-out, then fade. No JS animation — each dot reads its
@@ -206,9 +380,17 @@ button, a, input {
    The cozy corner mascot. Gently bobs while awake, settles and sways slowly
    while napping; its speech bubble pops in; little zzz drift up when asleep. */
 .petal-companion {
+  /* Mascot size scales with the viewport width: ~original on a laptop, up to
+     ~2× on a large desktop. Tune the middle (vw) term to taste. */
+  --petal-companion-size: clamp(10rem, 17vw, 20rem);
   animation: petal-bob 3.2s ease-in-out infinite;
   transition: transform 200ms ease;
 }
+/* The Lottie art sits inside the round badge with a little breathing room. */
+.petal-companion-art {
+  width: 88%;
+  height: 88%;
+}
 .petal-companion:hover {
   transform: translateY(-2px) scale(1.04);
 }
@@ -234,10 +416,10 @@ button, a, input {
 }
 
 .petal-zzz {
-  top: 6px;
-  right: 14px;
+  top: calc(var(--petal-companion-size) * 0.04);
+  right: calc(var(--petal-companion-size) * 0.1);
   font-weight: 800;
-  font-size: 1.1rem;
+  font-size: calc(var(--petal-companion-size) * 0.12);
   animation: petal-zzz 2.4s ease-in-out infinite;
 }
 @keyframes petal-zzz {
@@ -269,3 +451,155 @@ button, a, input {
   0%, 100% { opacity: 0.4; }
   50%      { opacity: 1; }
 }
+
+/* --- Organization & search (Phase 10) --------------------------------------
+   Tag chips, the search results list, and per-row affordances. The row actions
+   (tag / delete) fade in on hover for pointer users but are always visible on
+   touch (no hover) — see the coarse-pointer block below. */
+.petal-tag-chip {
+  transition: background 160ms ease, color 160ms ease, transform 160ms ease;
+}
+.petal-search-results {
+  animation: petal-suggestion-in 160ms ease both;
+}
+.petal-tag-picker {
+  animation: petal-suggestion-in 160ms ease both;
+}
+.petal-row-action {
+  opacity: 0;
+  transition: opacity 160ms ease, background 160ms ease;
+}
+.group:hover .petal-row-action,
+.petal-row-action:focus-visible {
+  opacity: 1;
+}
+.petal-row-action:hover {
+  background: var(--color-surface-alt);
+}
+/* Clamp a search snippet to two lines. */
+.line-clamp-2 {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* --- Touch & tablet polish --------------------------------------------------
+   On coarse pointers (tablets, phones) there's no hover, so make tap targets
+   comfortable and reveal affordances that would otherwise be hover-only. */
+@media (pointer: coarse) {
+  .petal-tap {
+    min-height: 44px;
+  }
+  .petal-tap-sm {
+    min-height: 36px;
+  }
+  /* Row actions can't rely on hover — keep them visible and roomy. */
+  .petal-row-action {
+    opacity: 1;
+    height: 36px;
+    width: 36px;
+  }
+  /* Bigger, easier-to-hit suggestion/word/tag pills. */
+  .petal-tag-chip {
+    padding-top: 0.25rem;
+    padding-bottom: 0.25rem;
+  }
+}
+
+/* --- Responsive sidebar (narrow screens) ------------------------------------
+   Below the tablet breakpoint the sidebar becomes an overlay drawer toggled by a
+   hamburger in the header, instead of a permanent column. A scrim sits behind it.
+   On wide screens the toggle + scrim are hidden and the sidebar is in-flow. */
+.petal-sidebar-toggle {
+  display: none;
+}
+.petal-scrim {
+  display: none;
+}
+@media (max-width: 768px) {
+  .petal-sidebar-toggle {
+    display: inline-flex;
+  }
+  .petal-sidebar {
+    position: fixed;
+    top: 48px; /* below the 12-height header */
+    bottom: 0;
+    left: 0;
+    z-index: 30;
+    background: var(--color-bg);
+    box-shadow: var(--shadow-soft);
+  }
+  /* On mobile the sidebar is hidden by default; the drawer-open class slides it
+     in. (Distraction-free's petal-sidebar-hidden still wins to keep it closed.) */
+  .petal-sidebar:not(.petal-drawer-open) {
+    width: 0;
+    transform: translateX(-24px);
+    opacity: 0;
+    pointer-events: none;
+  }
+  .petal-scrim.petal-scrim-show {
+    display: block;
+    position: fixed;
+    inset: 48px 0 0 0;
+    z-index: 20;
+    background: rgba(61, 46, 57, 0.18);
+  }
+}
+
+/* Print / Save-as-PDF: strip every bit of app chrome and editing decoration so
+   only the title and the writing itself reach the page. This is Petal's PDF
+   path — it uses the browser's own fonts, so CJK renders correctly with no
+   server-side font embedding. */
+/* --- Ambient falling petals -------------------------------------------------
+   The WebGL petal layer is a fixed, non-interactive overlay that drifts soft
+   blossoms over the page. Kept gentle (low opacity) so it never competes with
+   the writing. It hides itself in print and is skipped entirely for users who
+   prefer reduced motion (the component renders nothing in that case). */
+.petal-fall {
+  opacity: 1;
+}
+
+/* Honor reduced-motion globally: still the looping ambient animations and drop
+   the petal layer. One-shot entrance/feedback animations are left intact. */
+@media (prefers-reduced-motion: reduce) {
+  .petal-fall {
+    display: none !important;
+  }
+  .petal-bob,
+  .petal-bob-slow,
+  .petal-zzz,
+  .petal-checkpoint-dot {
+    animation: none !important;
+  }
+}
+
+@media print {
+  .petal-fall,
+  .petal-no-print,
+  .petal-sidebar,
+  .petal-suggestion-card,
+  .petal-misspell-card,
+  .petal-gloss-tip,
+  .petal-selection-bubble,
+  .petal-rewrite-card,
+  .petal-confetti,
+  .petal-companion {
+    display: none !important;
+  }
+  html, body, #root {
+    height: auto !important;
+    overflow: visible !important;
+    background: #fff !important;
+  }
+  /* Drop the in-editor highlight underlines/tints — they're guidance, not ink. */
+  .petal-suggestion,
+  .petal-misspelling {
+    background: none !important;
+    text-decoration: none !important;
+    border-bottom: none !important;
+  }
+  /* Let the writing use the full page width. */
+  .max-w-\[720px\] { max-width: none !important; }
+}

web/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />