Tag suggestion rows by status; repoint approval on promote

Carry each suggestion row's accept/promote status on the entry instead
of
inferring it from row position, so dropping a blank-in-language pick can
never
leave a candidate masquerading as the accept row.
glossedSuggestionEntries now
flattens the resolved read directly (folding in the approved-payload
exclusion),
and the dropdown and suggested-placeholder color from a shared
gloss-suggested
utility.

Make approveAnalysisForToken repoint the one approved link when
promoting an
already-approved token, reclaiming the old payload if it was its last
reference,
rather than no-opping. This unblocks promoting an approved homograph to
a
different pool analysis while keeping the single-approved invariant.

Bound normalizedFormCache with a FIFO eviction cap so the module-global
cache
stays flat across a session that opens many projects.

Author: alex-rawlings-yyc

contributions/localizedStrings.json

@@ -86,12 +86,6 @@
       "%interlinearizer_confirm_discard_ok%": "Discard",
       "%interlinearizer_confirm_discard_cancel%": "Cancel",
 
-      "%interlinearizer_globalEdit_title%": "Update analysis used by {count} tokens?",
-      "%interlinearizer_globalEdit_body%": "This analysis is shared by {count} tokens, so editing it updates all of them. Make a separate analysis to change only this token.",
-      "%interlinearizer_globalEdit_updateAll%": "Update all {count}",
-      "%interlinearizer_globalEdit_fork%": "Make a separate analysis for just this one",
-      "%interlinearizer_globalEdit_cancel%": "Cancel",
-
       "%interlinearizer_modal_saveAs_title%": "Save As",
       "%interlinearizer_modal_saveAs_new_section%": "Save as a new project",
       "%interlinearizer_modal_saveAs_save_new%": "Save as New Project",

src/__tests__/components/TokenChip.suggestions.test.tsx

