Move the active-app reference into the book tree as the arts composition root,
the App-side analogue of active-uix.md:
- new docs/architecture/active-app.md (frontmatter + fixed relative paths); the
dated Spanish "Handoff 2026-05-13" heading becomes a timeless "Quick start".
- extract that Handoff block verbatim (ES) to docs/process/handoffs-2026-05.md,
alongside the other extracted arts/uix handoffs.
- stub src/arts/active-app/README.md pointing at the chapter (active-uix pattern).
- wire the chapter into the docs/README.md E1 map.
docs:check 0 errors (11 pre-existing warnings unrelated).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Closes the provider→recipe direction of the CSS-var drift stumble the
architecture-faithful way: the morfo is the source of truth. A component now
declares the functional custom properties its soma provider writes and its eidos
recipe reads:
cssVars: [{ name: 'progress', … }, { name: 'angle', … }] // → --knob-progress, --knob-angle
- types: `MorfoCssVar` + optional `cssVars` on `Morfo` (additive; the 133
existing morfos are unaffected).
- schema: validates `cssVars` (array of `{ name, description? }`).
- compile: exposes `contracts.cssVars` as full names `--{kebab}-{name}`.
- knob morfo declares its two contract vars.
- guard (recipe-css-contract.test.ts): enumerates morfos via `import.meta.glob`
and verifies BOTH sides honour each declaration — the provider writes
`--{kebab}-{name}` AND the recipe reads it — so renaming one side without the
other fails loudly. Proven non-vacuous (a bogus cssVar is flagged on both
sides).
Why A1 and not a grep cross-check (A2): in the CSS a provider-written functional
var and a consumer-override alias are indistinguishable, and providers publish
hook vars the recipe doesn't consume — a grep gives ~17 false positives (proven
earlier). The morfo declaration is what disambiguates.
npm run check 59 (baseline, 0 in touched files); eidos recipe-css-contract 24/24;
morfo suite green (only the pre-existing dialog-role test fails); docs:check 0.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds a '### Authoring notes' subsection to soma.md §6 grounded in the real
defs — state<T>() vs $state, role optionality on a Provider, Without<>/
PrimitiveDivAttributes, and gesture pointermove/up ownership. Closes STUMBLES
#9; only #7 (soma->eidos CSS-var contract, design-open) remains.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The emit contract explains discrete events (one gesture → one emit → one
hold) but says nothing about direct-manipulation surfaces (Slider, Drawer,
future knob/swipe) where the pointer moves at sample rate while the value
updates continuously. Add a `## Continuous components (drag, swipe, hold)`
section after the emit contract, grounded entirely in the real Slider/Drawer
code (adversarially fact-checked, zero discrepancies):
- One door: `runtime.trigger()` is the sole path (there is no `emitEvent`).
Its Promise represents the whole occurrence incl. the visual hold — so
`void trigger()` is fire-and-forget (correct for high-frequency emits) and
`await trigger()` blocks until the hold ends (correct when a structural
change must observe the resolved signal, e.g. `close`).
- `coincident` vs `post` for a moving value: the move (handle-drag,
drag-progress) is `coincident` (signal + mutation indivisible); the commit
(commit-set) is `post` (handler settles, then the signal celebrates).
Slider is the worked example.
- Throttle continuous POINTER emits, not keyboard: pointer emits are coalesced
to animation frames + floored to a component-tuned interval via ActiveDom's
requestFrame (Slider DRAG_SIGNAL_MS, Drawer DRAG_PROGRESS_SIGNAL_MS);
keyboard commit-set fires once per keydown (already human-paced). Tuning ms
point to the code, never hard-coded here.
- The per-emit `overrides` payload owns pitch/gain/contour; a continuous
event's cascade rule sets only `channels` and MUST NOT override those
primitives, or it would clobber the live payload every frame.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The common ARIA pattern "emit aria-label only when there is no Label part"
was not declarable. Add `{ when: 'part-absent', part }` as the logical
inverse of `part-present`, plumbed through the four condition sites:
- types.ts: MorfoCondition union member + JSDoc.
- schema.ts: discriminated-union member (structural accept) + extend the
checkCondition unknown-part guard to cover part-absent (throws on unknown
part, same as part-present — the prior guard only discriminated part-present).
- compile.ts: collectConditionDeps adds the referenced part to partRefs, so
the runtime re-evaluates when the part's presence toggles.
- resolver.ts: shouldEmitMorfoEntry returns !bindings.parts?.[part] — emit
when the part is absent/falsy, suppress when present.
Runtime + keyboard paths delegate to these helpers (evalAttrPlan /
shouldEmitMorfoEntry), so no runtime change is needed. Correct by symmetry
with part-present, which reads the same presence-accurate bindings.parts.
Tests: schema accepts a part-absent condition on a known part and throws on
an unknown part; the compiler collects the part dep; the resolver emits the
value when the part is absent and undefined when present.
Docs: morfo.md condition list gains the part-absent form.
Non-breaking: no existing morfo uses it.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Removes the two runtime dependencies that broke the "framework depends on
nobody" doctrine, porting them into our own code (same move as
floating-ui -> $ethereal).
F1 (dropped the deps):
- tabbable -> src/libs/dom/tabbable-core.ts (getComputedStyle/CSS.escape
resolved from the node's own window, iframe-safe); consumed by the
existing tabbable.ts wrapper and surfaced via $adom.
- runed Context + watch/watch.pre/watchOnce -> $libs/reactive.
- runed ElementSize -> $adom/element-size.svelte.ts, rebuilt window-correct
on the node's own window (not defaultWindow).
- Rewired ~33 watch + 3 Context imports; floating (ElementSize) and
focus-scope (tabbable) now consume $adom.
F2 (rest of the pure reactive runes -> $libs/reactive):
- Previous, IsMounted, onCleanup, interval, debounce/Debounced,
throttle/Throttled, StateHistory, FiniteStateMachine, resource.
- Dropped runed's React-style use* prefix; reused framework toValue
(=extract) + MaybeActiveOrGetter; added Setter<T>.
runed + tabbable removed from package.json. `npm run check` = 59 (baseline,
0 in ported files); tests unchanged (pre-existing failures only).
F3 (remaining DOM-reactive runes -> $adom on ActiveDom, + PersistedState
-> $storage) is pending: see docs/process/continue-runed-tabbable-port.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
An agent building a component from the docs-book alone could not assign
archetypes / holds / haptic kinds: the closed sets live only in code consts
and the corpus (correctly) forbids copying them into prose, so they were
invisible from the docs. STUMBLES #1, the top stumble.
Fix: docs/canon/vocabularies.md is GENERATED from the consts by
'npm run docs:vocabularies' — the ONE sanctioned place the lists are spelled
out (generated = no drift objection), which every other doc links to. It
covers part archetypes (with a one-line role each), sema families with their
default hold/persistence + per-intent overrides, verbs by family, intents,
the perceptual-duration scale, haptic kinds, the 33 palette scales, sizes,
variant archetypes, and the shared common.* strings.
- scripts/docs-vocabularies.ts imports the consts (robust — no fragile
JSDoc/regex parsing) and formats them; the generation is an exported
function so docs-check can compare.
- Added ARCHETYPE_DESCRIPTIONS to morfo/types.ts (co-located with
ARCHETYPE_VOCABULARY, satisfies Record<MorfoArchetype,string>) as the
authoritative one-liners the appendix reads — descriptions become
first-class data instead of inline union JSDoc a tool would have to parse.
- docs-check gains I7: it regenerates in-memory and fails if the committed
file drifts from the consts (negative-tested: corrupt -> error, regen ->
green). The appendix's own counts pass I1, so I1 doubles as a second guard.
- Linked from README (E2 canon row + two 'I want to' shortcuts), CANON.md
(doctrine here, enumerated lists there), architecture/morfo.md (pick a
part's archetype), and the component-audit minimum-package list (STUMBLES
#8).
docs:check 0 errors; npm run check unchanged in my files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two user findings from the Knob build exercise (an agent building a new
component from the docs alone — STUMBLES.md).
Quarantine: the superseded fossils no longer share shelf space with the
live corpus. docs/old-deprecated/ (with an index README explaining what
lands there and pointing readers at docs/README.md) now holds the
executed audits and fix plans: fable_audit, fable-eidos-audit,
inherit_audit + inherit_fix_plan, ARCHETYPE_COHERENCE_AUDIT_2026-06-19
(still citable — the component-guide banner and the eidos components
README repoint to it), COMPONENT_COHERENCE_AUDIT. pendiente.md (a live
pending list, not a fossil) moved to docs/process/. docs-check treats
the folder as sealed chronicle (I1/I2 exempt; I6 skips its internal
links, as its README promises). Root-level *.md is now: README, CLAUDE,
AGENTS + the user's own working files.
STUMBLES fixes applied on the spot (the doc-class ones):
- #2 kind drift: the REAL enum is 'public' | 'private' | 'virtual'
(MorfoPartKind, 671/9/14 uses) — morfo.md omitted 'private', the
checklist invented 'internal' (0 uses). Both fixed; I2 gains the
phantom-'internal' guard. A-2.1's row now says what the audit script
actually checks (kebab only — the archetype may vary, the Toggle
provider-IS-trigger doctrine).
- #6: the langs catalog SHAPE (flat keys, per-language leaves, named
export, index registration) is now shown in morfo.md instead of only
its location.
- #8: component-audit s0 defines the minimum brief package as an
explicit 8-file list.
The engineering-class stumbles are registered as plan batches S1-S6
(generated vocabularies appendix, continuous-gesture trigger doctrine,
part-absent condition, Gesture.rotate, the soma->eidos CSS-var
contract, minor frictions). docs:check 0 errors, 11-warn baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The global sweep caught the last corpus links still pointing at
pre-book paths: morfo chapter's s2.bis cross-ref (src/uix/README ->
overview.md), authoring's E1 stratum row (active_architecture ->
docs/architecture/), the related: frontmatter of decisions.md and
canon/recipe-contract.md (THEMING/THEMING_GUIDE -> theming/reference +
guide), and component-audit's typographic-vertebration pointer (eidos
README -> architecture/eidos.md with the translated heading). README
map completed as the book TOC: every chapter now has a row —
theming/motion.md (the model) and theming/changelog.md (the chronicle)
were the two missing. Remaining old-path references live only in
chronicle docs (theming/changelog, process/) and resolve via stubs;
the 11-warn baseline is all foreign targets (MOTION_SERVICE_RFC demo
routes, deleted THEMING_AUDIT/PENDIENTES).
F7.6 complete. The book tree is fully populated: architecture/ (8) +
canon/ (2) + theming/ (7) + rfcs/ (7) + guides/ (4) + decisions/ (2).
Next and last: F7.7 CLAUDE.md thinning — diff to the user first.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
LIBRO_VARIACIONES_Y_EXTENSIONES -> decisions/book-deviations.md and
GUIA_IMPLEMENTACION_SEMAUIX -> decisions/guia-semantica-historica.md,
both moved AS-IS in Spanish: the deviations registry is a logbook of the
author's literal decisions ('transcrita literal') and carries proposed
doctrinal text destined for the Spanish book — translating it would
destroy that function (s G calls itself bitacora); the guia was already
status: historical (Fase 6) and the plan exempts it explicitly. English
frontmatter added to both; internal cross-links repointed (CANON,
theming/reference, book-deviations D.11). docs-check's I2 phantom-field
exemption follows the moved file (it matched by the LIBRO_VARIACIONES
filename; now also matches decisions/book-deviations.md). Corpus swept:
CANON x3, README (E2/E3 strata + tables — also fixed the pre-Fase-6
leftover row still calling the guia 'authoritative for any new wrapper'
and the unswept eidos/TSC.md stratum mention), building-a-component D.4,
completion-checklist G-1.1 + header, theming/reference, architecture
x5 (active-architecture, eidos, morfo, overview, sema x2).
docs:check 0 errors, 11-warn baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/soma/COMPONENT_GUIDE.md (1449 L, English body) moved to
docs/guides/component-guide.md. The only Spanish passage — the
archetype-canon banner (2026-06-19) — translated in the move; the rest
is verbatim. Banner's ARCHETYPE_COHERENCE_AUDIT link reaches into src
(audit fossil, stays with the code); the checklist cross-link is now
the sibling ./completion-checklist.md and the 'soma/README s9' mention
now names architecture/soma.md (its post-F7.2 home). Corpus swept:
authoring + README E4 stratum rows (also stale THEMING_GUIDE name),
building-a-component phases 0/2, architecture/{soma-architecture s4/
s13-tree/s17, overview, morfo, active-architecture}.
F7.5 complete: docs/guides/ = component-guide, completion-checklist,
demo-authoring, component-audit. docs:check 0 errors, warns back at
the 11 baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Three English guides moved verbatim (copy + link touch-ups, no
translation): COMPONENT_COMPLETION_CHECKLIST -> guides/
completion-checklist.md, COMPONENT_AUDIT_GUIDE -> guides/
component-audit.md, DEMO_AUTHORING_GUIDE -> guides/demo-authoring.md.
Tooling moved with its doc in the same pass: docs-check I5 now parses
the checklist at the new path (verified: 0 errors, rule tables found)
and component-audit.ts's two path strings updated. One reconciliation
in the audit guide's s5, applied as link-don't-copy: the copied v1
6-tab template list (stale vs the v2 9-tab guide it links, drawer
canary vs button) is replaced by a pointer to demo-authoring.md; the
domain canaries in s7 stay. demo-authoring's harness links now reach
into web/routes/uix/lib/ (the modules stay with the code); the deleted
pendiente_color_demos.md reference is marked TODO(reconcile). Corpus
swept: building-a-component (frontmatter related: + phases 6/8),
authoring, architecture/soma, theming/reference s5-parity,
testing-and-tooling, getting-started, README (E4 rows + component-audit
row added + two stale F7.3 paths in 'I want to' fixed). Remaining
warns = links to component-guide.md, which lands in F7.5 (2/2).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/THEMING.md (1499 L, Spanish) translated to English as
docs/theming/reference.md, same s1-s38 numbering: the mental model,
s1.bis (theming lives in eidos — the 2-of-3 derivation and the canonical
split), the CSS layers, the 7 token layers, the 9 roles, the size canon
(universal 1:1 + label step-down + container cap + the icon scale), the
naming conventions, the s7/s8/s9/s13/s15/s17/s18 stubs repointed into the
book (canon/tsc, theming/guide, theming/notes, theming/changelog,
theming/motion), runtime overrides + builders, bundle/purge, validation
tooling, s14 motion (the pickup lift), s16 anti-patterns, s19 variants
canon, and the s20-s38 standing-decision stubs. One internal
reconciliation applied: the s35 stub cited the control/compact/dense size
archetypes that s5 declares superseded by the universal 1:1 — aligned.
One stale v1 DEMO_AUTHORING s12.8 citation in s5 replaced by the v2 s6
parity rule. Stub at the old path carries the full s1-s38 map (the most
sN-cited doc in the repo: code comments, CLAUDE.md, RFCs). Corpus links
swept (CANON, docs map, comparison, glossary, eidos chapter, canon/tsc,
theming/guide + notes). docs:check 0 errors (260 docs).
F7.3 complete: docs/canon/ (tsc, recipe-contract) + docs/theming/
(reference, guide, notes, channels, motion, motion-guide, changelog).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/eidos-motion.md (698 L, Spanish) translated to English, same
s1-s19 numbering: the two-moment thesis, the closed cascade model
(D.11-D.13), motion across the 4 layers, the two-surface registry, types,
the EngineMotion API + cleanup policy, the 5 drivers, the DOM contract
(data-animation-style), Presence integration, reduced motion, primitives/
keyframes, built-in content, per-component defaults, code map, s15 (the
events.css -> signatures migration — cited from events.css), Chakra
comparison, naming, phases F1-F7, deferred. Stub with the full s-map at
the old path; corpus links swept (comparison, eidos chapter, changelog,
motion-guide). docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/TSC.md (334 L) and RECIPE_CONTRACT.md (131 L), both Spanish,
translated to English as docs/canon/tsc.md + docs/canon/recipe-contract.md
(the E2 visual canon inside the book tree). Thin stubs at the old paths
(code comments and component-audit R-4.x provenance keep resolving);
corpus links swept (docs map E2 rows, authoring anti-copy law,
building-a-component phase 5, comparison, getting-started, glossary,
eidos chapter). docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/soma/SOMA_ARCHITECTURE.md (1058 L, Spanish) translated to English
as docs/architecture/soma-architecture.md, same s1-s17 numbering: layer
architecture, design principles, the closed six-piece model + SomaRuntime,
component model (picker composition), runtime parts, the layers inventory,
the Soma class + date/time domain + statics convention, the reactive
system, internal helpers, data-* contracts, IDs, barrels, boundaries,
directory structure, anti-patterns, current shape, stability rule,
checklist. The frozen per-provider test list (dated 2026-05-15, ~140 L)
became the timeless fact: the NO_MISSING_PROVIDER_TESTS guard + the test
tree ARE the coverage inventory (testing-and-tooling aligned). Stub with
the full sN map at the old path; corpus links swept.
F7.2 is complete: docs/architecture/ now holds the whole E1 stratum in
English (7 chapters, ~5.4k lines), with thin stubs + sN maps next to the
code. docs:check 0 errors (251 docs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/README.md (1020 L, Spanish) translated to English: the
ActiveEidos runtime (config/patch, themes, themeSource, CSS contract,
setCssVariables, persistence envelope, resolveToken), canonical size +
transversal primitives, what eidos consumes from morfo/soma/sema, the
--* token rule, the THEMING sN map, typographic vertebration (two
anchors + alias chain + R-2.7), the 2-of-3 rule, disciplined-option-C
API conventions (7+4 rules, Toast special case), the selector-drift
defense, and the picker patterns P-1..P-5. Two already-decided
reconciliations folded in: themes/fonts.css superseded (font-faces live
in generated/base.css) and the dated 2026-05-21 picker block merged into
the picker-patterns intro — its dead PENDIENTES.md pointer replaced by a
TODO(reconcile) note (norms N-6/N-7 orphaned by d68d2c45), which also
clears one docs:check warn (13 -> 12). Thin stub at the old path keeps
THEMING/TSC/motion pointers next to the code; corpus links swept.
docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/active_architecture.md (865 L, Spanish) translated to English as
docs/architecture/active-architecture.md: the s0 module contracts +
canonical naming, the four layers in depth, the transcription chain, the
causal chain of one interaction, the DOM-attribute table, the 12 hard
rules (incl. the sec-dom read-timing rule), authorship vs transcription,
what it is NOT, risks. The dated header changelog block was dropped per
the timeless rule (s10 already routes snapshots to docs/process/); the
stale themes/fonts.css mention in the eidos structure listing corrected
to the generated foundation (phase-6 fact). Stub at the old path carries
the full sN section map (the most sN-cited doc in the corpus). All docs/
corpus links repointed to the chapter. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/README.md (485 L, Spanish) translated to English as the book's
opening chapter. Two already-decided reconciliations applied in passing:
the 'authoritative GUIA' pointer now reflects its historical status
(phase-6 decision) and the frozen 2026-05-17 migration status became the
timeless statement (every component ships an eidos wrapper; inventory =
tree + component:audit). Thin stub at the old path; docs/README entry,
strata table and reading order repointed. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
User decision (2026-07-02): the corpus stops being a MAP over dispersed
layer docs — the layer reference MOVES into docs/ with book order, in
English, superseding the kickoff-era 'hybrid structure' decision. The 189
component READMEs stay in-place (E5, linked).
- docs/process/PLAN-docs-book.md: the phase-7 plan — target tree
(architecture/ canon/ theming/ rfcs/ guides/ decisions/), the per-doc
migration pattern (translate -> Write new path -> stub at old path ->
link sweep -> docs:check -> commit per batch), batches F7.1-F7.7 with
volumes, and the known risks (sN citations get a map in the stub; the
legacy RFC renames finally become safe because the stub keeps the old
name alive for provenance citations).
- Pilot migrated end-to-end: docs/architecture/active-uix.md (English,
frontmatter, links repointed) with a thin stub at
src/uix/active-uix/README.md; docs/README map, glossary and
active_architecture s0 repointed. Validates the pattern for F7.2+.
docs:check: 0 errors (244 docs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
dev