Phase 12 + 13: collocation coach + vocabulary garden

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
2026-06-26 15:50:25 -07:00
parent 20442d1356
commit 8aa437ec82
23 changed files with 1614 additions and 58 deletions
@@ -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 (
    <div className="flex flex-1 flex-col">
-      <Toolbar editor={editor} onVoiceCheck={onVoiceCheck} voicing={voicing} />
+      <Toolbar
+        editor={editor}
+        onVoiceCheck={onVoiceCheck}
+        voicing={voicing}
+        onCollocationCheck={onCollocationCheck}
+        collocating={collocating}
+      />
      <div
        ref={wrapperRef}
        className="relative flex-1"
@@ -969,6 +1050,8 @@ export function EditorCore({
            word={wordInfo.word}
            info={wordInfo.info}
            loading={wordInfo.loading}
+            saved={wordInfo.saved}
+            onToggleSave={toggleSaveWord}
            style={{ top: wordInfo.top, left: wordInfo.left }}
            onReplace={replaceWord}
          />
@@ -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) {
        <span className="font-bold" style={{ color: 'var(--color-plum)' }}>
          {word}
        </span>
-        {speechSupported() && (
-          <button
-            type="button"
-            onClick={() => speak(word)}
-            aria-label={`Pronounce ${word}`}
-            title="朗读 · Read aloud"
-            className="ml-auto flex h-7 w-7 items-center justify-center rounded-full text-sm"
-            style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
-          >
-            🔊
-          </button>
-        )}
+        <div className="ml-auto flex items-center gap-1.5">
+          {!empty && !loading && (
+            <button
+              type="button"
+              onClick={onToggleSave}
+              aria-label={saved ? 'Remove from vocabulary garden' : 'Save to vocabulary garden'}
+              aria-pressed={saved}
+              title={saved ? '已在词汇花园 · In your garden (tap to remove)' : '加入词汇花园 · Save to garden'}
+              className="flex h-7 w-7 items-center justify-center rounded-full text-sm transition-transform"
+              style={{
+                background: saved ? 'var(--color-accent)' : 'var(--color-surface-alt)',
+              }}
+            >
+              {saved ? '💚' : '🤍'}
+            </button>
+          )}
+          {speechSupported() && (
+            <button
+              type="button"
+              onClick={() => speak(word)}
+              aria-label={`Pronounce ${word}`}
+              title="朗读 · Read aloud"
+              className="flex h-7 w-7 items-center justify-center rounded-full text-sm"
+              style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+            >
+              🔊
+            </button>
+          )}
+        </div>
      </div>

      {/* How to say it — the pronunciation aid for an English learner, paired
@@ -9,4 +9,5 @@ export const TYPE_META: Record<SuggestionType, { color: string; label: string }>
  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' },
 }