feat(terminal): localize settings option chips via display-label catalog

[pro-vi]

Summary

Localizes the Settings scene's option-value chips (font, cast method, cast mode, taijitu, glyph animation) for zh-Hant/zh-Hans through a token-keyed display-label catalog, while keeping stored config tokens, CLI stdout, and the config parse surface byte-identical. Implements the policy the glossary already sanctioned ("display labels for enum values are a SEPARATE catalog layer that never mutates the stored token") and removes the mixed-register zh Settings screen (CJK row labels above English chips).

Stacked on #5 (feat/language) — merge after it.

Key Changes

Features

• Option-label catalog (packages/terminal/src/i18n/option-labels.ts): optionLabel(lang, settingKey, token) — token-keyed Map (prototype-chain reaches miss by construction), total resolution with canonical-token fallback, zh-Hans authored explicitly. Not routed through tr() — MessageKey is a literal union; widening it to dynamic keys would break the exhaustive-catalog contract.
• Localized chips: font 楷體/隸變/黑體; cast method 銅錢 (coin)/蓍草 (yarrow) — canonical token rides in the label as the bridge back to the CLI value; cast mode 自動/手動; taijitu 點陣/密實; anim 噪點/點陣/放射/沙化. en mode unchanged. Labels derive from the live language selection (mid-screen flip re-labels same frame).
• Glossary + policy matrix (docs/language-glossary.md, TEXT_SURFACES.md): token-keyed ratification table (噪點=noise / 點陣=dots transposition hazard cross-referenced), theme labels recorded as deferred (brand-vs-literal ruling pending), input-alias policy: none.

Refactoring

• Identity-bound getValues(): SettingRow now carries canonical token arrays (values); field↔row mapping goes through the row key via selectedValue() instead of this.rows[0]…this.rows[6] positional indexing — reordering rows can no longer silently swap persisted values. Pre-existing two-way coupling (display-string→canonical by index AND field→row by position) is fully removed; no casts introduced.

Tests / Verifier

• Behavioral enforcement (scripts/verify-language-surfaces.ts --terminal): full ratified (settingKey, token) → 繁/简 contract checked through optionLabel(); en = canonical token pinned; theme verbatim-fallback pinned; prototype-chain miss pinned; representative label sentinels wired to the inventory row. Deleting a shipped entry reds the verifier (proven by mutation during development).
• Scene tests: per-wave chip rendering in all three languages, Simplified-residue guards, width budget under the en theme row, persistence round-trips, white-box row-reorder test locking the identity-bound contract. Re-pinned the "option-value badges remain verbatim" comment to the new policy. "[EN] 繁 简" endonym assertion preserved verbatim.

Technical Context

• Two label mechanisms coexist deliberately: LANGUAGE_LABELS (EN/繁/简) are endonym badges, invariant across display languages, heavily pinned by fixture rows + sentinels — untouched. OPTION_LABELS is the per-display-language layer for the other rows.
• No parser widening: translated chips do NOT get config-file aliases; config set and hand-edited files stay canonical-only (recorded in glossary + scope boundary). The TUI↔CLI vocabulary bridge is the in-label canonical hint, not an alias table.
• Theme chips stay verbatim until the glossary records whether ink/bone/cinnabar/jade/river are literal words or palette brand names (deferred follow-up).
• Plan: docs/plans/2026-06-10-001-feat-settings-option-label-localization-plan.md (origin: PR feat: add language-aware detail view #5 review session + cross-model second opinion).

Testing Scenarios

• zh-Hant renders 楷體/銅錢 (coin)/自動/點陣/噪點 chips; zh-Hans renders Simplified forms; en unchanged (589 tests pass)
• Persistence: zh-mode selections write canonical tokens; config get castMethod chain pinned by existing CLI tests
• Live language flip re-labels chips same frame, values untouched
• Row reorder cannot swap persisted values (white-box contract test)
• Prototype-chain token ("constructor") falls back, never resolves inherited members
• bun run typecheck, full suite, and verify-language-surfaces run-all: PASS — 0 issues

---

Generated with: Claude Code

QA checklist

All items verified fresh at ff0ffd8 on feat/settings-option-labels. TUI adaptation note: this is a terminal app — "screenshots" below are rendered CellBuffer dumps (80×24, the scene's real render path), captured by a reproducible script (bun one-shot rendering SettingsScene; commands inline). No browser/visual-proof manifests apply; provenance = git HEAD above + the capture commands.

• R1 — zh modes render localized chips; en unchanged — full-scene dumps per language; only theme chips remain English (deferred by R5):

  ──── settings @80x24 language=zh-Hant ────
                  主題
                  > ink  [bone]  cinnabar  jade  river
                  語言
                    EN  [繁]  简
                  太極圖
                    [點陣]  密實
                  字形動畫
                    [點陣]  噪點  放射  沙化
                  字體
                    [楷體]  隸變  黑體
                  起卦法
                    [銅錢 (coin)]  蓍草 (yarrow)
                  起卦模式
                    [自動]  手動
  ──── settings @80x24 language=zh-Hans ────
                  字体
                    [楷体]  隶变  黑体
                  起卦法
                    [铜钱 (coin)]  蓍草 (yarrow)
                  起卦模式
                    [自动]  手动
  ──── settings @80x24 language=en (unchanged) ────
                  Font
                    [kaiti]  libian  heiti
                  Cast Method
                    [coin]  yarrow
  

  (zh-Hans block abridged to the wave rows; en block abridged — full dumps reproduce via the capture script.)

• R2 — persisted tokens, CLI stdout, and parse surface unchanged; no new aliases — live CLI round-trip on a fresh --data-dir with language=zh-Hant:

  $ iching config get castMethod
  yarrow
  $ cat config.json   → "castMethod": "yarrow"  (canonical tokens only)
  $ iching config set castMethod 蓍草
  Invalid value "蓍草" for castMethod. Valid: coin, yarrow   (exit 1 — no parser widening)
  

• R3 — labels resolve from the live language selection — start in en, focus Language row, → to 繁: chips re-label in the same rendered frame, values untouched:

  ──── live flip en→zh-Hant (no save) ────
                  字體
                    [楷體]  隸變  黑體
  getValues(): { "glyphFont": "kaiti", "castMethod": "coin", ... }  (canonical)
  

  Locked by test: "flipping Language re-labels font chips immediately, before save".

• R4 — missing label falls back to canonical token, never crashes/persists — theme chips render ink bone cinnabar jade river verbatim in zh dumps above (empty-entry fallback, live); prototype-chain tokens (constructor, __proto__, toString…) pinned to miss by option-labels.test.ts and the verifier's contract check.

• R5 — theme chips verbatim pending glossary ruling — visible in the zh-Hant dump (主題 row shows English tokens); deferral + unratified candidates recorded in docs/language-glossary.md §Settings option-chip display labels and TEXT_SURFACES.md term-theme-names.

• R6 — policy artifacts re-pinned to "tokens canonical; labels via catalog" — scene-language.test.ts comment re-pinned; "[EN] 繁 简" assertion preserved; verifier --terminal now enforces the full ratified label contract behaviorally. Mutation red-proof during U5: deleting the noise entry → FAIL — option label settings.glyphAnimation.noise: zh-Hant != ratified "噪點".

• Automated — fresh runs at ff0ffd8:

  bun run test       → 589 pass, 0 fail (61 files)
  bun run typecheck  → clean
  bun scripts/verify-language-surfaces.ts → run-all (AC-009 final) PASS — 0 issues