@@ -163,15 +163,15 @@ describe('TokenChip suggested placeholder', () => {
     const input = screen.getByLabelText('Gloss for logos');
     // Visible at a glance — no focus or hover — so the row reveals which tokens have a suggestion.
     expect(input).toHaveAttribute('placeholder', 'word');
-    expect(input.className).toContain('tw:placeholder:text-success-foreground');
+    expect(input.className).toContain('tw:placeholder:gloss-suggested');
   });
 
   it('falls back to the generic placeholder when the token has no suggestion', () => {
     renderChip(wordToken('tok-x', 'unseen'), { initialAnalysis: poolWithOneApproved('word') });
 
     const input = screen.getByLabelText('Gloss for unseen');
     expect(input).toHaveAttribute('placeholder', 'gloss');
-    expect(input.className).not.toContain('tw:placeholder:text-success-foreground');
+    expect(input.className).not.toContain('tw:placeholder:gloss-suggested');
   });
 
   it('uses the generic placeholder when suggestions are turned off', () => {
@@ -182,7 +182,7 @@ describe('TokenChip suggested placeholder', () => {
 
     const input = screen.getByLabelText('Gloss for logos');
     expect(input).toHaveAttribute('placeholder', 'gloss');
-    expect(input.className).not.toContain('tw:placeholder:text-success-foreground');
+    expect(input.className).not.toContain('tw:placeholder:gloss-suggested');
   });
 
   it('reverts to the generic placeholder once the user types a gloss', async () => {
@@ -194,7 +194,7 @@ describe('TokenChip suggested placeholder', () => {
 
     // With a non-empty draft the typed value shows, so the suggested ghost text no longer applies.
     expect(input).toHaveAttribute('placeholder', 'gloss');
-    expect(input.className).not.toContain('tw:placeholder:text-success-foreground');
+    expect(input.className).not.toContain('tw:placeholder:gloss-suggested');
   });
 });
 
@@ -250,8 +250,12 @@ describe('TokenChip suggestion dropdown', () => {
     const chevron = screen.getByTestId('suggestion-chevron');
     await userEvent.click(chevron);
 
-    const accept = screen.getByTestId('suggestion-accept');
-    expect(accept).toHaveTextContent('finance');
+    // On an already-approved token every alternative is a blue "promote" row, not the green "accept"
+    // row — there is no suggestion to accept, only candidates to promote to.
+    expect(screen.queryByTestId('suggestion-accept')).not.toBeInTheDocument();
+    const promote = screen.getByTestId('suggestion-candidate');
+    expect(promote).toHaveTextContent('finance');
+    expect(promote.className).toContain('tw:gloss-candidate');
     // The already-approved 'riverbank' is excluded — only the alternative is offered.
     expect(screen.queryByText('riverbank')).not.toBeInTheDocument();
   });
@@ -531,10 +535,12 @@ describe('TokenChip suggestion keyboard navigation', () => {
 
     await userEvent.keyboard('{ArrowDown}');
 
-    // The dropdown opens with nothing highlighted, offering the alternative payload.
+    // The dropdown opens with nothing highlighted, offering the alternative as a promote candidate
+    // (an approved token has no "accept the suggestion" row, only promotions).
     expect(input).toHaveAttribute('aria-expanded', 'true');
-    expect(screen.getByTestId('suggestion-accept')).toHaveTextContent('finance');
-    expect(screen.getByTestId('suggestion-accept')).toHaveAttribute('aria-selected', 'false');
+    expect(screen.queryByTestId('suggestion-accept')).not.toBeInTheDocument();
+    expect(screen.getByTestId('suggestion-candidate')).toHaveTextContent('finance');
+    expect(screen.getByTestId('suggestion-candidate')).toHaveAttribute('aria-selected', 'false');
     expect(onGlossChange).not.toHaveBeenCalled();
   });
 

src/__tests__/store/analysisSlice.test.ts

@@ -1899,8 +1899,11 @@ describe('approveAnalysisForToken', () => {
     expect(links.some((l) => l.token.tokenRef === 'tok-2')).toBe(false);
   });
 
-  it('is a no-op when the token already has an approved analysis (single-approved invariant)', () => {
-    // Guards against a stray double-dispatch creating a second approved link for one token.
+  it('repoints the existing approved link when promoting an already-approved token (no second link)', () => {
+    // Promoting an already-approved homograph to a different pool analysis must swap the one approved
+    // link in place rather than appending a second (preserving the single-approved invariant) or
+    // no-opping (which would silently fail the re-promotion the UI offers). A co-linked sibling keeps
+    // ta-1 alive, so the old payload survives.
     const approved: TokenAnalysis = { id: 'ta-1', surfaceText: 'logos', gloss: { en: 'word' } };
     const other: TokenAnalysis = { id: 'ta-2', surfaceText: 'logos', gloss: { en: 'other' } };
     const store = createAnalysisStore({
@@ -1914,6 +1917,11 @@ describe('approveAnalysisForToken', () => {
               status: 'approved',
               token: { tokenRef: 'tok-1', surfaceText: 'logos' },
             },
+            {
+              analysisId: 'ta-1',
+              status: 'approved',
+              token: { tokenRef: 'tok-sibling', surfaceText: 'logos' },
+            },
           ],
         },
         analysisLanguage: 'en',
@@ -1924,11 +1932,83 @@ describe('approveAnalysisForToken', () => {
       approveAnalysisForToken({ tokenRef: 'tok-1', surfaceText: 'logos', analysisId: 'ta-2' }),
     );
 
-    // The existing approved link stands; no second approved link was appended.
+    // The one approved link for tok-1 is repointed to ta-2 — not duplicated.
+    const links = store
+      .getState()
+      .analysis.analysis.tokenAnalysisLinks.filter((l) => l.token.tokenRef === 'tok-1');
+    expect(links).toHaveLength(1);
+    expect(links[0].analysisId).toBe('ta-2');
+    // The sibling still approves ta-1, so the old payload survives.
+    expect(store.getState().analysis.analysis.tokenAnalyses.map((ta) => ta.id)).toEqual([
+      'ta-1',
+      'ta-2',
+    ]);
+  });
+
+  it('reclaims the old payload when promoting an already-approved token off its last reference', () => {
+    // When the promoted-away payload has no other approved link, repointing leaves it orphaned, so
+    // it is dropped — a promotion never strands an empty payload.
+    const approved: TokenAnalysis = { id: 'ta-1', surfaceText: 'logos', gloss: { en: 'word' } };
+    const other: TokenAnalysis = { id: 'ta-2', surfaceText: 'logos', gloss: { en: 'other' } };
+    const store = createAnalysisStore({
+      analysis: {
+        analysis: {
+          ...emptyAnalysis(),
+          tokenAnalyses: [approved, other],
+          tokenAnalysisLinks: [
+            {
+              analysisId: 'ta-1',
+              status: 'approved',
+              token: { tokenRef: 'tok-1', surfaceText: 'logos' },
+            },
+          ],
+        },
+        analysisLanguage: 'en',
+      },
+    });
+
+    store.dispatch(
+      approveAnalysisForToken({ tokenRef: 'tok-1', surfaceText: 'logos', analysisId: 'ta-2' }),
+    );
+
+    const links = store
+      .getState()
+      .analysis.analysis.tokenAnalysisLinks.filter((l) => l.token.tokenRef === 'tok-1');
+    expect(links).toHaveLength(1);
+    expect(links[0].analysisId).toBe('ta-2');
+    // ta-1 had no other approved reference, so it was reclaimed.
+    expect(store.getState().analysis.analysis.tokenAnalyses.map((ta) => ta.id)).toEqual(['ta-2']);
+  });
+
+  it('is a no-op when promoting an already-approved token to the analysis it already approves', () => {
+    // Re-approving the same payload changes nothing — the link already points there.
+    const approved: TokenAnalysis = { id: 'ta-1', surfaceText: 'logos', gloss: { en: 'word' } };
+    const store = createAnalysisStore({
+      analysis: {
+        analysis: {
+          ...emptyAnalysis(),
+          tokenAnalyses: [approved],
+          tokenAnalysisLinks: [
+            {
+              analysisId: 'ta-1',
+              status: 'approved',
+              token: { tokenRef: 'tok-1', surfaceText: 'logos' },
+            },
+          ],
+        },
+        analysisLanguage: 'en',
+      },
+    });
+
+    store.dispatch(
+      approveAnalysisForToken({ tokenRef: 'tok-1', surfaceText: 'logos', analysisId: 'ta-1' }),
+    );
+
     const links = store
       .getState()
       .analysis.analysis.tokenAnalysisLinks.filter((l) => l.token.tokenRef === 'tok-1');
     expect(links).toHaveLength(1);
     expect(links[0].analysisId).toBe('ta-1');
+    expect(store.getState().analysis.analysis.tokenAnalyses).toHaveLength(1);
   });
 });

src/components/AnalysisStore.tsx

@@ -165,9 +165,18 @@ export function AnalysisStoreProvider({
     if (wasPending !== isPending) onPendingEditsChangeRef.current?.(isPending);
   }, []);
 
-  // The gloss-write entry point exposed to inputs. A gloss edit is per-token: the reducer forks a
-  // shared payload before writing (blank clears, non-blank edits), so editing one token never
-  // rewrites the others. Write, persist via `onSave`, then notify the `onGlossChange` spy.
+  /**
+   * The gloss-write entry point exposed to inputs. Dispatches {@link writeGloss} so the reducer
+   * applies a per-token edit — it forks a shared payload before writing (blank clears, non-blank
+   * edits), so editing one token never rewrites its co-linked siblings — then persists the updated
+   * analysis via `onSave` and notifies the `onGlossChange` spy with the edited token and value.
+   *
+   * @param tokenRef - `Token.ref` of the token being glossed.
+   * @param surfaceText - Surface text of the token, recorded so the analysis can detect baseline
+   *   drift.
+   * @param value - New gloss string; blank (empty or whitespace) clears the active language's
+   *   gloss.
+   */
   const requestGlossEdit = useCallback(
     (tokenRef: string, surfaceText: string, value: string) => {
       store.dispatch(writeGloss(tokenRef, surfaceText, value));

src/components/SuggestionDropdown.tsx

@@ -39,13 +39,15 @@ type SuggestionDropdownProps = Readonly<{
 }>;
 
 /**
- * Renders the portaled suggestion listbox for a token's gloss combobox. Row 0 is the suggested pick
- * (green); the rest are candidates (blue), matching the inline coloring this replaced. The
- * keyboard-active row gets the same `bg-accent` background hovering applies, and hovering a row
- * sets the active index so only one row is ever highlighted. Each row suppresses its mouse-down
- * default so clicking it never blurs the input — focus stays in the input and the click selects
- * instead. The panel closes itself on outer scrolling (the anchor would drift); scrolling the
- * panel's own overflow is ignored so a long list can be scrolled without dismissing it.
+ * Renders the portaled suggestion listbox for a token's gloss combobox. Each row is colored and
+ * labeled by its own `status` — `'suggested'` (green, "accept") or `'candidate'` (blue, "promote")
+ * — carried on the entry rather than inferred from row position, so a dropped blank-in-language
+ * pick can never leave a candidate masquerading as the accept row. The keyboard-active row gets the
+ * same `bg-accent` background hovering applies, and hovering a row sets the active index so only
+ * one row is ever highlighted. Each row suppresses its mouse-down default so clicking it never
+ * blurs the input — focus stays in the input and the click selects instead. The panel closes itself
+ * on outer scrolling (the anchor would drift); scrolling the panel's own overflow is ignored so a
+ * long list can be scrolled without dismissing it.
  *
  * @param props - Component props (see {@link SuggestionDropdownProps}).
  * @returns A `document.body` portal containing the listbox, positioned under the anchor input.
@@ -132,13 +134,13 @@ export default function SuggestionDropdown({
         <li
           key={entry.id}
           aria-label={
-            index === 0
+            entry.status === 'suggested'
               ? `Accept suggestion ${entry.gloss} for ${surfaceText}`
               : `Promote ${entry.gloss} for ${surfaceText}`
           }
           aria-selected={index === activeIndex}
-          className={`tw:cursor-pointer tw:whitespace-nowrap tw:px-2 tw:py-0.5 tw:text-sm tw:italic ${index === 0 ? statusTextColorClass('suggested') : statusTextColorClass('candidate')}${index === activeIndex ? ' tw:bg-accent' : ''}`}
-          data-testid={index === 0 ? 'suggestion-accept' : 'suggestion-candidate'}
+          className={`tw:cursor-pointer tw:whitespace-nowrap tw:px-2 tw:py-0.5 tw:text-sm tw:italic ${statusTextColorClass(entry.status)}${index === activeIndex ? ' tw:bg-accent' : ''}`}
+          data-testid={entry.status === 'suggested' ? 'suggestion-accept' : 'suggestion-candidate'}
           id={optionId(index)}
           role="option"
           // Select on mouse-down, suppressing its default focus shift, so choosing a row never blurs

src/components/TokenChip.tsx

@@ -174,29 +174,17 @@ export function TokenChip({
 
   const hasMorphemes = morphemes.length > 0;
 
-  // The pool entries to offer via the suggestion dropdown. For a suggested token this is the engine's
-  // derived pick plus candidates. For an approved token this is the pool alternatives only —
-  // the already-approved payload is filtered out so the dropdown only shows genuinely different
-  // choices (re-approving the same analysis via the dropdown would be a no-op). Row 0 is the green
-  // "accept"; the rest are blue "promote" candidates. Blank-in-active-language entries are dropped
-  // individually rather than shown as empty rows (see `user-questions.md` display #3).
-  const suggestion = useMemo(() => {
-    if (!resolved) return undefined;
-    if (resolved.status === 'suggested') return resolved;
-    const pool = resolved.poolSuggestion;
-    if (!pool) return undefined;
-    const approvedId = resolved.analysis.id;
-    // Keep only pool entries that are not the already-approved analysis.
-    const alternatives = [pool.suggested, ...pool.candidates].filter((a) => a.id !== approvedId);
-    if (alternatives.length === 0) return undefined;
-    return { suggested: alternatives[0], candidates: alternatives.slice(1) };
-  }, [resolved]);
-  // Memoized on the (reference-stable) suggestion and active language so typing a gloss — which only
-  // changes local draft state — never re-runs the engine's flatten/filter; it recomputes only when
-  // the suggestion or language actually changes.
+  // The pool entries to offer via the suggestion dropdown, with their accept/promote status. The
+  // engine flattens the resolved read into ranked, status-tagged rows: for a suggested token its
+  // pick (green "accept") plus candidates (blue "promote"); for an approved token the pool
+  // alternatives only (all blue "promote", the already-approved payload excluded). Blank-in-active-
+  // language entries are dropped individually rather than shown as empty rows (see
+  // `user-questions.md` display #3). Memoized on the (reference-stable) resolved read and active
+  // language so typing a gloss — which only changes local draft state — never re-runs the flatten/
+  // filter; it recomputes only when the resolved read or language actually changes.
   const glossedRanked = useMemo(
-    () => glossedSuggestionEntries(suggestion, analysisLanguage),
-    [suggestion, analysisLanguage],
+    () => glossedSuggestionEntries(resolved, analysisLanguage),
+    [resolved, analysisLanguage],
   );
   // Whether this token has anything to suggest: gated on the demo toggle (via the resolve short-
   // circuit) and editability. The chevron and dropdown only ever appear when this is true.
@@ -274,9 +262,6 @@ export function TokenChip({
         // non-empty while open, but glossedRanked can empty out after open (a row approved away),
         // leaving suggestionsOpen stale while the dropdown is unmounted — guard so Enter closes
         // rather than dereferencing an absent pick.
-        // activeIndex -1 (nothing highlighted) falls back to the top row. The list is normally
-        // non-empty while open, but glossedRanked can empty out after open (a row approved away)
-        // while suggestionsOpen is still true, so guard rather than dereference an absent pick.
         const pick = glossedRanked[activeIndex] ?? glossedRanked[0];
         if (pick) selectSuggestion(pick.id);
         /* v8 ignore next -- defensive: the empty-pick race above is not reachable from the call sites */ else
@@ -465,9 +450,10 @@ export function TokenChip({
             aria-expanded={hasSuggestions ? dropdownShown : undefined}
             aria-label={`Gloss for ${token.surfaceText}`}
             // When the empty input is showing a suggested gloss as its placeholder, color that ghost
-            // text green (the same success color the dropdown's accept row uses) and italicize it, at
-            // full opacity, so it reads clearly as a suggestion rather than a faint generic hint.
-            className={`tw:gloss-input${showSuggestedPlaceholder ? ' tw:placeholder:text-success-foreground tw:placeholder:italic tw:placeholder:opacity-100' : ''}`}
+            // text via the same `gloss-suggested` utility the dropdown's accept row uses (one source
+            // of truth for the suggested green) and italicize it, at full opacity, so it reads
+            // clearly as a suggestion rather than a faint generic hint.
+            className={`tw:gloss-input${showSuggestedPlaceholder ? ' tw:placeholder:gloss-suggested tw:placeholder:italic tw:placeholder:opacity-100' : ''}`}
             disabled={disabled}
             id={glossInputId}
             placeholder={

src/components/__mocks__/AnalysisStore.tsx

@@ -8,12 +8,12 @@ import type { ResolvedTokenAnalysis } from '../../utils/suggestion-engine';
 type GlossMap = Record<string, string>;
 type MockCtxValue = {
   glosses: GlossMap;
-  dispatch: (tokenRef: string, surfaceText: string, value: string) => boolean;
+  dispatch: (tokenRef: string, surfaceText: string, value: string) => void;
   language: string;
 };
 const MockCtx = createContext<MockCtxValue>({
   glosses: {},
-  dispatch: () => false,
+  dispatch: () => {},
   language: 'und',
 });
 
@@ -54,8 +54,6 @@ export function AnalysisStoreProvider({
     (tokenRef: string, _surfaceText: string, value: string) => {
       setGlosses((prev) => ({ ...prev, [tokenRef]: value }));
       onGlossChange?.(tokenRef, value);
-      // The mock has no global-edit gate, so an edit is never held — always reports "committed".
-      return false;
     },
     [onGlossChange],
   );
@@ -132,17 +130,16 @@ export function useMorphemeDeleteDispatch(): (tokenRef: string) => void {
 }
 
 /**
- * Returns a no-op dispatch for writing morpheme glosses in mock context. Reports "committed" (never
- * held), matching the real hook's boolean return.
+ * Returns a no-op dispatch for writing morpheme glosses in mock context.
  *
  * @returns A no-op function matching the real signature.
  */
 export function useMorphemeGlossDispatch(): (
   tokenRef: string,
   morphemeId: string,
   value: string,
-) => boolean {
-  return () => false;
+) => void {
+  return () => {};
 }
 
 /**