From 8aa437ec8288951d9a14637929e5407aca6a2b8a Mon Sep 17 00:00:00 2001 From: prosolis <5590409+prosolis@users.noreply.github.com> Date: Fri, 26 Jun 2026 15:50:25 -0700 Subject: [PATCH 1/3] Phase 12 + 13: collocation coach + vocabulary garden MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 12 — collocation coach: a third suggestion family for gentle "natives usually say…" hints on non-native word pairings, reusing the existing runPass/pendingScope/rail machinery. - llm/collocation.go (RunCollocation, 25s floor, reuses ParseCheckpoint) + collocationSystemPrompt/CollocationMessages (warm, Mandarin gloss, defers grammar/spelling to the grammar family) - migration 0005 rebuilds the suggestions table to extend the type CHECK (SQLite can't ALTER a CHECK) - collocationScope + CollocationLimit + POST /{id}/collocation - fix: grammarScope was `type != 'voice'` and would wipe the new collocation flags; now `type NOT IN ('voice','collocation')` - frontend: --color-blossom, "Make it sound natural 🌸" pill, collocating/runCollocation in useCheckpoint, StatusBar dot Phase 13 — vocabulary garden: capture looked-up words and surface them for gentle spaced repetition. - new internal/vocab package: migration 0006 (vocab_words, SM-2-lite columns, doc_id ON DELETE SET NULL, UNIQUE(user_id,word)), scheduler.go (Leitner ladder 1/3/7/16/35 then geometric; gentle "again", no streak-shaming), handlers (capture-upsert/list/due/ review/delete, owner-scoped, SQLite-side datetime math) - auto-capture on word lookup (dictionary-known words only, captures the surrounding sentence + doc_id) + 🤍/💚 toggle on WordCard - GardenPanel: blossom grid (bloom by reps), flashcard review (sentence blanked, flip, again/good/easy, recognition↔production), sleepy-kitten footer; opened from a global 🌷 header button Tests: TestCollocationPassCoexists, vocab scheduler + handlers, db CHECK extended. go build/vet/test + tsc + vite + vitest (51/51) clean; migration verified against a copy of the live DB; live backend smoke walked the full vocab lifecycle + the warm-502 collocation path. Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd --- BUILD_PLAN.md | 33 +- cmd/server/main.go | 5 + internal/db/db.go | 65 +++ internal/db/db_test.go | 8 + internal/db/models.go | 13 +- internal/llm/collocation.go | 35 ++ internal/llm/prompts.go | 48 ++ internal/suggestions/handlers.go | 39 +- internal/suggestions/handlers_test.go | 59 +++ internal/vocab/handlers.go | 245 ++++++++++ internal/vocab/handlers_test.go | 170 +++++++ internal/vocab/scheduler.go | 97 ++++ internal/vocab/scheduler_test.go | 66 +++ web/src/App.tsx | 34 ++ web/src/api/client.ts | 45 +- web/src/components/Editor/EditorCore.tsx | 95 +++- web/src/components/Editor/WordCard.tsx | 47 +- web/src/components/Editor/suggestionMeta.ts | 1 + web/src/components/Garden/GardenPanel.tsx | 492 ++++++++++++++++++++ web/src/components/StatusBar/StatusBar.tsx | 18 +- web/src/components/Toolbar/Toolbar.tsx | 27 +- web/src/hooks/useCheckpoint.ts | 28 +- web/src/index.css | 2 + 23 files changed, 1614 insertions(+), 58 deletions(-) create mode 100644 internal/llm/collocation.go create mode 100644 internal/vocab/handlers.go create mode 100644 internal/vocab/handlers_test.go create mode 100644 internal/vocab/scheduler.go create mode 100644 internal/vocab/scheduler_test.go create mode 100644 web/src/components/Garden/GardenPanel.tsx diff --git a/BUILD_PLAN.md b/BUILD_PLAN.md index 24af513..3c27394 100644 --- a/BUILD_PLAN.md +++ b/BUILD_PLAN.md @@ -105,25 +105,25 @@ Multi-session build. **Source of truth for what's done and what's next.** Update - [x] **English phonetic (pivot from pinyin)** — for a native-Mandarin English learner the useful pronunciation aid is the English IPA, not pinyin (she reads Chinese fluently). `scripts/build_phonetic.py` extracts ECDICT's `phonetic` column (same source/freq-gate as the gloss); `phonetic.json.gz` embedded + lazily loaded; `Result.Phonetic` resolved via the same de-inflecting candidate walk; shown as `/ˈrɪvər/` in the WordCard. **Full dataset built from ECDICT: 46,579 words (361KB gz)**, in line with the other lexicon assets. The script also has a `--seed` mode (71 curated common words) that ships as a fallback / works without the csv. Curated seed entries (clean IPA) override the ECDICT form where both exist. - Verified: go build/vet/test (incl. new `TestExportAll`), tsc, vite build all clean; live smoke vs throwaway binaries — `/word/river|running|serendipity|rivers` all return phonetic (`rivers`→`river` de-inflected), export-all returns a valid 2-entry zip with de-duped CJK filenames + dated name, route doesn't collide with `/{id}`. -### Phase 12 — Collocation coach 🔜 (planned 2026-06-26) +### Phase 12 — Collocation coach ✅ (2026-06-26) **Why:** ESL writers nail grammar but miss *which words go together* — "do a decision" → "make a decision", "strong rain" → "heavy rain". These aren't *wrong*, so the grammar pass won't flag them; they're just non-native. Gentle "natives usually say…" hints are the single highest-leverage upgrade for making her writing sound native. **Build this first** — it's small and de-risks the migration-rebuild pattern Phase 13 also needs. **Key insight:** the suggestion pipeline is already generic over a `pass` + a `pendingScope` "family" (`runPass` in `internal/suggestions/handlers.go`; grammar + voice already prove it). Collocation drops in as a **third family** and reuses the entire accept/dismiss/re-anchoring/rail/Mandarin-explanation machinery — no new frontend rendering layer. -- [ ] `internal/llm/collocation.go` — `CollocationInterval` (~25s) + `RunCollocation(...)`, reusing the existing `ParseCheckpoint` parser (same as `RunVoice`). No new parsing. -- [ ] `internal/llm/prompts.go` — `CollocationMessages(contentText, tone)`. **This prompt is the whole feature**: flag only non-wrong-but-non-native word pairings; explicitly defer real grammar errors to the grammar family; phrase every explanation as warm "natives usually say…" with a Mandarin gloss — never "error/wrong". -- [ ] `internal/db/models.go` + migration `0005` — new suggestion type `collocation`. ⚠️ The `type` column has a `CHECK(...)` and **SQLite can't `ALTER` a CHECK** → migration must **rebuild** the `suggestions` table (create new w/ extended CHECK, copy rows, drop, rename, recreate `idx_suggestions_doc_id`). Not a one-line ALTER. -- [ ] `internal/suggestions/handlers.go` — add `collocationScope` (`deleteWhere: "type = 'collocation'"`, `forceType: collocation`), a `CollocationLimit` on `Handler` (+ wire in `New`), register `POST /{id}/collocation`. Mirrors `voice`, ~15 lines. Also extend `normalizeType` to accept the new type. -- [ ] Frontend: `suggestionMeta.ts` collocation entry (💡 icon + its own warm color so cards read as friendly tips); `client.ts` `collocation(docId)`; a gentle trigger like the existing "Check my voice" pill — **"Make it sound natural 🌸"** — rendering straight into `SuggestionRail`/`SuggestionCard`. -- [ ] Verify via the millenia UI-test harness (real-browser editor check) + go/tsc/vite clean. **Est. ~½ day** (mostly the new prompt + the table-rebuild migration). +- [x] `internal/llm/collocation.go` — `CollocationInterval` (25s) + `RunCollocation(...)`, reusing the existing `ParseCheckpoint` parser (same as `RunVoice`). Whole-document (no `TruncateDoc`), tone passed through. +- [x] `internal/llm/prompts.go` — `CollocationMessages(contentText, tone)` + `collocationSystemPrompt`. The prompt flags only non-wrong-but-non-native word pairings ("do a decision" → "make a decision"), explicitly defers grammar/spelling to the grammar family, and frames every explanation as warm "Natives usually say…" with a Mandarin gloss — never "error/wrong/mistake". +- [x] `internal/db/models.go` (`SuggestionTypeCollocation`) + migration `0005_collocation_suggestion_type` — **rebuilds** the `suggestions` table (new table w/ extended CHECK, copy rows, drop, rename, recreate `idx_suggestions_doc_id`), since SQLite can't `ALTER` a CHECK. Verified against a copy of the live DB (5 migrations apply cleanly, collocation insert accepted, rows preserved). +- [x] `internal/suggestions/handlers.go` — `collocationScope` (`deleteWhere: "type = 'collocation'"`, `forceType: collocation`), `CollocationLimit` on `Handler` (+ wired in `New`), `POST /{id}/collocation`, `normalizeType` extended. **Also fixed `grammarScope`** from `type != 'voice'` → `type NOT IN ('voice','collocation')` so a grammar checkpoint no longer wipes the collocation pending flags (the third family must survive like voice does). +- [x] Frontend: `suggestionMeta.ts` collocation entry (`--color-blossom` warm pink, "Word pairing" label); `client.ts` `collocationDoc(docId)` + `SuggestionType` extended; `index.css` token + `.petal-suggestion-collocation` decoration; `useCheckpoint` `collocating`/`runCollocation` (mirrors `runVoice`, shares the run-token guard); `Toolbar` blossom **"Make it sound natural 🌸"** pill (→ "Reading…"); `StatusBar` breathing blossom dot "Finding natural phrasing…"; threaded through `EditorCore`/`App`. Renders straight into the existing `SuggestionRail`/`SuggestionCard` (Accept applies the native pairing). +- [x] Verified: go build/vet/test (`TestCollocationPassCoexists` — three families coexist, grammar checkpoint doesn't wipe voice/collocation), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (dead LLM) → collocation route returns the warm 502 like check/voice. -### Phase 13 — Vocabulary garden (spaced repetition) 🔜 (planned 2026-06-26) +### Phase 13 — Vocabulary garden (spaced repetition) ✅ (2026-06-26) **Why:** the lexicon (`internal/lexicon`) is a stateless static-dataset lookup — **nothing records which words she's looked up.** Capturing them turns passive lookups into real vocabulary, and the review surface ties straight into the "petal garden" delight idea (words become blossoms; the sleeping kitten naps among them). Build **after** Phase 12. -- [ ] New `internal/vocab` package + migration `0005`/`0006` — `vocab_words` table: `word, gloss, phonetic, example` (sentence captured at lookup for context), `doc_id`, + SM-2-lite scheduling: `due_at, interval_days, ease, reps, lapses, last_reviewed`; `UNIQUE(user_id, word)`. -- [ ] Auto-capture: when `WordCard` calls `lookupWord`, also fire `POST /api/vocab` (upsert; new word → `due_at = now + 1 day`). Looking words up *is* the data source — zero extra effort from her. -- [ ] Endpoints: `POST /api/vocab` (record/upsert), `GET /api/vocab/due` (cards due now), `POST /api/vocab/{id}/review` (grade again/good/easy → reschedule), `GET /api/vocab` (full garden), `DELETE /api/vocab/{id}`. -- [ ] SR scheduler: gentle SM-2-lite / Leitner intervals (1d → 3d → 7d → 16d → 35d). No streak-shaming. This is the only genuinely new logic. -- [ ] Frontend Garden panel (sibling to `HistoryPanel`/`DocList`): each learned word a blossom, more reps → more bloomed; the `PetalCompanion` kitten naps among them. Flashcard review: captured sentence with the word blanked → recall → EN↔中文 flip → again/good/easy (direction flips for recognition *and* production). A 🤍 "save to garden" on `WordCard` for explicit saves alongside auto-capture. -- [ ] Verify via the millenia UI-test harness + go/tsc/vite clean. **Est. ~1½–2 days** (new package + table + panel/review UI; reuses existing panel/companion patterns). +- [x] New `internal/vocab` package + migration `0006_vocab_garden` (0005 was taken by collocation) — `vocab_words` table: `word, gloss, phonetic, example` (sentence captured at lookup), `doc_id` (`ON DELETE SET NULL` so a word outlives its source doc), + SM-2-lite scheduling: `due_at, interval_days, ease, reps, lapses, last_reviewed`; `UNIQUE(user_id, word)` + `idx_vocab_due`. +- [x] Auto-capture: `EditorCore.openWordLookup` fires `POST /api/vocab` after a successful lookup — **only for words the dictionary actually knows** (a real gloss or definition), so typos/proper-noun lookups don't clutter the garden. Captures the surrounding sentence (`sentenceAround`) + `doc_id`. Idempotent upsert: re-looking-up a word refreshes its gloss/phonetic/example but never resets its schedule. +- [x] Endpoints (`internal/vocab/handlers.go`): `POST /api/vocab` (upsert; new word → `due_at = datetime('now','+1 day')`), `GET /api/vocab/due` (due now, server-side `datetime('now')` comparison — avoids JS local-vs-UTC parsing bugs), `POST /api/vocab/{id}/review` (grade → reschedule via `datetime('now','+N days')`), `GET /api/vocab` (full garden), `DELETE /api/vocab/{id}`. All owner-scoped. +- [x] SR scheduler (`internal/vocab/scheduler.go`): gentle SM-2-lite / Leitner ladder (1d → 3d → 7d → 16d → 35d, then geometric by ease). "again" steps back to 1d + counts a lapse + nudges ease down (floored at 1.3) — no harsh wipe; "good" climbs one rung; "easy" climbs a rung and a bit more + raises ease. No streaks to break. +- [x] Frontend `GardenPanel` (slide-over drawer, sibling to `HistoryPanel`): each word a blossom that opens further with reps (🌱→🌿→🌷→🌸→🌺); a "复习 N 个词 · Review N due" button; per-word detail (phonetic/example/source-doc/remove); footer "🐱💤 N 朵花在花园里" — the sleepy kitten napping among the blossoms. **Flashcard review**: due queue, the example sentence with the word blanked (`blankOut`), flip to reveal word+phonetic+gloss+sentence, again/good/easy grades; **direction alternates** by cursor parity for recognition (EN→中文) *and* production (中文→EN). A 🤍/💚 "save to garden" toggle on `WordCard` alongside the silent auto-capture. Opened from a global 🌷 词汇花园 button in the app header. All copy bilingual zh-first. +- [x] Verified: go build/vet/test (`scheduler_test.go` — ladder/again-gentle/easy-further; `handlers_test.go` — capture/upsert/due/review/delete lifecycle + empty-word 400 + doc-delete SET NULL), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (throwaway DB) — full capture→list→due→review→delete flow + 400 on bad grade verified end-to-end. ### Phase 14 — Companion warmth + bedtime nag + night mode ✅ **Why:** the companion kitten is the heart of Petal's "built for her" feel. Three additions: (1) a wider, fresher pool of **encouraging phrases** so cheers don't repeat as quickly; (2) when she's still writing **late at night (≥11pm)**, the kitten gently nags her to go to bed; (3) at the same hour the whole app drifts into a calm **night mode** — dark moonlit theme + the falling petals become **falling stars**. Caring, never scolding — the sleepy-cat gag makes "you should be sleeping too 🐱💤" land perfectly. Self-contained, frontend-only. @@ -142,11 +142,12 @@ Multi-session build. **Source of truth for what's done and what's next.** Update ### 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) -- [ ] **Phase 12 — collocation coach**: gentle "natives usually say…" hints for non-native word pairings, as a third suggestion family. 🔜 (see Phase 12 above; build first) -- [ ] **Phase 13 — vocabulary garden**: spaced-repetition review built from looked-up words, surfaced as a blooming garden. 🔜 (see Phase 13 above) +- [x] **Phase 12 — collocation coach**: gentle "natives usually say…" hints for non-native word pairings, as a third suggestion family. ✅ (see Phase 12 above) +- [x] **Phase 13 — vocabulary garden**: spaced-repetition review built from looked-up words, surfaced as a blooming garden. ✅ (see Phase 13 above) - [x] **Phase 14 — companion warmth + bedtime nag + night mode**: more encouraging phrases, a gentle "go to bed" nudge after 11pm, and a calm dark theme + falling stars at night. ✅ (see Phase 14 above) ## Session log +- 2026-06-26: **Phases 12 + 13 complete** (collocation coach + vocabulary garden — "finish the rest of the build plan except Authentik/Traefik"). **Phase 12**: collocation drops in as a third suggestion family reusing the whole `runPass`/`pendingScope` machinery — `llm/collocation.go` (`RunCollocation`, 25s floor, reuses `ParseCheckpoint`), `collocationSystemPrompt`/`CollocationMessages` (warm "Natives usually say…" + Mandarin gloss, defers grammar elsewhere), migration `0005` **rebuilds** the suggestions table to extend the `type` CHECK (SQLite can't ALTER a CHECK), `collocationScope` + `CollocationLimit` + `POST /{id}/collocation`. **Caught a latent bug**: `grammarScope` was `type != 'voice'` → would wipe collocation flags; fixed to `type NOT IN ('voice','collocation')`. Frontend: `--color-blossom` pink, "Make it sound natural 🌸" toolbar pill, `collocating`/`runCollocation` in `useCheckpoint`, StatusBar dot — all into the existing rail/card. **Phase 13**: new `internal/vocab` package — migration `0006_vocab_garden` (`vocab_words`, SM-2-lite columns, doc_id `ON DELETE SET NULL`, `UNIQUE(user_id,word)`), `scheduler.go` (Leitner ladder 1/3/7/16/35 → geometric; gentle "again", no streak-shaming), `handlers.go` (capture-upsert/list/due/review/delete, all owner-scoped, time math via SQLite `datetime()` so stored values stay canonical-UTC). Auto-capture wired into `EditorCore.openWordLookup` (only dictionary-known words, captures the surrounding sentence + doc_id) + a 🤍/💚 toggle on `WordCard`. `GardenPanel` slide-over: blossom grid (bloom stage by reps), flashcard review (sentence blanked, flip, again/good/easy, direction alternates recognition↔production), sleepy-kitten footer; opened from a global 🌷 header button. Tests: `TestCollocationPassCoexists`, vocab `scheduler_test.go` + `handlers_test.go`, db CHECK test extended. go build/vet/test + tsc + vite + vitest (51/51) all clean; migration verified against a copy of the live DB; live backend smoke (throwaway DB) walked the full vocab lifecycle + the warm-502 collocation path. **Remaining: only the deferred infra bucket** — Authentik auth, Copyleaks Tier-2 (needs a public webhook), Docker/Traefik/deploy — all on hold per the user's "except Authentik/Traefik". - 2026-06-26: **Phase 14 complete** (companion warmth + bedtime nag + night mode). `tips.ts`: `ENCOURAGEMENTS` 5→10 lines; new `BEDTIME` array (4 lines, user-supplied English wit + gentle Mandarin leads). `useCompanion.ts`: bedtime branch in the 10s heartbeat (after idle-return + break, before the generic tip); only nudges while actively writing; own `lastBedtime` ref + 30min `BEDTIME_GAP`, respects `PROACTIVE_GAP`; new `'bedtime'` `BubbleTone` lingers ~4s longer. **Night mode** (added same session, user request): `lib/night.ts` centralizes `isBedtime()` + window (now shared by the nag too); `hooks/useNightMode.ts` toggles `petal-night` on `` (60s re-check); `index.css` `html.petal-night` re-points only the palette tokens → whole UI flips via `var()` (no component edits), 600ms dusk fade, print stays white; `PetalFall` gains a `night` prop → chunky cartoon power stars (`makeCartoonStar`, Mario/Kirby-style, 5 candy colors) mixed ~70/30 with small twinkle sparkles, gentle spin + shallow shimmer, effect re-inits on flip; App: `useNightMode()` → ``. tsc + vite clean, companion vitest 45/45; verified with real-browser Playwright screenshots (clock mocked to 23:30) — day petals/cream vs night stars/dark-plum, both pretty. Bedtime window is `BEDTIME_FROM`/`BEDTIME_TO` (local clock) for easy retune. - 2026-06-26: **Phase 11 complete** (writer power-ups, batch requested as "do it all"). Seven features: (1) in-doc **Find & Replace** — `SearchHighlight` decoration extension + `FindReplace` bar (Ctrl/Cmd+F, match-case, replace-all back-to-front, DOM scroll that doesn't trigger the selection bubble); (2) **read-aloud** Web Speech util + 🔊 in WordCard & selection bubble; (3) **keyboard/touch access** — Ctrl/Cmd+D caret lookup, Ctrl/Cmd+J rewrite, touch long-press (refactored `handleContextMenu` → shared `openWordLookup(pos)`); (4) **export-all** backup zip (`GET /api/docs/export-all`, `TestExportAll`, sidebar download links); (5) **smart typography** input-rules extension (curly quotes/em-dash/ellipsis, ASCII-only so CJK untouched); (6) **duplicate doc + sidebar sort + outline popover**; (7) **English phonetic** (pivoted from pinyin — IPA is what an English learner needs; pinyin annotates Chinese she already reads) via `scripts/build_phonetic.py` + embedded `phonetic.json.gz` + `Result.Phonetic` + WordCard `/ˈrɪvər/` line — **full 46,579-word dataset built from ECDICT** (the csv re-download worked; `--seed` mode kept as a csv-free fallback). Also folded in this session: the **selection-bubble vs copy/paste fix** (bubble deferred to pointer-up + container `pointer-events:none` so it never sits where you click). go build/vet/test + tsc + vite all clean; live smoke verified word-phonetic (incl. de-inflection) + export-all zip (de-duped CJK names, route priority). Next: deferred bucket (auth/Copyleaks/deploy), still on hold per user. - 2026-06-26: **Phase 10 complete** (organization & polish). Scope confirmed with user: all four areas, **tags** (not folders), **FTS5** search. Backend: migration `0004_tags_and_search` (tags + document_tags + `documents_fts` trigram virtual table with sync triggers + back-fill); `db.Tag` model + color constants; `internal/docs/tags.go` (tag CRUD + idempotent assignment + `tagsByDoc` helper, doc list now carries tags); `internal/docs/search.go` (`GET /api/search`, FTS for ≥3 runes + LIKE fallback for 1-2, Go-built sentinel-highlighted rune-aware snippets, owner-scoped). Mounted `/api/tags` + `/api/search` in main.go. Frontend: `useTags`, `TagChip`/`TagPicker`/`SearchBox`, rewritten `DocList`/`DocListItem` (chips + filter bar + search), `api.search`/tag methods + `splitSnippet`/`tagColorVar`; responsive sidebar drawer (hamburger + scrim, <768px) + `pointer:coarse` tap-target/affordance CSS; tap-to-open + outside-pointerdown-close for suggestion cards (touch); `useCheckpoint` `llmDown` flag → warm bilingual "小助手在休息" StatusBar note. Tests: `tags_test.go`, `search_test.go` (incl. update-trigger re-index). All builds/tests/vet/tsc/vite clean; live smoke vs binary on :8061 (dead LLM host) verified search EN/CJK/2-char, full tag lifecycle, check→502 warm path, bundle contents; FTS backfill of pre-existing docs verified. **All v1 phases (0–7) + post-v1 product (8–10) done.** Remaining: deferred bucket (auth/Copyleaks/deploy), on hold per user. diff --git a/cmd/server/main.go b/cmd/server/main.go index 206bb6c..c4ff306 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -20,6 +20,7 @@ import ( "gitea.parodia.dev/drwily/petal/internal/llm" "gitea.parodia.dev/drwily/petal/internal/suggestions" "gitea.parodia.dev/drwily/petal/internal/tts" + "gitea.parodia.dev/drwily/petal/internal/vocab" "gitea.parodia.dev/drwily/petal/web" ) @@ -83,6 +84,10 @@ func main() { api.Mount("/word", lex.Routes()) api.Mount("/gloss", lex.GlossRoutes()) + // Vocabulary garden: words the writer looks up are captured here and + // surfaced for gentle spaced-repetition review. + api.Mount("/vocab", vocab.New(database).Routes()) + // Editor image uploads, stored on disk and served back by content hash. imgHandler, err := images.New(cfg.ImageDir) if err != nil { diff --git a/internal/db/db.go b/internal/db/db.go index f52d644..f2f171d 100644 --- a/internal/db/db.go +++ b/internal/db/db.go @@ -260,6 +260,71 @@ END; INSERT INTO documents_fts (doc_id, title, content_text) SELECT id, title, content_text FROM documents; +`, + }, + { + // Collocation coach (Phase 12). Adds a third suggestion family, + // 'collocation', for gentle "natives usually say…" hints on + // non-native word pairings. The `type` column carries a CHECK + // constraint and SQLite cannot ALTER one in place, so we rebuild the + // suggestions table with the extended CHECK, copy every row across, + // and recreate its index. Nothing references suggestions, so dropping + // the old table is safe; the new table keeps the same ON DELETE + // CASCADE to documents. + name: "0005_collocation_suggestion_type", + stmt: ` +CREATE TABLE suggestions_new ( + id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))), + doc_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE, + from_pos INTEGER NOT NULL, + to_pos INTEGER NOT NULL, + original TEXT NOT NULL, + replacement TEXT NOT NULL, + explanation TEXT NOT NULL, + type TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice','collocation')), + status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')), + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +INSERT INTO suggestions_new (id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at) +SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at FROM suggestions; + +DROP TABLE suggestions; +ALTER TABLE suggestions_new RENAME TO suggestions; +CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id); +`, + }, + { + // Vocabulary garden (Phase 13). Every word the writer looks up is + // captured here and put on a gentle spaced-repetition schedule, turning + // passive lookups into real vocabulary. `example` holds the sentence the + // word appeared in (captured at lookup) for context during review; + // `doc_id` links back to where she met the word (nulled if that doc is + // deleted — the word stays in the garden). The SM-2-lite scheduling + // columns (due_at/interval_days/ease/reps/lapses/last_reviewed) drive a + // Leitner-style ladder (see internal/vocab/scheduler.go). UNIQUE on + // (user_id, word) makes capture an idempotent upsert. + name: "0006_vocab_garden", + stmt: ` +CREATE TABLE vocab_words ( + id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))), + user_id TEXT NOT NULL REFERENCES users(id), + word TEXT NOT NULL, + gloss TEXT NOT NULL DEFAULT '', + phonetic TEXT NOT NULL DEFAULT '', + example TEXT NOT NULL DEFAULT '', + doc_id TEXT REFERENCES documents(id) ON DELETE SET NULL, + due_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + interval_days INTEGER NOT NULL DEFAULT 0, + ease REAL NOT NULL DEFAULT 2.5, + reps INTEGER NOT NULL DEFAULT 0, + lapses INTEGER NOT NULL DEFAULT 0, + last_reviewed DATETIME, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + UNIQUE(user_id, word) +); + +CREATE INDEX idx_vocab_due ON vocab_words(user_id, due_at); `, }, } diff --git a/internal/db/db_test.go b/internal/db/db_test.go index df7fd09..1eb12b8 100644 --- a/internal/db/db_test.go +++ b/internal/db/db_test.go @@ -39,6 +39,14 @@ func TestOpenMigratesAndSeeds(t *testing.T) { t.Fatalf("insert voice suggestion: %v", err) } + // The collocation type (added by migration 0005's table rebuild) is permitted. + if _, err := d.Exec( + `INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type) + VALUES ('d1', 0, 9, 'do a decision', 'make a decision', 'natives usually say…', 'collocation')`, + ); err != nil { + t.Fatalf("insert collocation suggestion: %v", err) + } + // An invalid type is rejected. if _, err := d.Exec( `INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type) diff --git a/internal/db/models.go b/internal/db/models.go index 82f5423..9777ffa 100644 --- a/internal/db/models.go +++ b/internal/db/models.go @@ -88,18 +88,19 @@ type Suggestion struct { Original string `json:"original"` Replacement string `json:"replacement"` Explanation string `json:"explanation"` - Type string `json:"type"` // grammar | phrasing | idiom | clarity | voice + Type string `json:"type"` // grammar | phrasing | idiom | clarity | voice | collocation Status string `json:"status"` // pending | accepted | rejected CreatedAt time.Time `json:"created_at"` } // Suggestion type and status values, mirrored from the schema CHECK constraints. const ( - SuggestionTypeGrammar = "grammar" - SuggestionTypePhrasing = "phrasing" - SuggestionTypeIdiom = "idiom" - SuggestionTypeClarity = "clarity" - SuggestionTypeVoice = "voice" + SuggestionTypeGrammar = "grammar" + SuggestionTypePhrasing = "phrasing" + SuggestionTypeIdiom = "idiom" + SuggestionTypeClarity = "clarity" + SuggestionTypeVoice = "voice" + SuggestionTypeCollocation = "collocation" SuggestionStatusPending = "pending" SuggestionStatusAccepted = "accepted" diff --git a/internal/llm/collocation.go b/internal/llm/collocation.go new file mode 100644 index 0000000..c6442a8 --- /dev/null +++ b/internal/llm/collocation.go @@ -0,0 +1,35 @@ +package llm + +import ( + "context" + "time" +) + +// CollocationInterval is the minimum gap between collocation passes for one +// document. Like the voice pass it runs on an explicit user action ("Make it +// sound natural") rather than a typing cadence, so this floor only guards the +// inference endpoint against the button being mashed. +const CollocationInterval = 25 * time.Second + +// RunCollocation sends the WHOLE document for a collocation pass — gentle +// "natives usually say…" hints on non-native word pairings — and parses the JSON +// result with the checkpoint's tolerant parser. It is deliberately NOT +// TruncateDoc'd: like the voice pass it reads the whole document so the hints +// reflect the full piece. Each flag carries a native replacement to apply. +// +// The tone argument is accepted for a uniform pass signature and passed through +// to the prompt so a hint can prefer a register-appropriate pairing. +func RunCollocation(ctx context.Context, client LLMClient, contentText, tone string) ([]RawSuggestion, error) { + raw, err := client.Complete(ctx, CompletionRequest{ + Messages: CollocationMessages(contentText, tone), + MaxTokens: 2048, + Temperature: 0.3, + RepetitionPenalty: 1.15, + TopP: 0.9, + Stop: []string{"```", "\n\n\n\n"}, + }) + if err != nil { + return nil, err + } + return ParseCheckpoint(raw) +} diff --git a/internal/llm/prompts.go b/internal/llm/prompts.go index f24d24e..d564052 100644 --- a/internal/llm/prompts.go +++ b/internal/llm/prompts.go @@ -92,6 +92,54 @@ func VoiceMessages(contentText string) []Message { } } +// collocationSystemPrompt drives the collocation coach — the single most +// valuable polish for an ESL writer. It flags word PAIRINGS that are not wrong, +// just non-native ("do a decision" → "make a decision", "strong rain" → "heavy +// rain"), and explicitly DEFERS real grammar/spelling errors to the grammar +// checkpoint so the two families don't overlap. Every explanation is framed as a +// warm "natives usually say…" note with a short Mandarin gloss — never +// "error/wrong" — because these are stylistic, not mistakes. It is a distinct +// pass from the grammar checkpoint (do not bundle them). `replacement` carries +// the natural pairing the writer can accept in one tap. +const collocationSystemPrompt = `You are a warm, encouraging writing assistant helping someone who speaks English as a second language. ` + + `You are reviewing a COMPLETE document for COLLOCATIONS only — the natural word pairings native speakers use. + +A collocation is a pair or short group of words that native speakers habitually say together. ESL writers ` + + `often choose words that are grammatically correct but sound non-native: "do a decision" instead of "make a decision", ` + + `"strong rain" instead of "heavy rain", "say a joke" instead of "tell a joke". These are NOT grammar mistakes — they ` + + `are just not what a native speaker would naturally say. + +Identify up to 5 such non-native word pairings. For each, give the natural pairing a native speaker would use. ` + + `Be gentle and specific. Do NOT flag grammar errors, spelling mistakes, or unclear sentences — those are handled ` + + `elsewhere. Only flag word pairings that are correct but sound non-native.%s + +Phrase every explanation warmly as "Natives usually say…" and include a brief Simplified Chinese gloss in parentheses. ` + + `Never use the words "error", "wrong", or "mistake" — these are friendly polish, not corrections. + +Respond ONLY with valid JSON. No preamble, no markdown fences. Format: +{ + "suggestions": [ + { + "original": "exact word pairing from the document", + "replacement": "the natural native pairing", + "explanation": "friendly note, e.g. 'Natives usually say \"make a decision\" rather than \"do a decision\" (native usage / 地道说法).'", + "type": "collocation" + } + ] +} + +If every pairing already sounds natural, return: {"suggestions": []}` + +// CollocationMessages builds the message array for a collocation pass over the +// WHOLE document (no truncation), gently steered toward the document's tone so a +// hint can prefer a register-appropriate pairing. +func CollocationMessages(contentText, tone string) []Message { + return []Message{ + {Role: "system", Content: fmt.Sprintf(collocationSystemPrompt, toneGuidance(tone))}, + {Role: "user", Content: contentText}, + } +} + // askPetalSystemTemplate is the Ask Petal tutor prompt. The suggestion context // is interpolated in; the user's own messages are appended after this system // turn by the caller. diff --git a/internal/suggestions/handlers.go b/internal/suggestions/handlers.go index 5806214..fd42139 100644 --- a/internal/suggestions/handlers.go +++ b/internal/suggestions/handlers.go @@ -23,19 +23,22 @@ import ( // grammar checkpoint and the voice pass each get their own per-document rate // limiter — they are independent passes with different cadences. type Handler struct { - DB *db.DB - Client llm.LLMClient - Limit *llm.RateLimiter // grammar checkpoint floor - VoiceLimit *llm.RateLimiter // voice-consistency floor + DB *db.DB + Client llm.LLMClient + Limit *llm.RateLimiter // grammar checkpoint floor + VoiceLimit *llm.RateLimiter // voice-consistency floor + CollocationLimit *llm.RateLimiter // collocation-coach floor } -// New constructs a Handler with per-document checkpoint and voice rate limiters. +// New constructs a Handler with per-document checkpoint, voice, and collocation +// rate limiters. func New(database *db.DB, client llm.LLMClient) *Handler { return &Handler{ - DB: database, - Client: client, - Limit: llm.NewRateLimiter(llm.CheckpointInterval), - VoiceLimit: llm.NewRateLimiter(llm.VoiceInterval), + DB: database, + Client: client, + Limit: llm.NewRateLimiter(llm.CheckpointInterval), + VoiceLimit: llm.NewRateLimiter(llm.VoiceInterval), + CollocationLimit: llm.NewRateLimiter(llm.CollocationInterval), } } @@ -44,6 +47,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}/collocation", h.collocation) r.Post("/{id}/rewrite", h.rewrite) r.Get("/{id}/suggestions", h.listForDoc) } @@ -70,6 +74,13 @@ func (h *Handler) voice(w http.ResponseWriter, r *http.Request) { h.runPass(w, r, h.VoiceLimit, llm.RunVoice, voiceScope) } +// collocation runs the collocation coach over the whole document, flagging +// non-native word pairings. Explicit-action pass; replaces only the pending +// collocation flags. +func (h *Handler) collocation(w http.ResponseWriter, r *http.Request) { + h.runPass(w, r, h.CollocationLimit, llm.RunCollocation, collocationScope) +} + // pass is the signature shared by the grammar checkpoint and the voice pass: // given the document text and the document's tone it returns the model's raw // suggestions. The voice pass ignores tone (see llm.RunVoice). @@ -151,10 +162,14 @@ type pendingScope struct { } var ( - // grammarScope owns the grammar/phrasing/idiom/clarity flags (everything but voice). - grammarScope = pendingScope{deleteWhere: "type != 'voice'", forceType: ""} + // grammarScope owns the grammar/phrasing/idiom/clarity flags — everything but + // the explicit-action families (voice, collocation), which run on their own + // cadence and must survive a grammar checkpoint. + grammarScope = pendingScope{deleteWhere: "type NOT IN ('voice','collocation')", forceType: ""} // voiceScope owns the voice flags only. voiceScope = pendingScope{deleteWhere: "type = 'voice'", forceType: db.SuggestionTypeVoice} + // collocationScope owns the collocation flags only. + collocationScope = pendingScope{deleteWhere: "type = 'collocation'", forceType: db.SuggestionTypeCollocation} ) // replacePending swaps a document's pending suggestions within one family for a @@ -320,7 +335,7 @@ func locate(contentText, original string) (int, int) { // defaulting unknown values to grammar so a stray label never trips the CHECK. func normalizeType(t string) string { switch strings.ToLower(strings.TrimSpace(t)) { - case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity: + case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity, db.SuggestionTypeCollocation: return strings.ToLower(strings.TrimSpace(t)) default: return db.SuggestionTypeGrammar diff --git a/internal/suggestions/handlers_test.go b/internal/suggestions/handlers_test.go index db97bc6..d5f5e70 100644 --- a/internal/suggestions/handlers_test.go +++ b/internal/suggestions/handlers_test.go @@ -227,6 +227,65 @@ func TestVoicePassCoexists(t *testing.T) { } } +// TestCollocationPassCoexists proves the collocation coach is a third +// independent family: it never wipes grammar or voice pending flags, a grammar +// checkpoint never wipes its flags, and each endpoint returns the unified set. +func TestCollocationPassCoexists(t *testing.T) { + client := &switchClient{} + srv, docID, h := newTestServer(t, client) + // Zero the floors so the test can re-run passes without waiting them out. + h.Limit = llm.NewRateLimiter(0) + h.VoiceLimit = llm.NewRateLimiter(0) + h.CollocationLimit = llm.NewRateLimiter(0) + + // Grammar + voice first, so all three families are exercised. + client.response = `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"agreement","type":"grammar"}]}` + if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", ""); rec.Code != http.StatusOK { + t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body) + } + client.response = `{"suggestions":[{"original":"two apple","replacement":null,"explanation":"sounds formal","type":"voice"}]}` + if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/voice", ""); rec.Code != http.StatusOK { + t.Fatalf("voice: code=%d body=%s", rec.Code, rec.Body) + } + + // Collocation pass → a third flag (with a replacement). It must keep the + // grammar and voice flags; the response is the unified set of all three. + client.response = `{"suggestions":[{"original":"two apple","replacement":"two apples","explanation":"Natives usually say…","type":"collocation"}]}` + rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/collocation", "") + if rec.Code != http.StatusOK { + t.Fatalf("collocation: code=%d body=%s", rec.Code, rec.Body) + } + var got []db.Suggestion + if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil { + t.Fatalf("decode: %v", err) + } + byType := map[string]bool{} + for _, s := range got { + byType[s.Type] = true + } + if !byType[db.SuggestionTypeGrammar] || !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] { + t.Fatalf("collocation response should carry all three families, got %+v", got) + } + + // A grammar checkpoint must NOT wipe the voice or collocation flags. + client.response = `{"suggestions":[]}` + rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "") + if rec.Code != http.StatusOK { + t.Fatalf("second check: code=%d body=%s", rec.Code, rec.Body) + } + _ = json.Unmarshal(rec.Body.Bytes(), &got) + byType = map[string]bool{} + for _, s := range got { + byType[s.Type] = true + } + if byType[db.SuggestionTypeGrammar] { + t.Fatalf("grammar flag should have cleared, got %+v", got) + } + if !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] { + t.Fatalf("grammar checkpoint wiped a sibling family, got %+v", got) + } +} + // switchClient returns a response that can be swapped between calls. type switchClient struct { response string diff --git a/internal/vocab/handlers.go b/internal/vocab/handlers.go new file mode 100644 index 0000000..1dbc9c4 --- /dev/null +++ b/internal/vocab/handlers.go @@ -0,0 +1,245 @@ +package vocab + +import ( + "database/sql" + "encoding/json" + "errors" + "net/http" + "strconv" + "strings" + "time" + + "github.com/go-chi/chi/v5" + + "gitea.parodia.dev/drwily/petal/internal/db" +) + +// Word is one entry in the vocabulary garden: the looked-up word with its gloss, +// phonetic, and the sentence it was met in, plus its spaced-repetition state. +type Word struct { + ID string `json:"id"` + Word string `json:"word"` + Gloss string `json:"gloss"` + Phonetic string `json:"phonetic"` + Example string `json:"example"` + DocID *string `json:"doc_id"` + DueAt time.Time `json:"due_at"` + IntervalDays int `json:"interval_days"` + Ease float64 `json:"ease"` + Reps int `json:"reps"` + Lapses int `json:"lapses"` + LastReviewed *time.Time `json:"last_reviewed"` + CreatedAt time.Time `json:"created_at"` +} + +// Handler owns the vocabulary-garden routes. Everything is scoped to the local +// user while auth is deferred. +type Handler struct { + DB *db.DB +} + +func New(database *db.DB) *Handler { return &Handler{DB: database} } + +// Routes mounts the garden endpoints under /api/vocab. +func (h *Handler) Routes() chi.Router { + r := chi.NewRouter() + r.Get("/", h.list) // the whole garden + r.Get("/due", h.due) // only the cards due for review now + r.Post("/", h.capture) // record/upsert a looked-up word + r.Post("/{id}/review", h.review) + r.Delete("/{id}", h.remove) + return r +} + +const vocabColumns = `id, word, gloss, phonetic, example, doc_id, + due_at, interval_days, ease, reps, lapses, last_reviewed, created_at` + +func scanWord(s interface { + Scan(dest ...any) error +}) (Word, error) { + var w Word + err := s.Scan( + &w.ID, &w.Word, &w.Gloss, &w.Phonetic, &w.Example, &w.DocID, + &w.DueAt, &w.IntervalDays, &w.Ease, &w.Reps, &w.Lapses, &w.LastReviewed, &w.CreatedAt, + ) + return w, err +} + +// list returns the full garden, newest blossoms first. +func (h *Handler) list(w http.ResponseWriter, _ *http.Request) { + h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words + WHERE user_id = ? ORDER BY created_at DESC`, db.LocalUserID) +} + +// due returns only the cards whose review time has arrived, soonest first. +func (h *Handler) due(w http.ResponseWriter, _ *http.Request) { + h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words + WHERE user_id = ? AND due_at <= datetime('now') ORDER BY due_at ASC`, db.LocalUserID) +} + +func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) { + rows, err := h.DB.Query(query, args...) + if err != nil { + serverError(w, err) + return + } + defer rows.Close() + out := []Word{} + for rows.Next() { + word, err := scanWord(rows) + if err != nil { + serverError(w, err) + return + } + out = append(out, word) + } + writeJSON(w, http.StatusOK, out) +} + +type captureRequest struct { + Word string `json:"word"` + Gloss string `json:"gloss"` + Phonetic string `json:"phonetic"` + Example string `json:"example"` + DocID *string `json:"doc_id"` +} + +// capture records a looked-up word. It's an idempotent upsert keyed on the word: +// a new word lands due tomorrow (interval 1 day); an existing word keeps its +// schedule untouched but refreshes its gloss/phonetic/example/doc_id so the most +// recent context wins. Looking words up IS the data source — no extra effort. +func (h *Handler) capture(w http.ResponseWriter, r *http.Request) { + var req captureRequest + if err := json.NewDecoder(r.Body).Decode(&req); err != nil { + errorJSON(w, http.StatusBadRequest, "invalid body") + return + } + word := strings.TrimSpace(req.Word) + if word == "" { + errorJSON(w, http.StatusBadRequest, "word is required") + return + } + + // New rows start due tomorrow; ON CONFLICT refreshes context but leaves the + // schedule (due_at/reps/interval/ease) alone so re-looking-up a word never + // resets its progress. + _, err := h.DB.Exec( + `INSERT INTO vocab_words (user_id, word, gloss, phonetic, example, doc_id, due_at, interval_days) + VALUES (?, ?, ?, ?, ?, ?, datetime('now', '+1 day'), 1) + ON CONFLICT(user_id, word) DO UPDATE SET + gloss = excluded.gloss, + phonetic = excluded.phonetic, + example = CASE WHEN excluded.example != '' THEN excluded.example ELSE vocab_words.example END, + doc_id = COALESCE(excluded.doc_id, vocab_words.doc_id)`, + db.LocalUserID, word, req.Gloss, req.Phonetic, req.Example, req.DocID, + ) + if err != nil { + serverError(w, err) + return + } + + out, err := h.fetch(word) + if err != nil { + serverError(w, err) + return + } + writeJSON(w, http.StatusCreated, out) +} + +// fetch loads one word row by its (user, word) key. +func (h *Handler) fetch(word string) (Word, error) { + return scanWord(h.DB.QueryRow( + `SELECT `+vocabColumns+` FROM vocab_words WHERE user_id = ? AND word = ?`, + db.LocalUserID, word, + )) +} + +type reviewRequest struct { + Grade Grade `json:"grade"` +} + +// review grades one card and reschedules it. The grade drives the SM-2-lite +// scheduler; the new interval is applied as `due_at = now + interval days`. +func (h *Handler) review(w http.ResponseWriter, r *http.Request) { + id := chi.URLParam(r, "id") + var req reviewRequest + if err := json.NewDecoder(r.Body).Decode(&req); err != nil { + errorJSON(w, http.StatusBadRequest, "invalid body") + return + } + if req.Grade != GradeAgain && req.Grade != GradeGood && req.Grade != GradeEasy { + errorJSON(w, http.StatusBadRequest, "grade must be again, good, or easy") + return + } + + var cur State + err := h.DB.QueryRow( + `SELECT reps, interval_days, ease, lapses FROM vocab_words WHERE id = ? AND user_id = ?`, + id, db.LocalUserID, + ).Scan(&cur.Reps, &cur.Interval, &cur.Ease, &cur.Lapses) + if errors.Is(err, sql.ErrNoRows) { + errorJSON(w, http.StatusNotFound, "word not found") + return + } + if err != nil { + serverError(w, err) + return + } + + nxt := cur.next(req.Grade) + // `datetime('now', '+N days')` keeps the stored value in SQLite's canonical + // text format, matching CURRENT_TIMESTAMP and the due query's comparison. + offset := "+" + strconv.Itoa(nxt.Interval) + " days" + if _, err := h.DB.Exec( + `UPDATE vocab_words SET + reps = ?, interval_days = ?, ease = ?, lapses = ?, + last_reviewed = datetime('now'), due_at = datetime('now', ?) + WHERE id = ? AND user_id = ?`, + nxt.Reps, nxt.Interval, nxt.Ease, nxt.Lapses, offset, id, db.LocalUserID, + ); err != nil { + serverError(w, err) + return + } + + out, err := scanWord(h.DB.QueryRow( + `SELECT `+vocabColumns+` FROM vocab_words WHERE id = ? AND user_id = ?`, id, db.LocalUserID, + )) + if err != nil { + serverError(w, err) + return + } + writeJSON(w, http.StatusOK, out) +} + +// remove deletes a word from the garden (e.g. the writer already knows it). +func (h *Handler) remove(w http.ResponseWriter, r *http.Request) { + res, err := h.DB.Exec( + `DELETE FROM vocab_words WHERE id = ? AND user_id = ?`, + chi.URLParam(r, "id"), db.LocalUserID, + ) + if err != nil { + serverError(w, err) + return + } + if n, _ := res.RowsAffected(); n == 0 { + errorJSON(w, http.StatusNotFound, "word not found") + return + } + w.WriteHeader(http.StatusNoContent) +} + +// --- response helpers ------------------------------------------------------- + +func writeJSON(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) +} + +func errorJSON(w http.ResponseWriter, status int, msg string) { + writeJSON(w, status, map[string]string{"error": msg}) +} + +func serverError(w http.ResponseWriter, err error) { + errorJSON(w, http.StatusInternalServerError, err.Error()) +} diff --git a/internal/vocab/handlers_test.go b/internal/vocab/handlers_test.go new file mode 100644 index 0000000..f4b542f --- /dev/null +++ b/internal/vocab/handlers_test.go @@ -0,0 +1,170 @@ +package vocab + +import ( + "bytes" + "encoding/json" + "net/http" + "net/http/httptest" + "path/filepath" + "testing" + + "github.com/go-chi/chi/v5" + + "gitea.parodia.dev/drwily/petal/internal/db" +) + +func newTestServer(t *testing.T) (http.Handler, *db.DB) { + t.Helper() + database, err := db.Open(filepath.Join(t.TempDir(), "test.db")) + if err != nil { + t.Fatalf("open db: %v", err) + } + t.Cleanup(func() { database.Close() }) + r := chi.NewRouter() + r.Mount("/vocab", New(database).Routes()) + return r, database +} + +func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder { + t.Helper() + var r *http.Request + if body != "" { + r = httptest.NewRequest(method, path, bytes.NewBufferString(body)) + } else { + r = httptest.NewRequest(method, path, nil) + } + rec := httptest.NewRecorder() + srv.ServeHTTP(rec, r) + return rec +} + +// TestCaptureUpsertAndReview walks the garden lifecycle: capture a word (lands +// in the future, not yet due), re-capture refreshes context without resetting +// schedule, a forced-due word shows up in /due, a review reschedules it, and +// delete removes it. +func TestCaptureUpsertAndReview(t *testing.T) { + srv, database := newTestServer(t) + + // Capture a new word → 201, due tomorrow (interval 1), not in /due yet. + rec := do(t, srv, http.MethodPost, "/vocab", + `{"word":"serendipity","gloss":"机缘巧合","phonetic":"/ˌserənˈdɪpəti/","example":"What a serendipity."}`) + if rec.Code != http.StatusCreated { + t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body) + } + var w Word + _ = json.Unmarshal(rec.Body.Bytes(), &w) + if w.ID == "" || w.Word != "serendipity" || w.Gloss != "机缘巧合" { + t.Fatalf("captured word wrong: %+v", w) + } + if w.IntervalDays != 1 || w.Reps != 0 { + t.Fatalf("new word should start at interval 1, reps 0: %+v", w) + } + + // Not due yet (due tomorrow). + rec = do(t, srv, http.MethodGet, "/vocab/due", "") + var due []Word + _ = json.Unmarshal(rec.Body.Bytes(), &due) + if len(due) != 0 { + t.Fatalf("freshly-captured word should not be due yet, got %d", len(due)) + } + + // Re-capture with a new gloss → still one row (idempotent upsert), refreshed. + rec = do(t, srv, http.MethodPost, "/vocab", + `{"word":"serendipity","gloss":"意外的好运","phonetic":"/x/","example":""}`) + if rec.Code != http.StatusCreated { + t.Fatalf("re-capture: code=%d body=%s", rec.Code, rec.Body) + } + rec = do(t, srv, http.MethodGet, "/vocab", "") + var all []Word + _ = json.Unmarshal(rec.Body.Bytes(), &all) + if len(all) != 1 { + t.Fatalf("re-capture should not add a row, got %d", len(all)) + } + if all[0].Gloss != "意外的好运" { + t.Fatalf("gloss should refresh on re-capture, got %q", all[0].Gloss) + } + if all[0].Example != "What a serendipity." { + t.Fatalf("empty example should not clobber the prior one, got %q", all[0].Example) + } + + // Force it due now, then it appears in /due. + if _, err := database.Exec(`UPDATE vocab_words SET due_at = datetime('now','-1 hour')`); err != nil { + t.Fatalf("force due: %v", err) + } + rec = do(t, srv, http.MethodGet, "/vocab/due", "") + _ = json.Unmarshal(rec.Body.Bytes(), &due) + if len(due) != 1 { + t.Fatalf("forced-due word should be in /due, got %d", len(due)) + } + + // Review "good" → reschedules forward (interval 3 = second ladder rung, since + // reps was 0 and a capture set interval 1 but reps 0; first good → rung 1 = 1). + rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"good"}`) + if rec.Code != http.StatusOK { + t.Fatalf("review: code=%d body=%s", rec.Code, rec.Body) + } + var reviewed Word + _ = json.Unmarshal(rec.Body.Bytes(), &reviewed) + if reviewed.Reps != 1 || reviewed.IntervalDays != 1 { + t.Fatalf("first good review should be reps 1, interval 1: %+v", reviewed) + } + if reviewed.LastReviewed == nil { + t.Fatalf("review should stamp last_reviewed") + } + + // After a forward review it's no longer due. + rec = do(t, srv, http.MethodGet, "/vocab/due", "") + _ = json.Unmarshal(rec.Body.Bytes(), &due) + if len(due) != 0 { + t.Fatalf("reviewed word should leave /due, got %d", len(due)) + } + + // Bad grade → 400. + if rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"nope"}`); rec.Code != http.StatusBadRequest { + t.Fatalf("bad grade: want 400, got %d", rec.Code) + } + + // Delete → 204, garden empty. + if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNoContent { + t.Fatalf("delete: code=%d", rec.Code) + } + if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNotFound { + t.Fatalf("re-delete: want 404, got %d", rec.Code) + } +} + +// TestCaptureValidation rejects an empty word. +func TestCaptureValidation(t *testing.T) { + srv, _ := newTestServer(t) + if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":" "}`); rec.Code != http.StatusBadRequest { + t.Fatalf("empty word: want 400, got %d", rec.Code) + } +} + +// TestDocLinkSurvivesDocDelete proves the ON DELETE SET NULL keeps a word in the +// garden when its source document is removed. +func TestDocLinkSurvivesDocDelete(t *testing.T) { + srv, database := newTestServer(t) + var docID string + if err := database.QueryRow( + `INSERT INTO documents (user_id, content_text) VALUES (?, 'hi') RETURNING id`, db.LocalUserID, + ).Scan(&docID); err != nil { + t.Fatalf("seed doc: %v", err) + } + rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"ephemeral","gloss":"短暂的","doc_id":"`+docID+`"}`) + if rec.Code != http.StatusCreated { + t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body) + } + if _, err := database.Exec(`DELETE FROM documents WHERE id = ?`, docID); err != nil { + t.Fatalf("delete doc: %v", err) + } + rec = do(t, srv, http.MethodGet, "/vocab", "") + var all []Word + _ = json.Unmarshal(rec.Body.Bytes(), &all) + if len(all) != 1 { + t.Fatalf("word should survive doc deletion, got %d", len(all)) + } + if all[0].DocID != nil { + t.Fatalf("doc_id should be nulled after doc delete, got %v", *all[0].DocID) + } +} diff --git a/internal/vocab/scheduler.go b/internal/vocab/scheduler.go new file mode 100644 index 0000000..d60dbb9 --- /dev/null +++ b/internal/vocab/scheduler.go @@ -0,0 +1,97 @@ +// Package vocab implements the vocabulary garden: it captures words the writer +// looks up and schedules them for gentle spaced-repetition review. The scheduler +// is a deliberately forgiving SM-2-lite / Leitner hybrid — no streaks to break, +// no harsh resets beyond a single step back — because this is a confidence +// builder, not a drill sergeant. +package vocab + +import "math" + +// Grade is the writer's self-assessment after seeing a flashcard's answer. +type Grade string + +const ( + GradeAgain Grade = "again" // didn't recall it — show again soon + GradeGood Grade = "good" // recalled it — advance one rung + GradeEasy Grade = "easy" // knew it instantly — advance a little further +) + +// ladder is the Leitner interval ladder in days for the first several successful +// reviews: 1 → 3 → 7 → 16 → 35. Beyond the ladder, intervals grow by the card's +// ease factor so well-known words drift far into the future. +var ladder = []int{1, 3, 7, 16, 35} + +const ( + minEase = 1.3 + startEase = 2.5 + easyBonus = 1.3 // multiplier applied on top of a "good" step for "easy" + easeAgainDelta = -0.20 // ease nudged down on a lapse (still floored at minEase) + easeEasyDelta = 0.15 // ease nudged up when a card feels easy +) + +// State is the spaced-repetition state of one card. It mirrors the scheduling +// columns on vocab_words so a review is "load State → next(grade) → persist". +type State struct { + Reps int + Interval int // days until the next review + Ease float64 + Lapses int +} + +// next returns the card's state after a review with the given grade. It never +// mutates the receiver. "again" steps the card back to a 1-day interval and +// counts a lapse (but only nudges ease down, never wipes progress harshly); +// "good" advances one rung of the ladder; "easy" advances a rung and a bit more. +func (s State) next(grade Grade) State { + ease := s.Ease + if ease == 0 { + ease = startEase + } + + switch grade { + case GradeAgain: + return State{ + Reps: 0, + Interval: 1, + Ease: clampEase(ease + easeAgainDelta), + Lapses: s.Lapses + 1, + } + case GradeEasy: + ease = clampEase(ease + easeEasyDelta) + reps := s.Reps + 1 + return State{ + Reps: reps, + Interval: int(math.Round(float64(goodInterval(reps, s.Interval, ease)) * easyBonus)), + Ease: ease, + Lapses: s.Lapses, + } + default: // GradeGood + reps := s.Reps + 1 + return State{ + Reps: reps, + Interval: goodInterval(reps, s.Interval, ease), + Ease: ease, + Lapses: s.Lapses, + } + } +} + +// goodInterval returns the day-interval for a successful review: the explicit +// ladder while it lasts, then geometric growth by ease once past it. +func goodInterval(reps, prevInterval int, ease float64) int { + if reps >= 1 && reps <= len(ladder) { + return ladder[reps-1] + } + prev := prevInterval + if prev < ladder[len(ladder)-1] { + prev = ladder[len(ladder)-1] + } + return int(math.Round(float64(prev) * ease)) +} + +func clampEase(e float64) float64 { + if e < minEase { + return minEase + } + return e +} diff --git a/internal/vocab/scheduler_test.go b/internal/vocab/scheduler_test.go new file mode 100644 index 0000000..2dc2a68 --- /dev/null +++ b/internal/vocab/scheduler_test.go @@ -0,0 +1,66 @@ +package vocab + +import "testing" + +// TestLadderProgression walks a card up the Leitner ladder on repeated "good" +// reviews: 1 → 3 → 7 → 16 → 35 days, then geometric growth by ease. +func TestLadderProgression(t *testing.T) { + s := State{Ease: startEase} + want := []int{1, 3, 7, 16, 35} + for i, w := range want { + s = s.next(GradeGood) + if s.Interval != w { + t.Fatalf("rung %d: interval=%d, want %d", i, s.Interval, w) + } + if s.Reps != i+1 { + t.Fatalf("rung %d: reps=%d, want %d", i, s.Reps, i+1) + } + } + // Past the ladder it grows by ease (35 * 2.5 = 87.5 → 88). + s = s.next(GradeGood) + if s.Interval != 88 { + t.Fatalf("post-ladder interval=%d, want 88", s.Interval) + } +} + +// TestAgainStepsBackGently proves a lapse resets to a 1-day interval and counts +// a lapse, but only nudges ease down (never below the floor) — no harsh wipe. +func TestAgainStepsBackGently(t *testing.T) { + s := State{Reps: 4, Interval: 35, Ease: startEase} + s = s.next(GradeAgain) + if s.Interval != 1 { + t.Fatalf("again interval=%d, want 1", s.Interval) + } + if s.Reps != 0 { + t.Fatalf("again reps=%d, want 0", s.Reps) + } + if s.Lapses != 1 { + t.Fatalf("again lapses=%d, want 1", s.Lapses) + } + if s.Ease != startEase+easeAgainDelta { + t.Fatalf("again ease=%v, want %v", s.Ease, startEase+easeAgainDelta) + } + + // Ease never drops below the floor no matter how many lapses. + low := State{Ease: minEase} + for i := 0; i < 5; i++ { + low = low.next(GradeAgain) + } + if low.Ease < minEase { + t.Fatalf("ease fell below floor: %v", low.Ease) + } +} + +// TestEasyAdvancesFurther proves "easy" both bumps ease and lands a longer +// interval than a plain "good" at the same rung. +func TestEasyAdvancesFurther(t *testing.T) { + base := State{Reps: 2, Interval: 7, Ease: startEase} + good := base.next(GradeGood) + easy := base.next(GradeEasy) + if easy.Interval <= good.Interval { + t.Fatalf("easy interval %d should exceed good interval %d", easy.Interval, good.Interval) + } + if easy.Ease <= startEase { + t.Fatalf("easy should raise ease, got %v", easy.Ease) + } +} diff --git a/web/src/App.tsx b/web/src/App.tsx index 9e43da5..d66b588 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -9,6 +9,7 @@ import { EditorCore, type EditorChange } from './components/Editor/EditorCore' import { ToneSelect } from './components/Editor/ToneSelect' import { ExportMenu } from './components/Export/ExportMenu' import { HistoryPanel } from './components/History/HistoryPanel' +import { GardenPanel } from './components/Garden/GardenPanel' import { StatusBar } from './components/StatusBar/StatusBar' import { PetalCompanion } from './components/Companion/PetalCompanion' import { UpdateBanner } from './components/UpdateBanner/UpdateBanner' @@ -46,6 +47,7 @@ export default function App() { // editor to remount with the restored content (its initialContent is read // only on mount). const [historyOpen, setHistoryOpen] = useState(false) + const [gardenOpen, setGardenOpen] = useState(false) const [editorEpoch, setEditorEpoch] = useState(0) // Live mirrors of the current doc's editable fields so the "discard blank @@ -70,9 +72,11 @@ export default function App() { suggestions, checking, voicing, + collocating, llmDown, schedule: scheduleCheckpoint, runVoice, + runCollocation, removeSuggestion, } = useCheckpoint(currentDoc?.id ?? null) // Browser-side spell checker — loads the en-US dictionary once per session. @@ -395,6 +399,23 @@ export default function App() { 🌸 Petal +
@@ -471,6 +492,8 @@ export default function App() { onDismiss={handleDismiss} onVoiceCheck={runVoice} voicing={voicing} + onCollocationCheck={runCollocation} + collocating={collocating} onFocusMode={() => setFocusMode(true)} spellChecker={spellChecker} onAddWord={addWord} @@ -484,6 +507,7 @@ export default function App() { saveStatus={status} checking={checking} voicing={voicing} + collocating={collocating} llmDown={llmDown} />
@@ -507,6 +531,16 @@ export default function App() { /> )} + {gardenOpen && ( + setGardenOpen(false)} + onOpenDoc={(id) => { + setGardenOpen(false) + void openDoc(id) + }} + /> + )} + {updateAvailable && }
diff --git a/web/src/api/client.ts b/web/src/api/client.ts index c376488..fafe656 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -76,7 +76,29 @@ export interface Gloss { gloss: string } -export type SuggestionType = 'grammar' | 'phrasing' | 'idiom' | 'clarity' | 'voice' +export type SuggestionType = 'grammar' | 'phrasing' | 'idiom' | 'clarity' | 'voice' | 'collocation' + +// One word in the vocabulary garden: a looked-up word with its gloss/phonetic, +// the sentence it was met in, and its spaced-repetition state. `reps` drives how +// "bloomed" its blossom looks; `due_at` decides when it next surfaces for review. +export interface VocabWord { + id: string + word: string + gloss: string + phonetic: string + example: string + doc_id: string | null + due_at: string + interval_days: number + ease: number + reps: number + lapses: number + last_reviewed: string | null + created_at: string +} + +// The self-assessment grades a flashcard review can record. +export type VocabGrade = 'again' | 'good' | 'easy' // A point-in-time snapshot of a document. List responses omit the heavy // content/content_text fields; they arrive only on getVersion (preview/restore). @@ -141,6 +163,10 @@ export const api = { // Voice-consistency pass: whole-document, explicit-action, slower. Returns the // unified pending set too. Rate-limited per document server-side. voiceDoc: (id: string) => req(`/docs/${id}/voice`, { method: 'POST' }), + // Collocation coach: whole-document, explicit-action pass flagging non-native + // word pairings ("do a decision" → "make a decision"). Returns the unified + // pending set too. Rate-limited per document server-side. + collocationDoc: (id: string) => req(`/docs/${id}/collocation`, { method: 'POST' }), // Pending suggestions for a doc, loaded when the editor opens it. listSuggestions: (id: string) => req(`/docs/${id}/suggestions`), acceptSuggestion: (id: string) => @@ -221,6 +247,23 @@ export const api = { unassignTag: (docId: string, tagId: string) => req(`/docs/${docId}/tags/${tagId}`, { method: 'DELETE' }), + // Vocabulary garden. recordVocab captures (or refreshes) a looked-up word — + // idempotent per word, fired automatically on lookup. listVocab is the whole + // garden; dueVocab is just the cards ready for review; reviewVocab grades one + // card and returns its rescheduled state; deleteVocab removes a word. + recordVocab: (body: { + word: string + gloss?: string + phonetic?: string + example?: string + doc_id?: string | null + }) => req('/vocab', { method: 'POST', body: JSON.stringify(body) }), + listVocab: () => req('/vocab'), + dueVocab: () => req('/vocab/due'), + reviewVocab: (id: string, grade: VocabGrade) => + req(`/vocab/${id}/review`, { method: 'POST', body: JSON.stringify({ grade }) }), + deleteVocab: (id: string) => req(`/vocab/${id}`, { method: 'DELETE' }), + // Current deployed build id — changes whenever a new frontend ships. The // app polls this to offer a refresh. Bypasses any cache so the answer is live. version: () => req<{ version: string }>('/version', { cache: 'no-store' }), diff --git a/web/src/components/Editor/EditorCore.tsx b/web/src/components/Editor/EditorCore.tsx index f28bb7e..89dbb53 100644 --- a/web/src/components/Editor/EditorCore.tsx +++ b/web/src/components/Editor/EditorCore.tsx @@ -53,6 +53,10 @@ interface Props { // it runs (drives the toolbar button's loading state). onVoiceCheck: () => void voicing: boolean + // Triggers the whole-document collocation coach; `collocating` is true while it + // runs (drives the toolbar button's loading state). + onCollocationCheck: () => void + collocating: boolean // Fired when the editor gains focus, so the app can enter distraction-free mode. onFocusMode?: () => void // Browser-side spell checker (null until the dictionary loads). Adding a word @@ -81,6 +85,33 @@ interface WordInfoState { left: number loading: boolean info: WordInfo | null + // Garden state: the captured word's id (null until the auto-capture returns or + // after it's removed) and whether it's currently in the garden. + vocabId: string | null + saved: boolean +} + +// sentenceAround pulls the sentence containing `word` out of a block of text, so +// a captured vocab word carries the context it was met in. Falls back to the +// whole (trimmed, length-capped) text when no sentence boundary is found. +function sentenceAround(text: string, wordStart: number): string { + const stops = /[.!?。！？\n]/ + let start = 0 + for (let i = wordStart - 1; i >= 0; i--) { + if (stops.test(text[i])) { + start = i + 1 + break + } + } + let end = text.length + for (let i = wordStart; i < text.length; i++) { + if (stops.test(text[i])) { + end = i + 1 + break + } + } + const s = text.slice(start, end).trim() + return s.length > 240 ? s.slice(0, 240).trim() + '…' : s } // A tiny CSS-only confetti burst played at an accept. Four palette-colored dots @@ -185,6 +216,8 @@ export function EditorCore({ onDismiss, onVoiceCheck, voicing, + onCollocationCheck, + collocating, onFocusMode, spellChecker, onAddWord, @@ -630,13 +663,33 @@ export function EditorCore({ closeCard() setMisspell(null) const token = ++wordReqRef.current - setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null }) + setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, vocabId: null, saved: false }) + // The sentence the word sits in, for review context in the garden. + const block = editor.state.doc.resolve(range.from).parent.textContent + const example = sentenceAround(block, Math.max(0, range.from - editor.state.doc.resolve(range.from).start())) api .lookupWord(range.word) .then((info) => { - if (token === wordReqRef.current) { - setWordInfo((w) => (w ? { ...w, loading: false, info } : null)) - } + if (token !== wordReqRef.current) return + setWordInfo((w) => (w ? { ...w, loading: false, info } : null)) + // Auto-capture into the vocabulary garden — only words the dictionary + // actually knows (a real gloss or definition), so accidental lookups of + // typos or proper nouns don't clutter the garden. Looking words up IS + // the data source; this costs the writer nothing. + const known = !!info.gloss || info.definitions.length > 0 + if (!known) return + api + .recordVocab({ + word: range.word, + gloss: info.gloss, + phonetic: info.phonetic, + example, + doc_id: docId, + }) + .then((row) => { + setWordInfo((w) => (w && w.word === range.word ? { ...w, vocabId: row.id, saved: true } : w)) + }) + .catch((err) => console.error('vocab capture failed', err)) }) .catch((err) => { console.error('word lookup failed', err) @@ -645,9 +698,31 @@ export function EditorCore({ } }) }, - [editor, closeCard], + [editor, closeCard, docId], ) + // Toggle a looked-up word in/out of the vocabulary garden from the WordCard + // heart. Auto-capture saves it on lookup; this lets the writer remove a word + // she already knows (or re-add one she removed by mistake). + const toggleSaveWord = useCallback(() => { + setWordInfo((w) => { + if (!w || !w.info) return w + if (w.saved && w.vocabId) { + const id = w.vocabId + api.deleteVocab(id).catch((err) => console.error('vocab remove failed', err)) + return { ...w, saved: false, vocabId: null } + } + const word = w.word + const block = editor?.state.doc.resolve(w.from) + const example = block ? sentenceAround(block.parent.textContent, Math.max(0, w.from - block.start())) : '' + api + .recordVocab({ word, gloss: w.info.gloss, phonetic: w.info.phonetic, example, doc_id: docId }) + .then((row) => setWordInfo((cur) => (cur && cur.word === word ? { ...cur, vocabId: row.id, saved: true } : cur))) + .catch((err) => console.error('vocab save failed', err)) + return { ...w, saved: true } + }) + }, [editor, docId]) + // 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( @@ -926,7 +1001,13 @@ export function EditorCore({ return (
- +
diff --git a/web/src/components/Editor/WordCard.tsx b/web/src/components/Editor/WordCard.tsx index e5ea094..995542a 100644 --- a/web/src/components/Editor/WordCard.tsx +++ b/web/src/components/Editor/WordCard.tsx @@ -11,11 +11,15 @@ interface Props { word: string info: WordInfo | null loading: boolean + // Whether the word is in the vocabulary garden (auto-saved on lookup). The + // heart toggles it; `onToggleSave` removes/re-adds it. + saved: boolean + onToggleSave: () => void style: React.CSSProperties onReplace: (synonym: string) => void } -export function WordCard({ word, info, loading, style, onReplace }: Props) { +export function WordCard({ word, info, loading, saved, onToggleSave, style, onReplace }: Props) { const definitions = info?.definitions ?? [] const synonyms = info?.synonyms ?? [] const gloss = info?.gloss ?? '' @@ -48,18 +52,35 @@ export function WordCard({ word, info, loading, style, onReplace }: Props) { {word} - {speechSupported() && ( - - )} +
+ {!empty && !loading && ( + + )} + {speechSupported() && ( + + )} +
{/* How to say it — the pronunciation aid for an English learner, paired diff --git a/web/src/components/Editor/suggestionMeta.ts b/web/src/components/Editor/suggestionMeta.ts index 10b02f7..f494a39 100644 --- a/web/src/components/Editor/suggestionMeta.ts +++ b/web/src/components/Editor/suggestionMeta.ts @@ -9,4 +9,5 @@ export const TYPE_META: Record idiom: { color: 'var(--color-lavender)', label: 'Idiom' }, clarity: { color: 'var(--color-sky)', label: 'Clarity' }, voice: { color: 'var(--color-honey)', label: 'Voice' }, + collocation: { color: 'var(--color-blossom)', label: 'Word pairing' }, } diff --git a/web/src/components/Garden/GardenPanel.tsx b/web/src/components/Garden/GardenPanel.tsx new file mode 100644 index 0000000..912ceae --- /dev/null +++ b/web/src/components/Garden/GardenPanel.tsx @@ -0,0 +1,492 @@ +import { useCallback, useEffect, useMemo, useState } from 'react' +import { api, type VocabGrade, type VocabWord } from '../../api/client' +import { speak, speechSupported } from '../../audio/speech' + +// GardenPanel is the vocabulary garden: every word the writer has looked up, +// grown into a blossom that opens further the more she remembers it, plus a +// gentle spaced-repetition review. Words are captured automatically on lookup +// (zero effort), so the garden fills itself as she writes. The sleepy kitten +// naps among the blossoms — the same companion gag, at rest in her little +// meadow. Bilingual, zh-first, to match Petal's chrome. + +interface Props { + onClose: () => void + // Open the document a word was met in (so "where did I see this?" is one tap). + onOpenDoc?: (docId: string) => void +} + +// blossom maps a word's successful-review count to how bloomed its flower looks: +// a fresh seedling opens into a full blossom as it's remembered. No wilting — a +// forgotten word just stops climbing, never shames. +function blossom(reps: number): string { + if (reps <= 0) return '🌱' + if (reps <= 2) return '🌿' + if (reps <= 4) return '🌷' + if (reps <= 6) return '🌸' + return '🌺' +} + +// blankOut hides the target word in its example sentence with a soft blank, so a +// flashcard can quiz recall in context. Whole-word, case-insensitive. +function blankOut(sentence: string, word: string): string { + if (!sentence) return '' + try { + const re = new RegExp(`\\b${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi') + return sentence.replace(re, '____') + } catch { + return sentence + } +} + +export function GardenPanel({ onClose, onOpenDoc }: Props) { + const [words, setWords] = useState(null) + const [due, setDue] = useState([]) + const [error, setError] = useState(false) + // Review session state: the queue (snapshot of due at start), a cursor, and + // whether the current card's answer is revealed. + const [queue, setQueue] = useState(null) + const [cursor, setCursor] = useState(0) + const [revealed, setRevealed] = useState(false) + const [expanded, setExpanded] = useState(null) + + const load = useCallback(async () => { + setError(false) + try { + const [all, dueNow] = await Promise.all([api.listVocab(), api.dueVocab()]) + setWords(all) + setDue(dueNow) + } catch { + setError(true) + } + }, []) + + useEffect(() => { + void load() + }, [load]) + + // Escape closes the panel (or ends a review session back to the garden). + useEffect(() => { + const onKey = (e: KeyboardEvent) => { + if (e.key === 'Escape') { + if (queue) setQueue(null) + else onClose() + } + } + window.addEventListener('keydown', onKey) + return () => window.removeEventListener('keydown', onKey) + }, [onClose, queue]) + + const startReview = useCallback(() => { + if (due.length === 0) return + setQueue(due) + setCursor(0) + setRevealed(false) + }, [due]) + + const grade = useCallback( + async (g: VocabGrade) => { + if (!queue) return + const card = queue[cursor] + if (card) { + try { + await api.reviewVocab(card.id, g) + } catch { + /* keep going — a failed grade just won't reschedule */ + } + } + const nextCursor = cursor + 1 + if (nextCursor >= queue.length) { + // Session done — refresh the garden and drop back to it. + setQueue(null) + void load() + } else { + setCursor(nextCursor) + setRevealed(false) + } + }, + [queue, cursor, load], + ) + + const removeWord = useCallback(async (id: string) => { + setWords((prev) => (prev ? prev.filter((w) => w.id !== id) : prev)) + setDue((prev) => prev.filter((w) => w.id !== id)) + try { + await api.deleteVocab(id) + } catch { + void load() + } + }, [load]) + + return ( +
+
+ + +
+ ) +} + +// --- garden grid ------------------------------------------------------------ + +function GardenView({ + words, + due, + error, + expanded, + onToggleExpand, + onStartReview, + onRemove, + onOpenDoc, + onRetry, +}: { + words: VocabWord[] | null + due: VocabWord[] + error: boolean + expanded: string | null + onToggleExpand: (id: string) => void + onStartReview: () => void + onRemove: (id: string) => void + onOpenDoc?: (docId: string) => void + onRetry: () => void +}) { + return ( + <> + {due.length > 0 && ( +
+ +
+ )} + +
+ {error ? ( +
+ Couldn’t load your garden just now. + +
+ ) : words === null ? ( +
+ Loading… +
+ ) : words.length === 0 ? ( +
+
🌱🐱💤
+

+ 你的花园还空着。
+ 右键点一个英文单词查它的意思——它就会在这里发芽。 +

+

+ Your garden is empty. Look up an English word (right-click it) and it’ll sprout here. +

+
+ ) : ( +
    + {words.map((w) => { + const open = expanded === w.id + const isDue = due.some((d) => d.id === w.id) + return ( +
  • + + + {open && ( +
    + {w.phonetic && /{w.phonetic}/} + {w.example && ( +

    + “{w.example}” +

    + )} +
    + 复习 {w.reps} 次 · seen {w.reps}× · 间隔 {w.interval_days}d +
    +
    + {speechSupported() && ( + + )} + {w.doc_id && onOpenDoc && ( + + )} + +
    +
    + )} +
    • + ) + })} +
+ )} +
+ + {words && words.length > 0 && ( +
+ 🐱💤 {words.length} 朵花在花园里 · {words.length} blossom{words.length > 1 ? 's' : ''} growing +
+ )} + + ) +} + +// --- flashcard review ------------------------------------------------------- + +function ReviewSession({ + queue, + cursor, + revealed, + onReveal, + onGrade, + onQuit, +}: { + queue: VocabWord[] + cursor: number + revealed: boolean + onReveal: () => void + onGrade: (g: VocabGrade) => void + onQuit: () => void +}) { + const card = queue[cursor] + // Alternate the quiz direction so she practices both recognition (see the + // English, recall the meaning) and production (see the meaning, recall the + // English word). Parity of the cursor keeps it deterministic within a session. + const production = cursor % 2 === 1 && !!card?.gloss + + const prompt = useMemo(() => { + if (!card) return '' + if (production) return card.gloss + return card.example ? blankOut(card.example, card.word) : card.word + }, [card, production]) + + if (!card) return null + + return ( +
+
+ + {cursor + 1} / {queue.length} + + +
+ + {/* The card */} +
+
+ {blossom(card.reps)} +
+
+ {prompt} +
+
+ {production ? '这个中文意思的英文单词是？· Which English word?' : '这个词什么意思？· What does this mean?'} +
+ + {revealed && ( +
+
+ {card.word} + {speechSupported() && ( + + )} +
+ {card.phonetic && ( +
+ /{card.phonetic}/ +
+ )} + {card.gloss && ( +
+ {card.gloss} +
+ )} + {card.example && ( +

+ “{card.example}” +

+ )} +
+ )} +
+ + {/* Controls */} +
+ {!revealed ? ( + + ) : ( +
+ onGrade('again')} /> + onGrade('good')} /> + onGrade('easy')} /> +
+ )} +
+
+ ) +} + +function GradeButton({ color, zh, en, onClick }: { color: string; zh: string; en: string; onClick: () => void }) { + return ( + + ) +} diff --git a/web/src/components/StatusBar/StatusBar.tsx b/web/src/components/StatusBar/StatusBar.tsx index 4c8f48f..d031ec4 100644 --- a/web/src/components/StatusBar/StatusBar.tsx +++ b/web/src/components/StatusBar/StatusBar.tsx @@ -12,6 +12,8 @@ interface Props { checking: boolean // True while a whole-document voice pass runs — shows a breathing honey dot. voicing: boolean + // True while a collocation pass runs — shows a breathing blossom dot. + collocating: 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 @@ -28,7 +30,7 @@ const SAVE_LABEL: Record = { // 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, llmDown }: Props) { +export function StatusBar({ wordCount, text, saveStatus, checking, voicing, collocating, llmDown }: Props) { const label = SAVE_LABEL[saveStatus] // The expanded stats panel toggles open when the word count is clicked. const [statsOpen, setStatsOpen] = useState(false) @@ -90,7 +92,19 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing, llmD )} - {llmDown && !checking && !voicing && ( + {collocating && ( + <> + · + + + Finding natural phrasing… + + + )} + {llmDown && !checking && !voicing && !collocating && ( <> · void voicing: boolean + // Runs the whole-document collocation coach; `collocating` shows its progress. + onCollocationCheck: () => void + collocating: boolean } // A formatting button. `active` gets the rose pill treatment so the writer can @@ -165,7 +168,7 @@ function Swatch({ // 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) { +export function Toolbar({ editor, onVoiceCheck, voicing, onCollocationCheck, collocating }: 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('') @@ -594,6 +597,28 @@ export function Toolbar({ editor, onVoiceCheck, voicing }: Props) { /> {voicing ? 'Reading…' : 'Check my voice 🍯'} + +
) } diff --git a/web/src/hooks/useCheckpoint.ts b/web/src/hooks/useCheckpoint.ts index d9a0750..0db7c0b 100644 --- a/web/src/hooks/useCheckpoint.ts +++ b/web/src/hooks/useCheckpoint.ts @@ -13,6 +13,8 @@ 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 while a whole-document collocation pass is in flight (explicit action). + const [collocating, setCollocating] = 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 @@ -89,6 +91,29 @@ export function useCheckpoint(docId: string | null) { } }, []) + // Run the collocation coach now (explicit "Make it sound natural" action). + // Like runVoice it returns the unified pending set, so grammar + voice + // highlights survive. Shares the run token so a late response is discarded. + const runCollocation = useCallback(async () => { + const id = docIdRef.current + if (!id) return + clearTimeout(retryRef.current) // a collocation pass supersedes a queued grammar retry + const run = ++runRef.current + setCollocating(true) + try { + const full = await api.collocationDoc(id) + if (run === runRef.current && id === docIdRef.current) { + setSuggestions(full) + setLlmDown(false) + } + } catch (err) { + console.error('collocation pass failed', err) + if (run === runRef.current) setLlmDown(true) + } finally { + if (run === runRef.current) setCollocating(false) + } + }, []) + // Call on every edit; schedules a check 4s after typing settles. const schedule = useCallback(() => { clearTimeout(debounceRef.current) @@ -105,6 +130,7 @@ export function useCheckpoint(docId: string | null) { setSuggestions([]) setChecking(false) setVoicing(false) + setCollocating(false) setLlmDown(false) if (!docId) return let cancelled = false @@ -134,5 +160,5 @@ export function useCheckpoint(docId: string | null) { setSuggestions((prev) => prev.filter((s) => s.id !== id)) }, []) - return { suggestions, checking, voicing, llmDown, schedule, runVoice, removeSuggestion } + return { suggestions, checking, voicing, collocating, llmDown, schedule, runVoice, runCollocation, removeSuggestion } } diff --git a/web/src/index.css b/web/src/index.css index a436d27..b9dd43d 100644 --- a/web/src/index.css +++ b/web/src/index.css @@ -20,6 +20,7 @@ --color-lavender: #C5B4E8; /* idiom */ --color-sky: #A8CCE8; /* clarity */ --color-honey: #CE9B4F; /* voice */ + --color-blossom: #E59ABF; /* collocation — warm blossom pink */ --color-success: #8FCFA8; /* saved / accepted */ /* Typography */ @@ -232,6 +233,7 @@ button, a, input { .petal-suggestion-idiom { border-bottom-color: var(--color-lavender); } .petal-suggestion-clarity { border-bottom-color: var(--color-sky); } .petal-suggestion-voice { border-bottom-color: var(--color-honey); } +.petal-suggestion-collocation { border-bottom-color: var(--color-blossom); } @keyframes petal-suggestion-in { from { opacity: 0; transform: translateY(4px); } From 4161830da6755fb8b0f84122403389c2440d5efa Mon Sep 17 00:00:00 2001 From: prosolis <5590409+prosolis@users.noreply.github.com> Date: Fri, 26 Jun 2026 16:41:28 -0700 Subject: [PATCH 2/3] Code-review fixes for collocation coach + vocab garden Correctness: - useCheckpoint: clear the busy flag unconditionally so overlapping explicit passes don't strand each other's spinner; explicit actions now also supersede a queued auto-check and clear the stranded "checking" dot. Deduped runVoice/runCollocation into runExplicitPass. - EditorCore: token-guard the auto-capture so a late capture can't resurrect a removed word; move toggleSaveWord side effects out of the setWordInfo updater (StrictMode double-fire); fix sentenceAround offset desync via shared exampleAt (textBetween + parentOffset, single resolve); optimistic saved state so the heart doesn't flash unsaved. - vocab capture: normalize word to lower+trim (matches lexicon) so "Apple"/"apple" don't make duplicate cards; check rows.Err() in queryList. - GardenPanel: Promise.allSettled so a /due failure doesn't blank the whole garden; scrim click during review ends the review (mirrors Esc); gate footer on !error; O(1) due lookup via a Set. Features requested in review: - Definition-only review card: add vocab_words.definition (migration 0007) as an English fallback meaning, threaded through capture and used by review/garden when there's no Chinese gloss. - Scheduler caps: maxEase 3.0 + maxInterval 365d so "easy" growth can't push a word out of rotation for years. Tests: TestCaptureCaseInsensitive, TestCaptureStoresDefinitionFallback, TestCapsBoundGrowth. go build/vet/test, tsc, vitest 51/51, vite build clean. Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd --- internal/db/db.go | 11 +++ internal/vocab/handlers.go | 41 +++++++---- internal/vocab/handlers_test.go | 42 +++++++++++ internal/vocab/scheduler.go | 21 +++++- internal/vocab/scheduler_test.go | 22 ++++++ web/src/api/client.ts | 2 + web/src/components/Editor/EditorCore.tsx | 74 +++++++++++++------ web/src/components/Garden/GardenPanel.tsx | 55 ++++++++++----- web/src/hooks/useCheckpoint.ts | 86 ++++++++++++----------- 9 files changed, 256 insertions(+), 98 deletions(-) diff --git a/internal/db/db.go b/internal/db/db.go index f2f171d..0efee02 100644 --- a/internal/db/db.go +++ b/internal/db/db.go @@ -325,6 +325,17 @@ CREATE TABLE vocab_words ( ); CREATE INDEX idx_vocab_due ON vocab_words(user_id, due_at); +`, + }, + { + // Vocabulary garden, follow-up. Some looked-up words have an English + // definition but no Chinese gloss; those produced an unanswerable review + // card (review reveals only the gloss). `definition` stores a short + // English sense captured at lookup as a fallback "meaning" so such words + // are still reviewable. + name: "0007_vocab_definition", + stmt: ` +ALTER TABLE vocab_words ADD COLUMN definition TEXT NOT NULL DEFAULT ''; `, }, } diff --git a/internal/vocab/handlers.go b/internal/vocab/handlers.go index 1dbc9c4..663490d 100644 --- a/internal/vocab/handlers.go +++ b/internal/vocab/handlers.go @@ -20,6 +20,7 @@ type Word struct { ID string `json:"id"` Word string `json:"word"` Gloss string `json:"gloss"` + Definition string `json:"definition"` // English fallback meaning when there's no Chinese gloss Phonetic string `json:"phonetic"` Example string `json:"example"` DocID *string `json:"doc_id"` @@ -51,7 +52,7 @@ func (h *Handler) Routes() chi.Router { return r } -const vocabColumns = `id, word, gloss, phonetic, example, doc_id, +const vocabColumns = `id, word, gloss, definition, phonetic, example, doc_id, due_at, interval_days, ease, reps, lapses, last_reviewed, created_at` func scanWord(s interface { @@ -59,7 +60,7 @@ func scanWord(s interface { }) (Word, error) { var w Word err := s.Scan( - &w.ID, &w.Word, &w.Gloss, &w.Phonetic, &w.Example, &w.DocID, + &w.ID, &w.Word, &w.Gloss, &w.Definition, &w.Phonetic, &w.Example, &w.DocID, &w.DueAt, &w.IntervalDays, &w.Ease, &w.Reps, &w.Lapses, &w.LastReviewed, &w.CreatedAt, ) return w, err @@ -93,15 +94,20 @@ func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) { } out = append(out, word) } + if err := rows.Err(); err != nil { + serverError(w, err) + return + } writeJSON(w, http.StatusOK, out) } type captureRequest struct { - Word string `json:"word"` - Gloss string `json:"gloss"` - Phonetic string `json:"phonetic"` - Example string `json:"example"` - DocID *string `json:"doc_id"` + Word string `json:"word"` + Gloss string `json:"gloss"` + Definition string `json:"definition"` + Phonetic string `json:"phonetic"` + Example string `json:"example"` + DocID *string `json:"doc_id"` } // capture records a looked-up word. It's an idempotent upsert keyed on the word: @@ -114,7 +120,11 @@ func (h *Handler) capture(w http.ResponseWriter, r *http.Request) { errorJSON(w, http.StatusBadRequest, "invalid body") return } - word := strings.TrimSpace(req.Word) + // Normalize the same way the lexicon does (internal/lexicon: lower+trim) so + // the UNIQUE(user_id, word) upsert is genuinely idempotent — otherwise + // "Apple" at a sentence start and "apple" mid-line would create two separate + // cards on independent schedules. + word := strings.ToLower(strings.TrimSpace(req.Word)) if word == "" { errorJSON(w, http.StatusBadRequest, "word is required") return @@ -124,14 +134,15 @@ func (h *Handler) capture(w http.ResponseWriter, r *http.Request) { // schedule (due_at/reps/interval/ease) alone so re-looking-up a word never // resets its progress. _, err := h.DB.Exec( - `INSERT INTO vocab_words (user_id, word, gloss, phonetic, example, doc_id, due_at, interval_days) - VALUES (?, ?, ?, ?, ?, ?, datetime('now', '+1 day'), 1) + `INSERT INTO vocab_words (user_id, word, gloss, definition, phonetic, example, doc_id, due_at, interval_days) + VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now', '+1 day'), 1) ON CONFLICT(user_id, word) DO UPDATE SET - gloss = excluded.gloss, - phonetic = excluded.phonetic, - example = CASE WHEN excluded.example != '' THEN excluded.example ELSE vocab_words.example END, - doc_id = COALESCE(excluded.doc_id, vocab_words.doc_id)`, - db.LocalUserID, word, req.Gloss, req.Phonetic, req.Example, req.DocID, + gloss = excluded.gloss, + definition = excluded.definition, + phonetic = excluded.phonetic, + example = CASE WHEN excluded.example != '' THEN excluded.example ELSE vocab_words.example END, + doc_id = COALESCE(excluded.doc_id, vocab_words.doc_id)`, + db.LocalUserID, word, req.Gloss, req.Definition, req.Phonetic, req.Example, req.DocID, ) if err != nil { serverError(w, err) diff --git a/internal/vocab/handlers_test.go b/internal/vocab/handlers_test.go index f4b542f..288005a 100644 --- a/internal/vocab/handlers_test.go +++ b/internal/vocab/handlers_test.go @@ -141,6 +141,48 @@ func TestCaptureValidation(t *testing.T) { } } +// TestCaptureStoresDefinitionFallback proves a word with an English definition +// but no Chinese gloss still round-trips its definition, so review has a meaning +// to reveal instead of a blank card. +func TestCaptureStoresDefinitionFallback(t *testing.T) { + srv, _ := newTestServer(t) + rec := do(t, srv, http.MethodPost, "/vocab", + `{"word":"ineffable","definition":"too great to be expressed in words"}`) + if rec.Code != http.StatusCreated { + t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body) + } + var w Word + _ = json.Unmarshal(rec.Body.Bytes(), &w) + if w.Gloss != "" { + t.Fatalf("expected no gloss, got %q", w.Gloss) + } + if w.Definition != "too great to be expressed in words" { + t.Fatalf("definition not stored, got %q", w.Definition) + } +} + +// TestCaptureCaseInsensitive proves "Apple" (sentence start) and "apple" +// (mid-line) land in the SAME garden card — capture normalizes to lower+trim +// like the lexicon, so the idempotent upsert isn't defeated by casing. +func TestCaptureCaseInsensitive(t *testing.T) { + srv, _ := newTestServer(t) + if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"Apple","gloss":"苹果"}`); rec.Code != http.StatusCreated { + t.Fatalf("capture Apple: code=%d body=%s", rec.Code, rec.Body) + } + if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":" apple ","gloss":"苹果"}`); rec.Code != http.StatusCreated { + t.Fatalf("capture apple: code=%d body=%s", rec.Code, rec.Body) + } + rec := do(t, srv, http.MethodGet, "/vocab", "") + var all []Word + _ = json.Unmarshal(rec.Body.Bytes(), &all) + if len(all) != 1 { + t.Fatalf("Apple/apple should be one card, got %d", len(all)) + } + if all[0].Word != "apple" { + t.Fatalf("word should be normalized to lowercase, got %q", all[0].Word) + } +} + // TestDocLinkSurvivesDocDelete proves the ON DELETE SET NULL keeps a word in the // garden when its source document is removed. func TestDocLinkSurvivesDocDelete(t *testing.T) { diff --git a/internal/vocab/scheduler.go b/internal/vocab/scheduler.go index d60dbb9..a5f7fc3 100644 --- a/internal/vocab/scheduler.go +++ b/internal/vocab/scheduler.go @@ -23,10 +23,17 @@ var ladder = []int{1, 3, 7, 16, 35} const ( minEase = 1.3 + maxEase = 3.0 // ease ceiling — keeps "easy" from compounding growth without bound startEase = 2.5 easyBonus = 1.3 // multiplier applied on top of a "good" step for "easy" easeAgainDelta = -0.20 // ease nudged down on a lapse (still floored at minEase) easeEasyDelta = 0.15 // ease nudged up when a card feels easy + + // maxInterval caps how far a card can drift into the future. Even a word + // graded "easy" many times resurfaces about once a year, so nothing silently + // leaves the garden forever (the whole point is to keep words in gentle + // rotation, not to retire them). + maxInterval = 365 ) // State is the spaced-repetition state of one card. It mirrors the scheduling @@ -61,7 +68,7 @@ func (s State) next(grade Grade) State { reps := s.Reps + 1 return State{ Reps: reps, - Interval: int(math.Round(float64(goodInterval(reps, s.Interval, ease)) * easyBonus)), + Interval: clampInterval(int(math.Round(float64(goodInterval(reps, s.Interval, ease)) * easyBonus))), Ease: ease, Lapses: s.Lapses, } @@ -69,7 +76,7 @@ func (s State) next(grade Grade) State { reps := s.Reps + 1 return State{ Reps: reps, - Interval: goodInterval(reps, s.Interval, ease), + Interval: clampInterval(goodInterval(reps, s.Interval, ease)), Ease: ease, Lapses: s.Lapses, } @@ -93,5 +100,15 @@ func clampEase(e float64) float64 { if e < minEase { return minEase } + if e > maxEase { + return maxEase + } return e } + +func clampInterval(d int) int { + if d > maxInterval { + return maxInterval + } + return d +} diff --git a/internal/vocab/scheduler_test.go b/internal/vocab/scheduler_test.go index 2dc2a68..8040e4b 100644 --- a/internal/vocab/scheduler_test.go +++ b/internal/vocab/scheduler_test.go @@ -51,6 +51,28 @@ func TestAgainStepsBackGently(t *testing.T) { } } +// TestCapsBoundGrowth proves runaway "easy" grading can't push ease or the +// interval past their ceilings, so a word always resurfaces within a year. +func TestCapsBoundGrowth(t *testing.T) { + s := State{Ease: startEase} + for i := 0; i < 40; i++ { + s = s.next(GradeEasy) + if s.Ease > maxEase { + t.Fatalf("step %d: ease %v exceeded cap %v", i, s.Ease, maxEase) + } + if s.Interval > maxInterval { + t.Fatalf("step %d: interval %d exceeded cap %d", i, s.Interval, maxInterval) + } + } + // After enough "easy" reviews it should be pinned at the ceilings. + if s.Interval != maxInterval { + t.Fatalf("interval should saturate at %d, got %d", maxInterval, s.Interval) + } + if s.Ease != maxEase { + t.Fatalf("ease should saturate at %v, got %v", maxEase, s.Ease) + } +} + // TestEasyAdvancesFurther proves "easy" both bumps ease and lands a longer // interval than a plain "good" at the same rung. func TestEasyAdvancesFurther(t *testing.T) { diff --git a/web/src/api/client.ts b/web/src/api/client.ts index fafe656..1edc086 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -85,6 +85,7 @@ export interface VocabWord { id: string word: string gloss: string + definition: string // English fallback meaning shown in review when there's no gloss phonetic: string example: string doc_id: string | null @@ -254,6 +255,7 @@ export const api = { recordVocab: (body: { word: string gloss?: string + definition?: string phonetic?: string example?: string doc_id?: string | null diff --git a/web/src/components/Editor/EditorCore.tsx b/web/src/components/Editor/EditorCore.tsx index 89dbb53..cdb4f4a 100644 --- a/web/src/components/Editor/EditorCore.tsx +++ b/web/src/components/Editor/EditorCore.tsx @@ -640,6 +640,20 @@ export function EditorCore({ setMisspell(null) }, [misspell, onAddWord]) + // exampleAt pulls the sentence containing the position out of its block, for + // review context in the garden. textBetween with a single-char leaf/break + // placeholder keeps the string indices aligned with ProseMirror's parentOffset + // (so a hard break or inline atom before the word doesn't desync the slice). + const exampleAt = useCallback( + (pos: number): string => { + if (!editor) return '' + const $pos = editor.state.doc.resolve(pos) + const text = $pos.parent.textBetween(0, $pos.parent.content.size, '\n', ' ') + return sentenceAround(text, Math.max(0, $pos.parentOffset)) + }, + [editor], + ) + // 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. @@ -665,28 +679,35 @@ export function EditorCore({ const token = ++wordReqRef.current setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, vocabId: null, saved: false }) // The sentence the word sits in, for review context in the garden. - const block = editor.state.doc.resolve(range.from).parent.textContent - const example = sentenceAround(block, Math.max(0, range.from - editor.state.doc.resolve(range.from).start())) + const example = exampleAt(range.from) api .lookupWord(range.word) .then((info) => { if (token !== wordReqRef.current) return - setWordInfo((w) => (w ? { ...w, loading: false, info } : null)) // Auto-capture into the vocabulary garden — only words the dictionary // actually knows (a real gloss or definition), so accidental lookups of // typos or proper nouns don't clutter the garden. Looking words up IS // the data source; this costs the writer nothing. const known = !!info.gloss || info.definitions.length > 0 + // Reflect the saved state optimistically so the heart shows 💚 the + // moment a known word loads, rather than flashing 🤍 until the capture + // round-trips. vocabId is filled in when recordVocab returns. + setWordInfo((w) => (w ? { ...w, loading: false, info, saved: known } : null)) if (!known) return api .recordVocab({ word: range.word, gloss: info.gloss, + definition: info.definitions[0]?.definition ?? '', phonetic: info.phonetic, example, doc_id: docId, }) .then((row) => { + // Discard a late capture if the card has since been superseded (a + // new lookup, navigation, or an explicit remove all bump the token), + // so it can't resurrect a word the writer just removed. + if (token !== wordReqRef.current) return setWordInfo((w) => (w && w.word === range.word ? { ...w, vocabId: row.id, saved: true } : w)) }) .catch((err) => console.error('vocab capture failed', err)) @@ -705,23 +726,36 @@ export function EditorCore({ // heart. Auto-capture saves it on lookup; this lets the writer remove a word // she already knows (or re-add one she removed by mistake). const toggleSaveWord = useCallback(() => { - setWordInfo((w) => { - if (!w || !w.info) return w - if (w.saved && w.vocabId) { - const id = w.vocabId - api.deleteVocab(id).catch((err) => console.error('vocab remove failed', err)) - return { ...w, saved: false, vocabId: null } - } - const word = w.word - const block = editor?.state.doc.resolve(w.from) - const example = block ? sentenceAround(block.parent.textContent, Math.max(0, w.from - block.start())) : '' - api - .recordVocab({ word, gloss: w.info.gloss, phonetic: w.info.phonetic, example, doc_id: docId }) - .then((row) => setWordInfo((cur) => (cur && cur.word === word ? { ...cur, vocabId: row.id, saved: true } : cur))) - .catch((err) => console.error('vocab save failed', err)) - return { ...w, saved: true } - }) - }, [editor, docId]) + // Read the current card and do the network side effects OUTSIDE the state + // updater — an updater must be pure (React StrictMode double-invokes it, + // which would otherwise fire each request twice). + const w = wordInfo + if (!w || !w.info) return + if (w.vocabId) { + // Already in the garden — remove it, and invalidate any in-flight capture + // for this card so a late auto-capture can't resurrect the removed word. + const id = w.vocabId + wordReqRef.current++ + setWordInfo((cur) => (cur ? { ...cur, saved: false, vocabId: null } : cur)) + api.deleteVocab(id).catch((err) => console.error('vocab remove failed', err)) + return + } + // Not in the garden yet — save it (idempotent upsert keyed on the word). + const word = w.word + const example = exampleAt(w.from) + setWordInfo((cur) => (cur ? { ...cur, saved: true } : cur)) + api + .recordVocab({ + word, + gloss: w.info.gloss, + definition: w.info.definitions[0]?.definition ?? '', + phonetic: w.info.phonetic, + example, + doc_id: docId, + }) + .then((row) => setWordInfo((cur) => (cur && cur.word === word ? { ...cur, vocabId: row.id, saved: true } : cur))) + .catch((err) => console.error('vocab save failed', err)) + }, [wordInfo, exampleAt, docId]) // 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). diff --git a/web/src/components/Garden/GardenPanel.tsx b/web/src/components/Garden/GardenPanel.tsx index 912ceae..d801129 100644 --- a/web/src/components/Garden/GardenPanel.tsx +++ b/web/src/components/Garden/GardenPanel.tsx @@ -51,13 +51,14 @@ export function GardenPanel({ onClose, onOpenDoc }: Props) { const load = useCallback(async () => { setError(false) - try { - const [all, dueNow] = await Promise.all([api.listVocab(), api.dueVocab()]) - setWords(all) - setDue(dueNow) - } catch { - setError(true) - } + // Settle the two requests independently: a failed /due shouldn't blank the + // whole garden when the word list loaded fine. Only listVocab failing is a + // true error state; a dueVocab failure just hides the review button. + const [allRes, dueRes] = await Promise.allSettled([api.listVocab(), api.dueVocab()]) + if (allRes.status === 'fulfilled') setWords(allRes.value) + else setError(true) + if (dueRes.status === 'fulfilled') setDue(dueRes.value) + else setDue([]) }, []) useEffect(() => { @@ -119,7 +120,11 @@ export function GardenPanel({ onClose, onOpenDoc }: Props) { return (
-
+
(queue ? setQueue(null) : onClose())} + />
- {words && words.length > 0 && ( + {!error && words && words.length > 0 && (
void }) { const card = queue[cursor] + // The meaning shown/asked is the Chinese gloss, or the English definition when + // a word has no gloss — so definition-only words are still reviewable. + const meaning = card?.gloss || card?.definition || '' // Alternate the quiz direction so she practices both recognition (see the // English, recall the meaning) and production (see the meaning, recall the // English word). Parity of the cursor keeps it deterministic within a session. - const production = cursor % 2 === 1 && !!card?.gloss + const production = cursor % 2 === 1 && !!meaning const prompt = useMemo(() => { if (!card) return '' - if (production) return card.gloss + if (production) return meaning return card.example ? blankOut(card.example, card.word) : card.word - }, [card, production]) + }, [card, production, meaning]) if (!card) return null @@ -432,15 +445,19 @@ function ReviewSession({ /{card.phonetic}/
)} - {card.gloss && ( + {meaning && (
- {card.gloss} + {meaning}
)} {card.example && ( diff --git a/web/src/hooks/useCheckpoint.ts b/web/src/hooks/useCheckpoint.ts index 0db7c0b..c2e97a9 100644 --- a/web/src/hooks/useCheckpoint.ts +++ b/web/src/hooks/useCheckpoint.ts @@ -68,51 +68,53 @@ export function useCheckpoint(docId: string | null) { } }, []) - // Run the voice-consistency pass now (explicit "Check my voice" action). Like - // runCheck it returns the unified pending set, so grammar highlights survive. - // Shares the run token so navigating away discards a late voice response. - 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) + // runExplicitPass drives a whole-document, explicit-action pass (voice, + // collocation): it returns the unified pending set, so the other families' + // highlights survive, and shares the run token so navigating away discards a + // late response. It supersedes any queued grammar retry AND clears the + // checkpoint's "checking" state, so the breathing rose dot can't linger on + // after the retry timer it would have cleared is cancelled here. + const runExplicitPass = useCallback( + async (call: (id: string) => Promise, setBusy: (b: boolean) => void, label: string) => { + const id = docIdRef.current + if (!id) return + // An explicit action fully supersedes a queued auto-check and grammar + // retry, and takes over the indicator — clear the stranded "checking" dot. + clearTimeout(debounceRef.current) + clearTimeout(retryRef.current) + setChecking(false) + const run = ++runRef.current + setBusy(true) + try { + const full = await call(id) + if (run === runRef.current && id === docIdRef.current) { + setSuggestions(full) + setLlmDown(false) + } + } catch (err) { + console.error(`${label} failed`, err) + if (run === runRef.current) setLlmDown(true) + } finally { + // setBusy is THIS invocation's own flag (a newer run sets its own), so + // clear it unconditionally — otherwise an overlapping pass that bumped + // the run token would strand this spinner on "Reading…" forever. + setBusy(false) } - } catch (err) { - console.error('voice pass failed', err) - if (run === runRef.current) setLlmDown(true) - } finally { - if (run === runRef.current) setVoicing(false) - } - }, []) + }, + [], + ) + + // Run the voice-consistency pass now (explicit "Check my voice" action). + const runVoice = useCallback( + () => runExplicitPass(api.voiceDoc, setVoicing, 'voice pass'), + [runExplicitPass], + ) // Run the collocation coach now (explicit "Make it sound natural" action). - // Like runVoice it returns the unified pending set, so grammar + voice - // highlights survive. Shares the run token so a late response is discarded. - const runCollocation = useCallback(async () => { - const id = docIdRef.current - if (!id) return - clearTimeout(retryRef.current) // a collocation pass supersedes a queued grammar retry - const run = ++runRef.current - setCollocating(true) - try { - const full = await api.collocationDoc(id) - if (run === runRef.current && id === docIdRef.current) { - setSuggestions(full) - setLlmDown(false) - } - } catch (err) { - console.error('collocation pass failed', err) - if (run === runRef.current) setLlmDown(true) - } finally { - if (run === runRef.current) setCollocating(false) - } - }, []) + const runCollocation = useCallback( + () => runExplicitPass(api.collocationDoc, setCollocating, 'collocation pass'), + [runExplicitPass], + ) // Call on every edit; schedules a check 4s after typing settles. const schedule = useCallback(() => { From 8c6bc1604b08ea5fe13ba59e1152336bc17a2015 Mon Sep 17 00:00:00 2001 From: prosolis <5590409+prosolis@users.noreply.github.com> Date: Fri, 26 Jun 2026 16:59:23 -0700 Subject: [PATCH 3/3] Code-review follow-ups: httputil, validation caps, a11y Backend: - Extract shared internal/httputil (WriteJSON/ErrorJSON/BadRequest/ ServerError); drop the triple-duplicated helpers in docs, suggestions, vocab. ServerError now logs the real error and returns a generic 500 so raw DB/internal errors never reach the client. - vocab capture: validate doc_id ownership (blank -> none, unknown -> 400 instead of a leaked FK 500); rune-safe clamp word/gloss/definition/ phonetic/example. - vocab review(): wrap the read-modify-write in a transaction (TOCTOU). - /api request-size cap via MaxBytesReader middleware (2 MiB), exempting /api/images (own 10 MiB limit). Frontend: - StatusBar: drive the checking/voicing/collocating indicators from one array; llmDown uses !anyBusy. - Slide-overs: new useFocusTrap hook (focus-in, Tab trap, focus-restore) on GardenPanel + HistoryPanel, both role=dialog/aria-modal/aria-label. - speech.ts: export stopSpeech(); GardenPanel cancels audio on unmount. Tests: add doc_id-validation and field-clamp coverage; full suite green. Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd --- cmd/server/main.go | 31 +++++ internal/docs/export.go | 19 +-- internal/docs/handlers.go | 50 ++++---- internal/docs/search.go | 19 +-- internal/docs/tags.go | 25 ++-- internal/docs/versions.go | 35 +++--- internal/httputil/json.go | 37 ++++++ internal/suggestions/chat.go | 15 +-- internal/suggestions/handlers.go | 44 +++---- internal/suggestions/rewrite.go | 15 +-- internal/suggestions/translate.go | 11 +- internal/vocab/handlers.go | 127 ++++++++++++++------ internal/vocab/handlers_test.go | 37 ++++++ web/src/audio/speech.ts | 9 +- web/src/components/Garden/GardenPanel.tsx | 14 ++- web/src/components/History/HistoryPanel.tsx | 7 ++ web/src/components/StatusBar/StatusBar.tsx | 86 +++++++------ web/src/hooks/useFocusTrap.ts | 59 +++++++++ 18 files changed, 436 insertions(+), 204 deletions(-) create mode 100644 internal/httputil/json.go create mode 100644 web/src/hooks/useFocusTrap.ts diff --git a/cmd/server/main.go b/cmd/server/main.go index c4ff306..fcf75b5 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -48,6 +48,11 @@ func main() { log.Printf("frontend build version %s", version) r.Route("/api", func(api chi.Router) { + // Cap request bodies so a runaway or hostile client can't stream an + // unbounded payload into a JSON decoder. Image uploads carry their own + // (larger) limit inside the images handler, so they're exempt here. + api.Use(limitBody(maxAPIBodyBytes, "/api/images")) + api.Get("/health", func(w http.ResponseWriter, _ *http.Request) { w.Header().Set("Content-Type", "application/json") _, _ = w.Write([]byte(`{"status":"ok"}`)) @@ -114,6 +119,32 @@ func main() { } } +// maxAPIBodyBytes caps a JSON API request body at 2 MiB. That's far above any +// real document save (the body is text plus lightweight marks; images upload +// separately by reference) while still bounding abuse. Exceeding it makes the +// handler's json.Decode fail, which surfaces as a 400. +const maxAPIBodyBytes = 2 << 20 + +// limitBody wraps each request body in an http.MaxBytesReader so handlers can't +// be made to read an unbounded payload. Paths under any of exemptPrefixes are +// left alone (e.g. image uploads, which set their own, larger limit). +func limitBody(max int64, exemptPrefixes ...string) func(http.Handler) http.Handler { + return func(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + for _, p := range exemptPrefixes { + if strings.HasPrefix(r.URL.Path, p) { + next.ServeHTTP(w, r) + return + } + } + if r.Body != nil { + r.Body = http.MaxBytesReader(w, r.Body, max) + } + next.ServeHTTP(w, r) + }) + } +} + // buildVersion derives a short, stable identifier for the currently embedded // frontend by hashing dist/index.html. Vite stamps content-hashed asset names // into that file each build, so the digest is a reliable "did the deploy diff --git a/internal/docs/export.go b/internal/docs/export.go index a9c34e9..8eafdd9 100644 --- a/internal/docs/export.go +++ b/internal/docs/export.go @@ -14,6 +14,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // exportRoutes registers the download endpoints: one document @@ -48,7 +49,7 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) { db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer rows.Close() @@ -62,12 +63,12 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) { &doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText, &doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt, ); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } body, err := format.render(doc) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } base := sanitizeFilename(doc.Title) @@ -82,20 +83,20 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) { seen[key]++ f, err := zw.Create(name) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if _, err := f.Write(body); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } } if err := rows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if err := zw.Close(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -148,13 +149,13 @@ func (h *Handler) export(w http.ResponseWriter, r *http.Request) { return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } body, err := format.render(doc) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } diff --git a/internal/docs/handlers.go b/internal/docs/handlers.go index ab4bd81..a946460 100644 --- a/internal/docs/handlers.go +++ b/internal/docs/handlers.go @@ -13,6 +13,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // Handler holds the dependencies shared by every document route. @@ -62,7 +63,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) { db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer rows.Close() @@ -72,20 +73,20 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) { for rows.Next() { var d docSummary if err := rows.Scan(&d.ID, &d.Title, &d.WordCount, &d.UpdatedAt); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } out = append(out, d) ids = append(ids, d.ID) } if err := rows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } byDoc, err := h.tagsByDoc(ids) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } for i := range out { @@ -94,7 +95,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) { out[i].Tags = []db.Tag{} } } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } // create inserts a fresh blank document and returns it in full. @@ -109,10 +110,10 @@ func (h *Handler) create(w http.ResponseWriter, r *http.Request) { &doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusCreated, doc) + httputil.WriteJSON(w, http.StatusCreated, doc) } // get returns a single full document by id. @@ -123,10 +124,10 @@ func (h *Handler) get(w http.ResponseWriter, r *http.Request) { return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, doc) + httputil.WriteJSON(w, http.StatusOK, doc) } // updateRequest is the auto-save payload. Every field is optional (a pointer) so @@ -163,7 +164,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) { req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, id, db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { @@ -173,7 +174,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) { doc, err := h.fetch(id) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -186,7 +187,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) { } } - writeJSON(w, http.StatusOK, doc) + httputil.WriteJSON(w, http.StatusOK, doc) } // delete removes a document (suggestions cascade via the FK). @@ -196,7 +197,7 @@ func (h *Handler) delete(w http.ResponseWriter, r *http.Request) { chi.URLParam(r, "id"), db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { @@ -222,21 +223,12 @@ func (h *Handler) fetch(id string) (db.Document, error) { } // --- small response helpers ------------------------------------------------- +// +// The generic JSON/error helpers live in internal/httputil; these are the +// document-specific shorthands that carry domain wording. -func writeJSON(w http.ResponseWriter, status int, v any) { - w.Header().Set("Content-Type", "application/json") - w.WriteHeader(status) - _ = json.NewEncoder(w).Encode(v) +func badRequest(w http.ResponseWriter, msg string) { httputil.BadRequest(w, msg) } +func notFound(w http.ResponseWriter) { + httputil.ErrorJSON(w, http.StatusNotFound, "document not found") } - -func errorJSON(w http.ResponseWriter, status int, msg string) { - writeJSON(w, status, map[string]string{"error": msg}) -} - -func serverError(w http.ResponseWriter, err error) { - errorJSON(w, http.StatusInternalServerError, 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) } +func notFoundMsg(w http.ResponseWriter, msg string) { httputil.ErrorJSON(w, http.StatusNotFound, msg) } diff --git a/internal/docs/search.go b/internal/docs/search.go index 1663222..c928086 100644 --- a/internal/docs/search.go +++ b/internal/docs/search.go @@ -8,6 +8,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // Search snippet shaping. @@ -57,7 +58,7 @@ func (h *Handler) SearchRoutes() chi.Router { 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{}) + httputil.WriteJSON(w, http.StatusOK, []searchResult{}) return } @@ -82,20 +83,20 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) { phrase, db.LocalUserID, maxSearchResults, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer sqlRows.Close() for sqlRows.Next() { var rw row if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } rows = append(rows, rw) } if err := sqlRows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } } else { @@ -112,20 +113,20 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) { db.LocalUserID, like, like, maxSearchResults, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer sqlRows.Close() for sqlRows.Next() { var rw row if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } rows = append(rows, rw) } if err := sqlRows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } } @@ -145,7 +146,7 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) { byDoc, err := h.tagsByDoc(ids) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } for i := range out { @@ -154,7 +155,7 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) { out[i].Tags = []db.Tag{} } } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } // escapeLike escapes the LIKE metacharacters (% and _) and the escape character diff --git a/internal/docs/tags.go b/internal/docs/tags.go index 15df7ef..f87b4f8 100644 --- a/internal/docs/tags.go +++ b/internal/docs/tags.go @@ -8,6 +8,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // validTagColors is the palette a tag may use, mirrored from the design tokens. @@ -57,7 +58,7 @@ func (h *Handler) listTags(w http.ResponseWriter, r *http.Request) { db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer rows.Close() @@ -66,16 +67,16 @@ func (h *Handler) listTags(w http.ResponseWriter, r *http.Request) { for rows.Next() { var t db.Tag if err := rows.Scan(&t.ID, &t.Name, &t.Color, &t.DocCount); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } out = append(out, t) } if err := rows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } type tagRequest struct { @@ -106,10 +107,10 @@ func (h *Handler) createTag(w http.ResponseWriter, r *http.Request) { db.LocalUserID, name, normalizeColor(req.Color), ).Scan(&t.ID, &t.Name, &t.Color) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusCreated, t) + httputil.WriteJSON(w, http.StatusCreated, t) } // updateTag renames and/or recolors a tag. Both fields optional via pointers so @@ -147,7 +148,7 @@ func (h *Handler) updateTag(w http.ResponseWriter, r *http.Request) { namePtr, colorPtr, id, db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { @@ -160,10 +161,10 @@ func (h *Handler) updateTag(w http.ResponseWriter, r *http.Request) { `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) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, t) + httputil.WriteJSON(w, http.StatusOK, t) } // deleteTag removes a tag; its document assignments cascade away via the FK. @@ -173,7 +174,7 @@ func (h *Handler) deleteTag(w http.ResponseWriter, r *http.Request) { chi.URLParam(r, "id"), db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { @@ -216,7 +217,7 @@ func (h *Handler) assignTag(w http.ResponseWriter, r *http.Request) { ON CONFLICT(doc_id, tag_id) DO NOTHING`, docID, req.TagID, ); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } w.WriteHeader(http.StatusNoContent) @@ -235,7 +236,7 @@ func (h *Handler) unassignTag(w http.ResponseWriter, r *http.Request) { `DELETE FROM document_tags WHERE doc_id = ? AND tag_id = ?`, docID, tagID, ); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } w.WriteHeader(http.StatusNoContent) diff --git a/internal/docs/versions.go b/internal/docs/versions.go index c0cc315..0290c0e 100644 --- a/internal/docs/versions.go +++ b/internal/docs/versions.go @@ -9,6 +9,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // Version-history tuning. @@ -29,8 +30,8 @@ const ( // 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", 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) } @@ -50,7 +51,7 @@ func (h *Handler) listVersions(w http.ResponseWriter, r *http.Request) { docID, db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer rows.Close() @@ -59,16 +60,16 @@ func (h *Handler) listVersions(w http.ResponseWriter, r *http.Request) { 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) + httputil.ServerError(w, err) return } out = append(out, v) } if err := rows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } // getVersion returns one snapshot in full (including content) for preview. @@ -79,10 +80,10 @@ func (h *Handler) getVersion(w http.ResponseWriter, r *http.Request) { return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, v) + httputil.WriteJSON(w, http.StatusOK, v) } // createVersion takes an explicit, user-requested ('manual') restore point from @@ -96,16 +97,16 @@ func (h *Handler) createVersion(w http.ResponseWriter, r *http.Request) { return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } v, err := h.insertVersion(doc, db.VersionKindManual) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusCreated, v) + httputil.WriteJSON(w, http.StatusCreated, v) } // restoreVersion copies a snapshot back onto the live document. Before @@ -121,17 +122,17 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) { return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } current, err := h.fetch(docID) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if _, err := h.insertVersion(current, db.VersionKindPreRestore); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -143,7 +144,7 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) { v.Title, v.Content, v.ContentText, v.WordCount, docID, db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { @@ -153,10 +154,10 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) { doc, err := h.fetch(docID) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, doc) + httputil.WriteJSON(w, http.StatusOK, doc) } // maybeAutoSnapshot records a throttled background snapshot of the just-saved diff --git a/internal/httputil/json.go b/internal/httputil/json.go new file mode 100644 index 0000000..006154a --- /dev/null +++ b/internal/httputil/json.go @@ -0,0 +1,37 @@ +// Package httputil holds the small HTTP response helpers shared by every API +// handler package (docs, suggestions, vocab, …). Keeping them in one place means +// JSON encoding and — crucially — error handling behave identically everywhere: +// internal errors are logged in full but never leaked to the client. +package httputil + +import ( + "encoding/json" + "log" + "net/http" +) + +// WriteJSON encodes v as the response body with the given status code. +func WriteJSON(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) +} + +// ErrorJSON sends a {"error": msg} body with the given status. The message is +// caller-chosen and safe to show the client. +func ErrorJSON(w http.ResponseWriter, status int, msg string) { + WriteJSON(w, status, map[string]string{"error": msg}) +} + +// BadRequest is the common 400 shorthand. +func BadRequest(w http.ResponseWriter, msg string) { + ErrorJSON(w, http.StatusBadRequest, msg) +} + +// ServerError logs the real error (with full detail, for the operator) and +// returns a generic 500 to the client — raw database/internal errors must never +// reach the browser, where they leak schema and implementation details. +func ServerError(w http.ResponseWriter, err error) { + log.Printf("internal error: %v", err) + ErrorJSON(w, http.StatusInternalServerError, "something went wrong") +} diff --git a/internal/suggestions/chat.go b/internal/suggestions/chat.go index 1f0c5ba..c992b68 100644 --- a/internal/suggestions/chat.go +++ b/internal/suggestions/chat.go @@ -10,6 +10,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" "gitea.parodia.dev/drwily/petal/internal/llm" ) @@ -29,7 +30,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) { var body chatRequest if err := json.NewDecoder(r.Body).Decode(&body); err != nil { - errorJSON(w, http.StatusBadRequest, "invalid request body") + httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body") return } @@ -37,8 +38,8 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) { // scoped to the local user so a stray id can't read another user's doc. var ( original, replacement, explanation, typ string - fromPos int - contentText string + fromPos int + contentText string ) err := h.DB.QueryRow( `SELECT s.original, s.replacement, s.explanation, s.type, s.from_pos, d.content_text @@ -48,11 +49,11 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) { sugID, db.LocalUserID, ).Scan(&original, &replacement, &explanation, &typ, &fromPos, &contentText) if errors.Is(err, sql.ErrNoRows) { - errorJSON(w, http.StatusNotFound, "suggestion not found") + httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found") return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -63,7 +64,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) { // Flush through; bail with a plain error if somehow they don't. flusher, ok := w.(http.Flusher) if !ok { - serverError(w, errors.New("streaming unsupported")) + httputil.ServerError(w, errors.New("streaming unsupported")) return } @@ -71,7 +72,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) { if err != nil { // The stream never opened (e.g. LLM unreachable) — a normal JSON error is // still appropriate since we haven't written SSE headers yet. - errorJSON(w, http.StatusBadGateway, "chat failed: "+err.Error()) + httputil.ErrorJSON(w, http.StatusBadGateway, "chat failed: "+err.Error()) return } diff --git a/internal/suggestions/handlers.go b/internal/suggestions/handlers.go index fd42139..5ad8c6e 100644 --- a/internal/suggestions/handlers.go +++ b/internal/suggestions/handlers.go @@ -8,7 +8,6 @@ package suggestions import ( "context" "database/sql" - "encoding/json" "errors" "net/http" "strings" @@ -16,6 +15,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" "gitea.parodia.dev/drwily/petal/internal/llm" ) @@ -99,17 +99,17 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R docID, db.LocalUserID, ).Scan(&contentText, &tone) if errors.Is(err, sql.ErrNoRows) { - errorJSON(w, http.StatusNotFound, "document not found") + httputil.ErrorJSON(w, http.StatusNotFound, "document not found") return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } // Nothing to analyze on an empty document — skip the LLM round-trip. if strings.TrimSpace(contentText) == "" { - writeJSON(w, http.StatusOK, []db.Suggestion{}) + httputil.WriteJSON(w, http.StatusOK, []db.Suggestion{}) return } @@ -119,10 +119,10 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R // error, so the frontend keeps showing current suggestions. existing, err := h.fetchPending(docID) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, existing) + httputil.WriteJSON(w, http.StatusOK, existing) return } @@ -132,12 +132,12 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R // 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()) + httputil.ErrorJSON(w, http.StatusBadGateway, "llm pass failed: "+err.Error()) return } if err := h.replacePending(docID, contentText, raw, scope); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -146,10 +146,10 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R // throttle path above stays consistent with the success path. out, err := h.fetchPending(docID) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } // pendingScope describes how one LLM pass touches the shared suggestions table: @@ -261,10 +261,10 @@ func suggestionKey(original, replacement string) string { func (h *Handler) listForDoc(w http.ResponseWriter, r *http.Request) { out, err := h.fetchPending(chi.URLParam(r, "id")) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } func (h *Handler) fetchPending(docID string) ([]db.Suggestion, error) { @@ -310,11 +310,11 @@ func (h *Handler) setStatus(w http.ResponseWriter, r *http.Request, status strin status, chi.URLParam(r, "id"), db.SuggestionStatusPending, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { - errorJSON(w, http.StatusNotFound, "pending suggestion not found") + httputil.ErrorJSON(w, http.StatusNotFound, "pending suggestion not found") return } w.WriteHeader(http.StatusNoContent) @@ -341,19 +341,3 @@ func normalizeType(t string) string { return db.SuggestionTypeGrammar } } - -// --- response helpers ------------------------------------------------------- - -func writeJSON(w http.ResponseWriter, status int, v any) { - w.Header().Set("Content-Type", "application/json") - w.WriteHeader(status) - _ = json.NewEncoder(w).Encode(v) -} - -func errorJSON(w http.ResponseWriter, status int, msg string) { - writeJSON(w, status, map[string]string{"error": msg}) -} - -func serverError(w http.ResponseWriter, err error) { - errorJSON(w, http.StatusInternalServerError, err.Error()) -} diff --git a/internal/suggestions/rewrite.go b/internal/suggestions/rewrite.go index 92da4de..55e2efa 100644 --- a/internal/suggestions/rewrite.go +++ b/internal/suggestions/rewrite.go @@ -10,6 +10,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" "gitea.parodia.dev/drwily/petal/internal/llm" ) @@ -36,17 +37,17 @@ func (h *Handler) rewrite(w http.ResponseWriter, r *http.Request) { var body rewriteRequest if err := json.NewDecoder(r.Body).Decode(&body); err != nil { - errorJSON(w, http.StatusBadRequest, "invalid request body") + httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body") return } text := strings.TrimSpace(body.Text) if text == "" { - errorJSON(w, http.StatusBadRequest, "no text to rewrite") + httputil.ErrorJSON(w, http.StatusBadRequest, "no text to rewrite") return } if len([]rune(text)) > llm.RewriteMaxRunes { - errorJSON(w, http.StatusBadRequest, "selection too long to rewrite") + httputil.ErrorJSON(w, http.StatusBadRequest, "selection too long to rewrite") return } @@ -58,19 +59,19 @@ func (h *Handler) rewrite(w http.ResponseWriter, r *http.Request) { docID, db.LocalUserID, ).Scan(&exists) if errors.Is(err, sql.ErrNoRows) { - errorJSON(w, http.StatusNotFound, "document not found") + httputil.ErrorJSON(w, http.StatusNotFound, "document not found") return } if err != nil { - serverError(w, err) + httputil.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()) + httputil.ErrorJSON(w, http.StatusBadGateway, "rewrite failed: "+err.Error()) return } - writeJSON(w, http.StatusOK, rewriteResponse{Rewrite: out}) + httputil.WriteJSON(w, http.StatusOK, rewriteResponse{Rewrite: out}) } diff --git a/internal/suggestions/translate.go b/internal/suggestions/translate.go index a7a7c74..5add0b0 100644 --- a/internal/suggestions/translate.go +++ b/internal/suggestions/translate.go @@ -9,6 +9,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" "gitea.parodia.dev/drwily/petal/internal/llm" ) @@ -33,25 +34,25 @@ func (h *Handler) translate(w http.ResponseWriter, r *http.Request) { sugID, db.LocalUserID, ).Scan(&explanation) if errors.Is(err, sql.ErrNoRows) { - errorJSON(w, http.StatusNotFound, "suggestion not found") + httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found") return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } explanation = strings.TrimSpace(explanation) if explanation == "" { - writeJSON(w, http.StatusOK, translateResponse{Translation: ""}) + httputil.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()) + httputil.ErrorJSON(w, http.StatusBadGateway, "translate failed: "+err.Error()) return } - writeJSON(w, http.StatusOK, translateResponse{Translation: out}) + httputil.WriteJSON(w, http.StatusOK, translateResponse{Translation: out}) } diff --git a/internal/vocab/handlers.go b/internal/vocab/handlers.go index 663490d..6ff2a70 100644 --- a/internal/vocab/handlers.go +++ b/internal/vocab/handlers.go @@ -12,6 +12,7 @@ import ( "github.com/go-chi/chi/v5" "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" ) // Word is one entry in the vocabulary garden: the looked-up word with its gloss, @@ -81,7 +82,7 @@ func (h *Handler) due(w http.ResponseWriter, _ *http.Request) { func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) { rows, err := h.DB.Query(query, args...) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } defer rows.Close() @@ -89,16 +90,16 @@ func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) { for rows.Next() { word, err := scanWord(rows) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } out = append(out, word) } if err := rows.Err(); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + httputil.WriteJSON(w, http.StatusOK, out) } type captureRequest struct { @@ -110,6 +111,28 @@ type captureRequest struct { DocID *string `json:"doc_id"` } +// Field-length caps. The captured fields come from the offline lexicon and the +// editor selection, not free-typed prose, so we clamp rather than reject — a +// lookup should never fail because a definition ran long. Counts are runes so a +// Chinese gloss isn't cut mid-character. The word is the upsert key, so an absurd +// "word" is bounded too. +const ( + maxWordLen = 128 + maxGlossLen = 512 + maxDefinitionLen = 4096 + maxPhoneticLen = 256 + maxExampleLen = 4096 +) + +// clamp trims s to at most max runes (rune-safe so multibyte glosses survive). +func clamp(s string, max int) string { + r := []rune(s) + if len(r) <= max { + return s + } + return string(r[:max]) +} + // capture records a looked-up word. It's an idempotent upsert keyed on the word: // a new word lands due tomorrow (interval 1 day); an existing word keeps its // schedule untouched but refreshes its gloss/phonetic/example/doc_id so the most @@ -117,18 +140,47 @@ type captureRequest struct { func (h *Handler) capture(w http.ResponseWriter, r *http.Request) { var req captureRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { - errorJSON(w, http.StatusBadRequest, "invalid body") + httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body") return } // Normalize the same way the lexicon does (internal/lexicon: lower+trim) so // the UNIQUE(user_id, word) upsert is genuinely idempotent — otherwise // "Apple" at a sentence start and "apple" mid-line would create two separate // cards on independent schedules. - word := strings.ToLower(strings.TrimSpace(req.Word)) + word := clamp(strings.ToLower(strings.TrimSpace(req.Word)), maxWordLen) if word == "" { - errorJSON(w, http.StatusBadRequest, "word is required") + httputil.ErrorJSON(w, http.StatusBadRequest, "word is required") return } + req.Gloss = clamp(req.Gloss, maxGlossLen) + req.Definition = clamp(req.Definition, maxDefinitionLen) + req.Phonetic = clamp(req.Phonetic, maxPhoneticLen) + req.Example = clamp(req.Example, maxExampleLen) + + // A blank doc_id is the same as none; otherwise the word must belong to a + // document the user actually owns. Without this check a stale or forged id + // would hit the foreign key and leak a raw "FOREIGN KEY constraint" 500 + // instead of a clean 400 (and, once auth lands, would let a word be attached + // to another user's document). + if req.DocID != nil { + if strings.TrimSpace(*req.DocID) == "" { + req.DocID = nil + } else { + var ok int + err := h.DB.QueryRow( + `SELECT 1 FROM documents WHERE id = ? AND user_id = ?`, + *req.DocID, db.LocalUserID, + ).Scan(&ok) + if errors.Is(err, sql.ErrNoRows) { + httputil.ErrorJSON(w, http.StatusBadRequest, "unknown doc_id") + return + } + if err != nil { + httputil.ServerError(w, err) + return + } + } + } // New rows start due tomorrow; ON CONFLICT refreshes context but leaves the // schedule (due_at/reps/interval/ease) alone so re-looking-up a word never @@ -145,16 +197,16 @@ func (h *Handler) capture(w http.ResponseWriter, r *http.Request) { db.LocalUserID, word, req.Gloss, req.Definition, req.Phonetic, req.Example, req.DocID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } out, err := h.fetch(word) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusCreated, out) + httputil.WriteJSON(w, http.StatusCreated, out) } // fetch loads one word row by its (user, word) key. @@ -175,25 +227,36 @@ func (h *Handler) review(w http.ResponseWriter, r *http.Request) { id := chi.URLParam(r, "id") var req reviewRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { - errorJSON(w, http.StatusBadRequest, "invalid body") + httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body") return } if req.Grade != GradeAgain && req.Grade != GradeGood && req.Grade != GradeEasy { - errorJSON(w, http.StatusBadRequest, "grade must be again, good, or easy") + httputil.ErrorJSON(w, http.StatusBadRequest, "grade must be again, good, or easy") return } + // The grade is computed in Go (the SM-2-lite scheduler), so the read and the + // write must be one atomic unit: a bare SELECT-then-UPDATE could interleave + // with a concurrent review of the same card and lose an update. Wrap both in a + // transaction. + tx, err := h.DB.Begin() + if err != nil { + httputil.ServerError(w, err) + return + } + defer tx.Rollback() // no-op once committed + var cur State - err := h.DB.QueryRow( + err = tx.QueryRow( `SELECT reps, interval_days, ease, lapses FROM vocab_words WHERE id = ? AND user_id = ?`, id, db.LocalUserID, ).Scan(&cur.Reps, &cur.Interval, &cur.Ease, &cur.Lapses) if errors.Is(err, sql.ErrNoRows) { - errorJSON(w, http.StatusNotFound, "word not found") + httputil.ErrorJSON(w, http.StatusNotFound, "word not found") return } if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } @@ -201,25 +264,29 @@ func (h *Handler) review(w http.ResponseWriter, r *http.Request) { // `datetime('now', '+N days')` keeps the stored value in SQLite's canonical // text format, matching CURRENT_TIMESTAMP and the due query's comparison. offset := "+" + strconv.Itoa(nxt.Interval) + " days" - if _, err := h.DB.Exec( + if _, err := tx.Exec( `UPDATE vocab_words SET reps = ?, interval_days = ?, ease = ?, lapses = ?, last_reviewed = datetime('now'), due_at = datetime('now', ?) WHERE id = ? AND user_id = ?`, nxt.Reps, nxt.Interval, nxt.Ease, nxt.Lapses, offset, id, db.LocalUserID, ); err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - out, err := scanWord(h.DB.QueryRow( + out, err := scanWord(tx.QueryRow( `SELECT `+vocabColumns+` FROM vocab_words WHERE id = ? AND user_id = ?`, id, db.LocalUserID, )) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } - writeJSON(w, http.StatusOK, out) + if err := tx.Commit(); err != nil { + httputil.ServerError(w, err) + return + } + httputil.WriteJSON(w, http.StatusOK, out) } // remove deletes a word from the garden (e.g. the writer already knows it). @@ -229,28 +296,12 @@ func (h *Handler) remove(w http.ResponseWriter, r *http.Request) { chi.URLParam(r, "id"), db.LocalUserID, ) if err != nil { - serverError(w, err) + httputil.ServerError(w, err) return } if n, _ := res.RowsAffected(); n == 0 { - errorJSON(w, http.StatusNotFound, "word not found") + httputil.ErrorJSON(w, http.StatusNotFound, "word not found") return } w.WriteHeader(http.StatusNoContent) } - -// --- response helpers ------------------------------------------------------- - -func writeJSON(w http.ResponseWriter, status int, v any) { - w.Header().Set("Content-Type", "application/json") - w.WriteHeader(status) - _ = json.NewEncoder(w).Encode(v) -} - -func errorJSON(w http.ResponseWriter, status int, msg string) { - writeJSON(w, status, map[string]string{"error": msg}) -} - -func serverError(w http.ResponseWriter, err error) { - errorJSON(w, http.StatusInternalServerError, err.Error()) -} diff --git a/internal/vocab/handlers_test.go b/internal/vocab/handlers_test.go index 288005a..7657841 100644 --- a/internal/vocab/handlers_test.go +++ b/internal/vocab/handlers_test.go @@ -6,6 +6,7 @@ import ( "net/http" "net/http/httptest" "path/filepath" + "strings" "testing" "github.com/go-chi/chi/v5" @@ -183,6 +184,42 @@ func TestCaptureCaseInsensitive(t *testing.T) { } } +// TestCaptureUnknownDocID rejects an unowned/stale doc_id with a clean 400 +// rather than letting it hit the foreign key and leak a raw 500. +func TestCaptureUnknownDocID(t *testing.T) { + srv, _ := newTestServer(t) + rec := do(t, srv, http.MethodPost, "/vocab", + `{"word":"quixotic","gloss":"不切实际的","doc_id":"does-not-exist"}`) + if rec.Code != http.StatusBadRequest { + t.Fatalf("unknown doc_id: want 400, got %d body=%s", rec.Code, rec.Body) + } + // A blank doc_id is treated as none, not an error. + if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"limpid","gloss":"清澈的","doc_id":""}`); rec.Code != http.StatusCreated { + t.Fatalf("blank doc_id should be accepted as none: code=%d body=%s", rec.Code, rec.Body) + } +} + +// TestCaptureClampsLongFields proves over-long fields are clamped (not rejected) +// so a lookup never fails on length, and the word key stays bounded. +func TestCaptureClampsLongFields(t *testing.T) { + srv, _ := newTestServer(t) + longWord := strings.Repeat("a", maxWordLen+50) + longDef := strings.Repeat("x", maxDefinitionLen+50) + rec := do(t, srv, http.MethodPost, "/vocab", + `{"word":"`+longWord+`","definition":"`+longDef+`"}`) + if rec.Code != http.StatusCreated { + t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body) + } + var w Word + _ = json.Unmarshal(rec.Body.Bytes(), &w) + if len([]rune(w.Word)) != maxWordLen { + t.Fatalf("word should clamp to %d runes, got %d", maxWordLen, len([]rune(w.Word))) + } + if len([]rune(w.Definition)) != maxDefinitionLen { + t.Fatalf("definition should clamp to %d runes, got %d", maxDefinitionLen, len([]rune(w.Definition))) + } +} + // TestDocLinkSurvivesDocDelete proves the ON DELETE SET NULL keeps a word in the // garden when its source document is removed. func TestDocLinkSurvivesDocDelete(t *testing.T) { diff --git a/web/src/audio/speech.ts b/web/src/audio/speech.ts index 3d7cda8..79a63b8 100644 --- a/web/src/audio/speech.ts +++ b/web/src/audio/speech.ts @@ -28,7 +28,12 @@ let current: { audio: HTMLAudioElement; url: string } | null = null // a newer tap can detect it's stale and bow out instead of double-playing. let requestSeq = 0 -function stopCurrent(): void { +// stopSpeech halts any read-aloud in flight — both the server-audio element and +// the Web Speech fallback — and bumps requestSeq so a fetch still in flight bows +// out instead of playing late. Exported so a panel can cancel audio on unmount, +// keeping a word's pronunciation from outliving the panel that started it. +export function stopSpeech(): void { + requestSeq++ if (current) { current.audio.pause() URL.revokeObjectURL(current.url) @@ -77,7 +82,7 @@ export function detectLang(text: string): string { // with no configured voice). export function speak(text: string, lang = detectLang(text)): void { if (!text.trim()) return - stopCurrent() + stopSpeech() const seq = ++requestSeq fetch('/api/tts', { diff --git a/web/src/components/Garden/GardenPanel.tsx b/web/src/components/Garden/GardenPanel.tsx index d801129..ec4c879 100644 --- a/web/src/components/Garden/GardenPanel.tsx +++ b/web/src/components/Garden/GardenPanel.tsx @@ -1,6 +1,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react' import { api, type VocabGrade, type VocabWord } from '../../api/client' -import { speak, speechSupported } from '../../audio/speech' +import { speak, speechSupported, stopSpeech } from '../../audio/speech' +import { useFocusTrap } from '../../hooks/useFocusTrap' // GardenPanel is the vocabulary garden: every word the writer has looked up, // grown into a blossom that opens further the more she remembers it, plus a @@ -48,6 +49,12 @@ export function GardenPanel({ onClose, onOpenDoc }: Props) { const [cursor, setCursor] = useState(0) const [revealed, setRevealed] = useState(false) const [expanded, setExpanded] = useState(null) + const panelRef = useFocusTrap() + + // Read-aloud is fire-and-forget, so a word she tapped could still be speaking + // when the panel closes. Cancel any in-flight audio on unmount so it can't + // outlive the garden. + useEffect(() => stopSpeech, []) const load = useCallback(async () => { setError(false) @@ -127,6 +134,11 @@ export function GardenPanel({ onClose, onOpenDoc }: Props) { />
- {checking && ( - <> - · - - - Checking… - - - )} - {voicing && ( - <> - · - - - Reading your voice… - - - )} - {collocating && ( - <> - · - - - Finding natural phrasing… - - - )} - {llmDown && !checking && !voicing && !collocating && ( + {indicators + .filter((i) => i.active) + .map((i) => ( + + · + + + {i.label} + + + ))} + {llmDown && !anyBusy && ( <> · () { + const ref = useRef(null) + + useEffect(() => { + const node = ref.current + if (!node) return + + // Remember where focus was so we can hand it back when the panel closes. + const previouslyFocused = document.activeElement as HTMLElement | null + + const focusables = () => + Array.from( + node.querySelectorAll( + 'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])', + ), + ).filter((el) => el.offsetParent !== null) + + // Focus the first interactive element, or the container itself as a fallback. + const first = focusables()[0] + if (first) first.focus() + else node.focus() + + const onKeyDown = (e: KeyboardEvent) => { + if (e.key !== 'Tab') return + const items = focusables() + if (items.length === 0) { + e.preventDefault() + return + } + const firstEl = items[0] + const lastEl = items[items.length - 1] + const active = document.activeElement + if (e.shiftKey && active === firstEl) { + e.preventDefault() + lastEl.focus() + } else if (!e.shiftKey && active === lastEl) { + e.preventDefault() + firstEl.focus() + } + } + + node.addEventListener('keydown', onKeyDown) + return () => { + node.removeEventListener('keydown', onKeyDown) + previouslyFocused?.focus?.() + } + }, []) + + return ref +}