svelte-kit-vice/docs/process/continue-with-stumbles-s2-s6.md

# Continue with — STUMBLES S2–S6 + catalog coherence (hand-off 2026-07-03)

> **Kickoff for a new session**: *"Lee docs/process/continue-with-stumbles-s2-s6.md
> y continúa."* Everything below is verified against the code at commit
> `116594e0`. Working rules unchanged: respond in Castilian, docs/comments in
> English; NEVER touch `words/` `palabras/` `chronos/` `media-player` (foreign
> WIP); commit per batch, `git reset -q` + stage only your own files; commit
> messages via `-F file` (backticks in `-m` run command substitution — see the
> memory note). Each systemic fix ships its guard.

## Where things stand (verified)

- `component:audit`: **82 PASS / 48 NEEDS-WORK / 0 BROKEN**. The remaining
  NEEDS-WORK is almost all **docs completeness** (E-2.3 missing README, F-1.x
  sections) and **demos** (D-*, deferred to the web phase) — NOT functional.
- `npm run check`: ~**64–65 errors**, ALL pre-existing/foreign (heroscrolling +
  animation demos, arts/connection, libs/reactive — the parallel runed/tabbable
  port drifted the tree; my baseline earlier this session was 59). None in the
  maintained catalog files I touched. Confirm with a stash-test if a number
  moves: my changes were net-neutral-to-negative on the count.
- `npm run docs:check`: **0 errors, 11 warnings** (all foreign/known targets).
- `vitest src/uix/eidos`: **289/289 green** (the long-red suite was triaged).
- **Uncommitted foreign WIP in the tree** (do NOT commit): the runed/tabbable
  0-dep port — `src/libs/dom/*`, `src/libs/reactive/index.ts`,
  `src/arts/adom/index.ts`, `package-lock.json`, deleted `CONTINUE*.md` /
  `src/audit-opus-4-6-26.md`. Another session owns these.

## Done this session (committed, on `alpha-0.1-sec-dom`)

- **C7 size-bundle** (`6001d9bb`, `e83ca6ea`): 34 recipes consume the bundle
  coordinate; guard forbids the raw primitive; theming/notes size-canon row ⚠️→✅.
- **Eidos test triage** (`bbd9c467`): 15 long-red tests → 289/289. Real fixes
  inside: pin-input readonly-bg declared, 5 dead tokens removed, time-picker
  `size` clamped to PopoverSize (check 61→59).
- **onion-menu + surface-subtle bug** (`46d68ff2`): default export; and
  `--color-surface-subtle` was a PHANTOM token → table/tree-grid headers
  rendered with no background → repointed to `--color-surface-muted` (verified
  in browser).
- **Functional flags + C10 reframe** (`730812c0`): 4 service E-2.2 exceptions
  (format-date/number, relative-time, trans), alert-dialog R-1.1, card A-1.3.
  **C10 reframed**: tier = audit verdict — stable=PASS (82), preview=NEEDS-WORK
  on docs/demo only (~35, incl. mature button/table — a README gap is not
  immaturity), experimental/WIP=real functional gap or foreign. C10 folds into
  C8.
- **S1 — generated vocabularies appendix** (`116594e0`): `npm run docs:vocabularies`
  → `docs/canon/vocabularies.md` from the consts (STUMBLES #1). New
  `ARCHETYPE_DESCRIPTIONS` in morfo/types.ts; docs-check I7 freshness guard
  (negative-tested); linked from README/CANON/morfo/component-audit.

## NEXT — S2, S3, S4 ALL DONE; re-scope S5/S6 (and wire the Knob)

A read-only scoping workflow (`scope-stumbles-s2-s6`) mapped each against the
real code. S2/S3/S4 returned high-confidence plans (below). **S5 and S6 did the
research but did not emit a structured plan — re-scope them first** (relaunch
the workflow for just those two, or scope by hand; their prompts are in the
committed workflow script `…/workflows/scripts/scope-stumbles-s2-s6-*.js`).

### S3 — `part-absent` morfo condition — ✅ DONE (`11504043`)

Shipped as `{ when: 'part-absent', part }`, the exact inverse of `part-present`,
across the four condition sites (types union + JSDoc, schema discriminated
member, compile `collectConditionDeps`, resolver `shouldEmitMorfoEntry`) plus
schema/compile tests and the `morfo.md` condition list. **One deviation from
the plan below**: the plan claimed `checkCondition` "already covers it (doesn't
discriminate)" — it DOES discriminate (`schema.ts` had `c.when === 'part-present'`
hard-coded), so the unknown-part guard was extended to `part-present || part-absent`
so an unknown-part `part-absent` throws too. `npm run check` = 59 errors (none
mine); the pre-existing red morfo test `hoists role into staticAttrs` (Dialog
`content` role intentionally undeclared, dialog-001) is unrelated → flagged
separately. Original plan preserved below for provenance.

The common ARIA pattern "aria-label only when there is no Label part" is not
declarable. Add the inverse of `part-present`. Four surgical edits + a test,
mirroring `part-present` exactly:

