feat(words): R1 — V2 architecture proposal + types-v2 + validator + 50 tests
Architectural refactor proposal landed for review. R1 closes the
audit + type design + validator phase. V1 stays untouched in parallel.
ARCHITECTURE_PROPOSAL.md (~500 lines):
- 8 principles signed (P1 content↔design strict, P2 raw values only,
P3 renderer translates, P4 runtime state out, P5 framework-neutral
engine, P6 single source of truth, P7 sema intents canonical for
evaluative vocabulary, P8 per-property entry rules).
- D-SEM-1/2/3 + Q1-Q6 all signed with recommendations accepted by
user. Notable: CalloutBlock.intent uses SemaIntent canonical
(neutral|affirm|fulfill|risk|threat|loss), NOT web admonition
vocabulary (warning|info|danger|etc.) — those live as UI labels +
Markdown serializer mappings ONLY.
engine/types-v2.ts (~320 lines):
- WordsDocumentV2 with version '2.0.0'.
- BlockBase with optional id (autogen at load) + optional visual
sidecar.
- BlockVisual with RAW values only (numbers in px, hex color
strings). Per-type Pick<> subsets: ParagraphVisual / HeadingVisual
/ QuoteVisual / CodeVisual / ListVisual / TableVisual / ImageVisual
/ DividerVisual / CalloutVisual.
- 9 block types: paragraph, heading, quote, code, list, table,
image PLUS new divider (semantic <hr>) and callout (with
WordsEvalIntent + nestable block children).
- Marks refactored from V1 template-literal `color:${string}` to
structured `{type:'color'|'background', value:'#hex'}`. Type-safe.
- Image upload status REMOVED from the content model (P4): the
WordsImageBlockV2 no longer has `status`; it goes to runtime
sidecar `provider.runtime.imageStatus: Map<blockId, status>`.
- Table V2 drops `striped` + `compact` (presentation tokens). Adds
`headerRow` + `headerCol` (semantic accessibility). Per-cell and
per-row `visual` allowed (background for zebra; cell padding).
- Cell `tone: 'muted'|'accent'` REMOVED (was a design system token).
Replace with cell.visual.background hex if user wants a tinted
cell.
- WordsEvalIntent declared locally in engine to keep engine
framework-neutral. Parity with $uix/sema asserted at boot
(TODO in R2).
engine/validate-v2.ts (~520 lines):
- Pure function validateWordsDocument(input) → ValidationResult.
- 11 error codes: invalid-version, invalid-block-type,
invalid-block-shape, invalid-children, invalid-visual-key,
invalid-visual-value, invalid-mark, invalid-href,
invalid-eval-intent, invalid-enum-value, invalid-number,
duplicate-id, invalid-text-content, invalid-link-children.
- Enforces P2: hex regex on color fields, finite numbers on
dimension fields, rejects tokens / classes / var() refs / non-
canonical mark shapes.
- Enforces P8: per-type Pick<> at runtime via
WORDS_VISUAL_KEYS_PER_TYPE whitelist.
- Enforces P7: callout.intent must be one of the 6 canonical sema
intents; rejects web vocabulary (`warning`/`info`/etc.).
- Each error carries a JSON-pointer path (e.g.
/children/1/visual/background).
engine/validate-v2.test.ts (50 tests):
- Top-level shape, block type registry, marks (boolean + structured
+ V1 reject + token reject), visual properties (allowed +
rejected tokens/classes/var()/non-numeric + per-type Pick<>),
id uniqueness, heading levels, list kind + indent, code text-only
children, image src + width, callout SemaIntent + reject of web
vocabulary + nested blocks, divider, quote.cite URL parseability,
link nesting + URL parseability, table headerRow/headerCol +
per-cell visual whitelist + per-row visual.
Verification: 135/135 engine tests pass (85 V1 + 50 V2). V1
untouched. npm run check: 0 errors, 26 warnings (pre-existing).
Next: R2 — migrator V1→V2, runtime image-status sidecar, refactor
provider to consume V2 internally.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
dev
9b13e3cf23