- `src/uix/morfo/types.ts` (MorfoCondition union, ~L169–175): add
  `{ when: 'part-absent'; part: string }`; update the JSDoc.
- `src/uix/morfo/schema.ts` (conditionObjectSchema discriminated union,
  ~L143–153): add `object({ when: literal('part-absent'), part: string() })`.
  The `checkCondition` part-reference validator (~L556–573) already covers it
  (it doesn't discriminate) — no change there.
- `src/uix/morfo/compile.ts` (`collectConditionDeps`, ~L666–681): add the
  `condition.when === 'part-absent'` branch → `partRefs.add(condition.part)`
  (same as part-present).
- `src/uix/morfo/resolver.ts` (`shouldEmitMorfoEntry`, ~L39–50): add the branch
  → `return !Boolean(bindings.parts?.[condition.part])` (inverted part-present
  at L44).
- Test (`compile.test.ts` / runtime test): schema accepts it; unknown-part
  throws; compiler collects the dep; resolver returns the value when the part is
  absent/falsy and `undefined` when present. Integration: a Dialog-like aria-label
  gated on `{ when: 'part-absent', part: 'label' }`.
- **Risk**: semantics are "part not in bindings.parts OR falsy value" (not
  strictly DOM-absent). Verify provider init populates the parts map for every
  part (even optional-unrendered) so absence is unambiguous. Non-breaking (no
  existing morfo uses it).

### S2 — "Continuous components" doctrine in `docs/architecture/sema.md` — ✅ DONE (`1da36ca6`)

Shipped as a new `## Continuous components (drag, swipe, hold)` section after
the emit contract (before `## The per-family intent policy`), covering: the
single `runtime.trigger` door + `void` vs `await` (hold opt-out/in), `coincident`
vs `post` for a moving value (Slider worked example), rAF throttling of
continuous pointer emits vs unthrottled keyboard commit-set, and "a continuous
event's cascade rule must not override the primitives the per-emit `overrides`
control". Every claim adversarially fact-checked against the Slider/Drawer
providers + morfo + sema pack (zero discrepancies). `docs:check` = 0 errors.
Original plan preserved below for provenance.

Pure doc addition, grounded in the REAL Slider/Drawer code (verified answers to
the three open questions):

- **(a) turn hold**: `runtime.trigger()` returns a Promise that resolves AFTER
  emit + the perceptual hold (`runtime.svelte.ts:742–749, 765–768`). `void
  trigger()` = fire-and-forget; `await trigger()` blocks until the hold ends.
- **(b) sanctioned path**: ONLY `runtime.trigger()` — there is NO `emitEvent()`
  in the codebase. Slider uses trigger exclusively (handle-pick L297, handle-drag
  L263/322/330, commit-set L155); Drawer likewise (drag-start/progress/end
  L661/645/679).
- **(c) throttling**: keyboard `commit-set` fires on EVERY keydown
  (`SliderThumbProvider.onkeydown` L485–522) — no built-in throttle. Throttling
  is drag-only, via rAF (Drawer `flushDragProgress` ~88ms L604/624–648; Slider
  `queueHandleDrag` L244–260). The Slider sema cascade for handle-drag sets only
  `channels:['sound','haptic']` and does NOT override pitch/gain, so per-emit
  overrides stay the source of truth (`sema/components/slider.ts:30–32`).
- **Deliverable**: new `## Continuous components (drag, swipe, hold)` section
  after "## The emit contract" (~L121) covering: sequence `coincident` vs `post`
  (perceptual+structural indivisible vs commit-then-signal), route-through-trigger
  doctrine, rAF throttling for continuous gestures, and "a cascade rule must not
  override the primitives that per-emit values control". Slider = worked example.
  Keep prose on the invariant ("what the Promise represents"), point to code for
  tuning constants (don't hard-code ms). Verify with `docs:check`.

### S4 — `Gesture.rotate` layer (STUMBLES #3, the flagged gap) — ✅ DONE (`18b0d44e`)

Shipped in `src/uix/soma/layers/gesture/` as the fourth specialization
(`GestureRotate extends GestureBase`): `angleAbsolute` (0°=up, CW+, [0,360),
CSS-rotate convention), `angleDelta` (seam-unwrapped, multi-turn),
`angularVelocityDeg` (radius-independent via a dedicated tracker fed the
accumulated angle), `AngularSnap` detents (wrap-aware), dismiss-by-degrees,
`center: 'element'|{x,y}`. 9 tests, 0 type errors in the layer. Deviations from
the plan below (all deliberate): angle convention taken from the REAL Knob
consumer (`atan2(dx,-dy)` not `atan2(dy,dx)`); `referenceSize` omitted (no
meaning for a radius-independent angle); `AxialDrag` is in `layers/manipulation`
not the gesture layer (plan conflated it); CW/CCW lock deferred as planned. Two
release-time snap bugs found by adversarial review were fixed pre-merge (px→deg
projection scale + capped below a half-turn; sequential guard made circular
under wrap). **A real consumer now exists AND is wired**: the Fable-built Knob was
relocated out of `src/uix/active-uix/knob/` into its per-layer homes
(morfo/langs/sema/soma/eidos) and rewired to consume `Gesture.rotate`
(`c13cad74`): 162→59 type errors (0 in any knob file), 4 provider tests, no
regressions; morfo now uses the S3 `part-absent` for aria-label; knob added to
`recipe-css-contract` WIP_TRACKS until its recipe tokens land (css still md-only,
no variants — the remaining polish). Original plan below.

New angular gesture layer mirroring the existing ones in
`src/uix/soma/layers/gesture/` (GestureBase → GestureDrag/GestureResize;
AxialDrag is the single-axis peer). Consumers: Knob, AngleSlider, hue ring,
clock dial.

- `layers/gesture/types.ts`: add `RotateState` (angleDelta°, angleAbsolute
  0–360, angularVelocityDeg), `RotateReleaseState` (+snappedTo, dismissed),
  `GestureRotateOpts` (extends GestureBaseOpts: `center` (`Active<{x,y}|'element'>`),
  `referenceSize`, `direction?`, `snapPoints?`, `snapToSequential?`,
  `dismissDegrees?`, `velocityThreshold?`, `wrap?=true`, onRotate/onRelease/
  onDismiss/onSnapChange), `GestureRotateState`, `AngularSnap` (number = 0–1
  fraction of 360 / >1 degrees / `'45deg'`/`'45°'`/`'50%'`).
- `layers/gesture/gesture.svelte.ts`: `GestureRotate extends GestureBase`.
  Center detection (`'element'` → getBoundingClientRect center vs explicit
  coords); angle via `atan2(dy,dx)` normalized [0,360); `unwrapDelta` for the
  0/360 crossing (`|delta|>180 ? delta∓360`); velocity on the unit circle
  (VelocityTracker, 100ms window / 50ms staleness — reuse the existing tracker);
  override handlePointerDown/onMove/onRelease/onCancelled; `snapToAbsoluteDegrees`
  + `resolveSnapAt` with the sequential-neighbour guard (`|i-current|>1` blocked,
  like AxialDrag). Export `Gesture.rotate(opts)` matching drag/resize.
- `layers/gesture/index.ts`: export the new types.
- Test (`gesture.test.ts`): center detection; angle unwrap across 0°/180°;
  velocity (stationary/flick-capped/stale); snap (closest, sequential guard,
  velocity projection); dismissal by absolute offset; single-pointer only.
- **Risks**: 0/360 unwrap correctness (normalize delta to [-180,180] before
  distance in snap, esp. with wrap so 350°↔10° are adjacent); angular velocity
  via unit-circle derivative underestimates at large radii; no CW/CCW direction
  locking in v1 (defer). All dom listeners via `dom.listen` like the peers.

### S5 / S6 — re-scope, then implement

- **S5** (soma→eidos CSS-var contract, STUMBLES #7): the agent researched
  `--drawer-progress`-style vars but didn't emit the plan. Re-scope to get 2–3
  concrete options (e.g. a morfo `cssVars` declaration validated against provider
  writes + eidos reads; or an eidos-lint cross-check of provider-written vs
  recipe-consumed vars) with a recommendation. Design-open — get the tradeoffs
  before implementing.
- **S6** (minor frictions): four doc notes to author from the real defs —
  `state<T>()` vs `$state` (pass-by-ref vs local), `role` on a DOM-rendering
  Provider (required vs omittable), `Without<>`/`PrimitiveDivAttributes`
  definitions, gesture pointermove/up ownership. Land them in soma.md /
  soma-architecture.md.

## After the S-series — remaining coherence plan

`docs/process/PLAN-component-coherence.md` is the master. Left:

- **C8** (heaviest): 28 missing READMEs (E-2.3) + incomplete F-1.x sections.
  This is where the deferred exceptions land: announce/clipboard R-1.5
  (live-region / composed-focus), natural-time-picker R-2.1 (fixed-tone sky) +
  A-3.1, card/card-group/drag-drop/virtual-list. Write real Baseline/Comparativa/
  Decisiones/Gaps (per-component reference research) — no skeletons.
- **C9**: motion eventful gap (which interactives should express an event
  signature; criterion: high-frequency = sober, D.5).
- **Real gaps tracked, NOT silenced**: float-panel **A-3.7** (28 mutating
  keyboard actions, 6 events — morfo-completeness question); **card-group** has
  no morfo (morfo-first violation, `KNOWN_MISSING_MORFO` in lint.test.ts);
  natural-time-picker **A-3.1**.

## Verify-before-done checklist (unchanged doctrine)

`npm run check` (compare to the drifting foreign baseline, not 59) · relevant
`vitest` scope · `component:audit --only {kebab}` per touched component ·
`npm run docs:check` after doc/vocab changes · browser check for anything
visual (Playwright from repo-root; the preview MCP is flaky — memory note).