# Architecture — @dolphinspired/solid-stage

This is the canonical record of the library's architectural decisions: the
load-bearing principles, the cross-cutting systems, every primitive's design,
and the gotchas worth not relearning. It is both reference and roadmap.

**Read this before adding a feature; update it whenever an architectural
decision is made.** When a change touches the public API, update `README.md`
too.

`@dolphinspired/solid-stage` is a small library of Solid + Three editor-chrome
primitives, extracted from `osrs-engine-study` and `3d-model-exporter` after
both independently grew the same shape.

---

## 1. Architecture thesis

The load-bearing principles. Everything else is downstream of these; a new
feature that violates one is almost certainly wrong.

1. **Pre-composed children, not registries.** `EditorPanels` takes
   `leftPanel?: JSX.Element`, not `leftSections: SectionId[]`; `Section` takes
   `children`, not a field schema; every bar is a pre-composed `Toolbar` (or
   plain JSX), not a bar config object. Naming the collapsible container
   `Section` does **not** imply a section registry / id-keyed lookup — that
   mapping is app-specific. Composition stays child-based throughout.

2. **Controlled + uncontrolled, mirrored everywhere.** Anything with state
   (collapse, active tab) accepts optional `open?: () => boolean` + `onToggle?`
   with an `internalOpen()` signal fallback. Canonical accessor:
   `isOpen = () => props.open?.() ?? internalOpen()`. In uncontrolled mode the
   internal signal seeds from / writes back to localStorage where a primitive
   persists (`Section` collapse, panel collapse); controlled mode leaves
   persistence to the parent (never caches).

3. **CSS classes + variables, no inline styles.** Every classname is `stage-*`.
   Every dimension and colour is a CSS custom property on `:where(.stage-root)`.
   Consumers override by setting variables on any container. The library never
   writes `!important` — `:where()` (specificity 0) lets consumer overrides win
   without it. The library ships no inline-`style` escape hatch; the style hook
   is a `class` prop (e.g. `Label`).

4. **Bundled curated icon set + consumer-supplied icons.** The library ships a
   small, curated subset of **Phosphor** icons as a tree-shakeable subpath export
   (`@dolphinspired/solid-stage/icons`), generated from the `@phosphor-icons/core` dev
   dependency into `src/icons/generated/` (committed; codegen in
   `scripts/gen-icons.mjs` driven by the `scripts/icons.json` manifest). Phosphor
   glyphs are **filled vector shapes** (not strokes, viewBox 256), so they
   anti-alias cleanly at small chrome sizes — the reason we moved off lucide, whose
   thin strokes softened at 14–16px. The codegen's **default weight is `bold`** (a
   single caret reads thinner than a double at the lighter weight; bold evens the
   chrome out); a manifest entry overrides per icon via `@weight` (`circle@fill`).
   The set spans library chrome glyphs **plus common editor-app icons** (copy,
   lock, eye, trash, …) so consumers — and the playground — reach for icons without
   a separate package. Each is a `Component<{ size?; class? }>`
   carrying a `stage-icon stage-icon-<name>` class, so it sizes off
   `--stage-icon-size` (the `.stage-icon` base rule) and is addressable in
   CSS/tests. Library chrome renders these (collapse/disclosure carets, close `X`,
   `Plus`, the modified-tab dot as a fill-weight `CircleFill`, scroll/step carets)
   — no hand-rolled SVGs or unicode glyph affordances, and no house icons (the
   `fill` weight gives a real solid disc). The artwork is vendored under Phosphor's
   MIT licence; the notice is retained in `NOTICE` (shipped in the package).
   Icon-*button* components take an `IconComponent` prop so consumers can pass
   their own icons (any `Component<{ size? }>`) — never hard-`import` an icon set
   or a styling helper (incl. `clsx`) in library source.
   **Scope boundary (the line for "add this icon?"):** a glyph is bundled only
   when a library *component* renders it, plus the small band of generic
   editor-app icons already shipped. **Domain icons stay consumer-supplied** —
   media-transport (play/pause/skip), app-specific marks, rotation-axis arrows,
   etc. There's no principled stopping point once we bundle for one consumer's
   feature, and the `IconComponent` / thunk contract already lets a consumer pass
   any icon at zero maintenance cost; a curated Phosphor subset we hand-maintain
   for every use case would be strictly worse than the consumer importing
   `lucide-solid` directly. A domain glyph earns a slot only if/when a library
   component starts rendering it. (Surfaced by the dsts-viewer media-transport
   request, 2026-06-18 — declined for bundling on this basis.)

5. **Browser-only.** `ResizeObserver` + `getBoundingClientRect` are not
   SSR-safe. Documented in `README.md`. Do not add SSR shims or `typeof window`
   dances beyond the one `typeof ResizeObserver !== 'undefined'` guard.

6. **The chrome is centre-agnostic; the *world* is a canvas.** `EditorPanels`
   takes an arbitrary `center: JSX.Element` — the chrome could host any middle
   (DOM page-builder preview, code buffer, node graph). Do **not** narrow
   `EditorPanels` to canvases. But `CanvasStage` and the focus model that treats
   "the world" as a single non-tabbable boundary *are* canvas-specific: the
   multi-layer world/HUD/pointer z-stack + viewport ResizeObserver describe a
   viewport onto a continuous spatial scene. The tell: the moment a centre is
   *editable DOM* it stops being "a world" (an opaque region you never tab into)
   and becomes the primary tabbable content — which inverts the focus model. So
   wherever the focus/Tab design needs an answer for the centre, assume a
   canvas; everywhere structural, keep the centre open.

### Scope discipline

A feature that lives in only one consumer stays consumer-side until a **second**
consumer asks for it (the field framework cleared that bar — both apps had
grown it). Everything else is consumer-side or deferred; see
`docs/feature-ideas.md` for the deferred list. Resist scope creep.

---

## 2. Theming & class conventions

- **`.stage-root` is the token scope.** All `stage-*` custom properties are
  declared on `:where(.stage-root)`. Anything that must read those tokens has to
  live inside a `.stage-root` subtree.
- **Portalled content mounts into the nearest `.stage-root`**, not
  `document.body` — otherwise tokens don't resolve and consumer overrides don't
  cascade. It also escapes panel `overflow` clipping and sits above chrome via
  `--stage-z-popover`. The modal extends this: lookups are
  `.closest('.stage-root, .stage-modal-container')` so fields opened *inside* a
  modal portal into the container (see §7).
- **Resolve the portal mount at *open* time, not once at mount.** `SelectControl`,
  `ColorControl`, and `SearchControl` each `.closest('.stage-root, …')` off their
  trigger/input to find the mount target. Caching that once in `onMount` is a trap:
  on mobile WebKit `onMount` can fire before the trigger is spliced under
  `.stage-root` (first seen when `Panel` still detached collapsed bodies), so
  `.closest` returns `null` and it falls back to `document.body`. Cached, the dropdown
  then portals outside the token scope forever (transparent bg, UA-black text, no
  overflow scroll) until a remount.
  The fix: keep the `onMount` resolve to prime the common case, but **re-resolve on
  every open** (`onOpenChange` for Kobalte Select/Popover; the `panelOpen` effect
  for the hand-rolled Search panel) — the trigger is always connected and laid out
  by then. Desktop hid this (insertion beats `onMount` there). Guarded by a
  mount-outside-then-move-under-root test.
- **The surface ramp derives from one root, parent-by-parent.**
  `--stage-color-bg` is the single root background the whole grayscale ground keys
  off. Each surface/border token mixes off its *logical parent*, not flat off the
  root: panel lifts off bg, popover = panel, header darkens off panel,
  header-hover lifts off header, border lifts off panel, border-strong lifts off
  border, border-hover lifts off strong, the input well darkens off panel,
  control-hover (the shared hover fill) lifts off the well, readonly lifts off the
  well. Same
  `color-mix` pattern as `--stage-color-accent-readonly` and the tooltip skins;
  each token stays individually overridable, so retinting one parent flows to its
  children while pinning any single token stops the chain there. The accent family
  (`--stage-color-accent` + `-readonly`/`-on-accent`/`-text-on-accent`/
  `-icon-on-accent`) is the separate "primary" axis and does **not** derive from bg.
- **Surface colours are opaque — no alpha.** `--stage-color-modal-backdrop` is
  the one intentionally translucent token (a scrim must let the dimmed page show
  through). Every other background is a solid, legible colour; don't reintroduce
  alpha into the ramp.
- **Foreground text derives from one base, like the surfaces.** Three tiers
  (`--stage-color-text` / `-text-label` / `-text-muted`); label + muted mix off
  `--stage-color-text` (darkened toward black), so retinting the base text colour
  carries the whole type-colour scheme.
- **Content on an accent fill has its own colours, defaulting to the text colour.**
  `--stage-color-text-on-accent` (the "on"/active button label, the highlighted
  dropdown option, the active search row) and `--stage-color-icon-on-accent` (icons
  in those spots, defaulting to `-text-on-accent`) both **default to
  `--stage-color-text`** — so the default mid-dark accent is unchanged, but a theme
  with a **bright accent + light text** overrides them to a dark colour without
  touching every rule (the legibility gap that surfaced in a bright-accent
  consumer). Distinct from `--stage-color-on-accent`, which is *not* part of the
  text group: it's the bright fill for the **decorative** switch thumb / checkbox
  tick (a knob/check that reads best at full contrast regardless of theme), pinned
  to contrast the accent, not the text.
- **Icons carry a colour token too.** `--stage-color-icon` defaults to
  `currentColor` so a bundled `.stage-icon` matches its surrounding text and any
  context that sets its own colour (the accent info bubble, the select indicator)
  still wins — `.stage-icon`'s rule loads in `base.css`, before every consumer of
  it. Set the token to recolour all icons at once; `-icon-on-accent` handles the
  accent-fill case. No glyph-colour hover shift anywhere by design — section
  headers are flat (their former hover-brighten was dropped when the chevron became
  the collapse control and the rest a drag grip), so don't add a
  `--stage-color-text-hover` nothing consumes. (`--stage-color-section-header-hover-bg`
  survives only as the close button's press-flash, not a header hover.)
- **`--stage-colorpicker-*` is dimensions, not colour.** The ColorField popover's
  width/area/track/thumb sizes use the `colorpicker` stem (no hyphen after
  `color`) deliberately, so a `--stage-color-*` grep for themeable colours skips
  them. Don't reintroduce a `--stage-color-picker-*` form.
- **Corner rounding is one derived knob.** `--stage-border-radius` (default 2px)
  is the base control radius (inputs, the select trigger, accents — badges,
  checkbox, slider track/fill, colorpicker area/track — and focus outlines);
  `--stage-border-radius-lg` (`calc(× 2)` → 4px) covers the button family, the
  tooltip, and the select/search dropdowns; `--stage-border-radius-modal`
  (`calc(× 4)` → 8px) the modal. Set `--stage-border-radius: 0` for a fully-square
  aesthetic, or override `-lg`/`-modal` directly to decouple. Pills/circles
  (slider/switch/colorpicker thumbs, the switch track) are intentional *shapes*
  (`50%` / `9999px`), not corner-rounding, and don't derive. Flush-joined controls
  (ColorField hex+swatch, SearchControl input+stepper) square their inner seam and
  round only the unit's outer corners so the radius reads as one pill.
- **Class taxonomy:** `.stage-field-*` is the shared row/layout vocabulary;
  `.stage-{type}-*` is one control's own internals; a trailing segment is a
  state/variant modifier (`-active`, `-on`, `-center`).
- **Z-index tokens:** `--stage-z-popover` (1000) < `--stage-z-modal` (1050) <
  tooltip (1100). The modal backdrop's `--stage-z-modal` opens a stacking
  context lifting the whole modal above page-level popovers while keeping a modal
  field's tooltip on top.
- **Motion derives from one base, like the surfaces.** `--stage-motion-duration`
  (0.18s) + `--stage-motion-ease` (ease) are the base knobs; each animated
  interaction has its own `--stage-*-motion` token — a `<duration> <easing>` pair
  fed straight into `transition` — that derives from the base
  (`--stage-panel-motion`, `--stage-section-motion`, `--stage-toast-motion`). A
  consumer retunes all motion by overriding the base, or one interaction by pinning
  its own token; setting any duration to `0s` disables that motion. Animations are
  **on by default**; `@media (prefers-reduced-motion: reduce)` zeroes
  `--stage-motion-duration` (in tokens.css), collapsing every derived transition to
  instant. The tooltip predates this and keeps its own `--stage-transition-fade` +
  reduced-motion block (§7) — don't fold it in. The three animated interactions:
  **Panel** collapse transitions `grid-template-columns` on `.stage-panels` (the
  strip↔expanded column track slides; only columns animate, rows snap) — the panel
  box fills its track (`width:100%`, `overflow:hidden`) while `.stage-panel-inner`
  holds the true width pinned to the pane's outer edge, so the body slides in and
  out clipped rather than reflowing. **Section** collapse uses the
  `grid-template-rows: 1fr↔0fr` height trick on `.stage-section-collapse` (the
  `.stage-section-body` grid item carries `overflow:hidden`/`min-height:0`, padding
  lives one level in on `.stage-section-body-content` so the row reaches a true
  zero); the body is also `inert` when closed — that, not `display:none`, is now
  what drops collapsed content from the tab order + a11y tree (compatible with the
  height animation, and `focusField` clears it on expand). **Toast** slides+fades
  via opacity/transform between a resting state and an edge-offset
  `.stage-toast-enter`/`.stage-toast-leaving` state (offset direction keys off the
  host placement); the exit is two-phase (§7).

---

## 3. Sizing — the type-scale tier system

The library **owns the type scale**: row height is a deliberate,
font-size-coupled primitive, not the emergent "whichever control is tallest" it
once was.

### The two coupled tokens
- `--stage-font-size` — base field font-size. The library sets its own; it no
  longer `font: inherit`s size from the consumer.
- `--stage-control-height` — the row / control-height every field row and tall
  control snaps to.

They are **coupled** (a 1px hairline border doesn't scale with `em`), so they
ship as hand-tested **discrete tiers**, not a `height = font × k` formula:

| Tier | font / height | Selector |
|---|---|---|
| `small` | 11px / 16px | `.stage-size-small` |
| `normal` (default) | 13px / 20px | unclassed `:where(.stage-root)` |
| `large` (= touch) | 16px / 24px | `.stage-size-large` |

Preset classes are plain-specificity (beat the `:where()` 0-specificity
defaults without `!important`); raw tokens stay overridable for retuning.

**Typography split:** font-*family* is 100% consumer; font-*size* is a
library-owned knob (the tier) because layout is downstream of it — an off-tier
font-size forfeits the row-height guarantee.

### How each part snaps to the tier
- **Compact + bar rows:** `min-height: var(--stage-control-height)` +
  `align-items: center` — short controls (boolean / checkbox / slider / icon)
  centre in the row rather than shrinking it.
- **Tall controls** (`.stage-input` text/number/colour-hex + `.stage-select-trigger`):
  pin `height: var(--stage-control-height)`.
- **Short controls scale via tokens derived from control-height** (matching
  today's `normal` values): `--stage-checkbox-size` + `--stage-slider-thumb-size`
  use a constant `control-height − 6px` inset (14px at `normal`; an even inset off
  the even control-height so they integer-centre in the row); the switch
  derives width/thumb/travel from `--stage-switch-height` (`control-height − 5px`);
  the slider's rail thickness is `control-height / 3.5`, its label allowance is
  in `ch` (tracks font-size) and its thumb-clearance gap is thumb-derived.
  - **Exception — booleans don't shrink at `small`.** The switch / checkbox value is a
    single glyph, so shrinking it past `normal` costs legibility for no density gain.
    `.stage-size-small` pins `--stage-checkbox-size` / `--stage-switch-height` back to
    their `normal`-tier px (so the switch width + thumb re-derive); the label still
    shrinks off `--stage-font-size`, so a small boolean row is a smaller label beside a
    normal-sized control. `normal` / `large` are unchanged.
- **The whole button family** joins the grid: shared `.stage-button` base is
  `box-sizing: border-box`, each skin sets `height: var(--stage-control-height)`
  with vertical padding 0 (horizontal kept). The base owns the button font —
  `font: inherit` (family) + `font-size: var(--stage-font-size)` (tier) — so
  button text *and* a text button's content-driven width scale with the tier
  (no width set on text buttons; `fill` / `width: 100%` opts into stretch).
- **Icon buttons are square at control-height** (`width = height`; the old
  `sm`/`md` width split is gone — classes kept for API compat, now equivalent).
  The glyph is sized by `--stage-icon-size` = `control-height − 4px` → 12 / 16 /
  20px at small / normal / large. The control-heights are all **even** (16/20/24),
  so an even-inset icon always integer-centres in the square button (content box
  `ch − 2px` border, icon `ch − 4px` → exactly 1px each side, no sub-pixel lean —
  the reason the tiers are even). Applied via `.stage-button svg` (CSS overrides
  the icon's own attrs).
- **Section header is one control-height** (`min-height`, horizontal-only
  padding) so it lines up with its field rows. Styled as *a field label rendered
  bold* — `--stage-color-text-muted`, `--stage-font-size` (tier), `font-weight: 700`.
  Header height + font read the *inherited* (panel) tier, so a section re-tiering
  its own body never resizes its header.
- **One bar height derives from control-height:** `--stage-bar-height: calc(control-height + 8px)`
  is the single height EVERY bar snaps to — toolbars, the title bar, the tab menu,
  sub-bars. It's **border-inclusive**: each bar is `box-sizing: border-box` so its
  1px separator is absorbed (no off-by-one between a `TitleBar` and a toolbar-stack
  row). The bar **component** carries the height now, not the slot: `.stage-toolbar`
  and `.stage-title-bar` each set `min-height: var(--stage-bar-height)`. The
  full-width `.stage-top-bar`/`.stage-bottom-bar` slots are **transparent** cells
  that only stretch their child to fill width (see TitleBar below) — they no longer
  enforce height or paint a background. A custom bar host (e.g. a TabMenu wrapper
  that isn't a Toolbar) opts in with `min-height: var(--stage-bar-height)` +
  `box-sizing: border-box`.
  (Replaced the old `--stage-toolbar-height`; the unused `--stage-top-bar-height` /
  `-bottom-bar-height` / `-sub-pane-height` fixed tokens were removed.)
- **Expanded fields** ≈ 2 control-heights + gap (the `.stage-field-name-row`
  pins one, the value control below pins another).
- **Wrapping value controls tile to whole control-heights:** `.stage-icon-row`
  (expanded IconButton/IconToggle) wraps with `row-gap: 0`, so K buttons over M
  lines occupy exactly M × control-height (horizontal `column-gap` unchanged).
- **TextareaField is exempt** — multi-row by design, sized by its own
  `--stage-textarea-{min,max}-height`.

### The cascade & the `size` prop
The three tier tokens inherit, so setting a tier (a `.stage-size-*` class or the
raw token) on any element resizes everything inside it; a nested element can
re-tier to override its ancestor. This is the whole cascade — stage → panel →
section → field, plus bars — for free.

`size?: ControlSize` (`'small' | 'normal' | 'large'`) exposes it at three
levels:
- `EditorPanels.size` (whole stage, the `.stage-panels` root); `leftSize` /
  `rightSize` forward into the internal `Panel`s (consumer composes panels via
  `leftPanel`/`rightPanel`, not a `Panel` directly).
- `Panel.size` (header + sections + fields).
- `Section.size` — **applied to `.stage-section-body`, not the section root** — so
  it resizes the section's *fields* while the header keeps the inherited *panel*
  size (an info-dense section can go `small` without its header falling out of
  line). This body-scoping is why no structural change was needed.

Helper `layout/size.ts` `sizeClassList(size)` returns a 3-key classList fragment
(all keys present so Solid's diff swaps tiers reactively); spread into a
`classList`. `.stage-size-normal` exists as a reset because the default is
*unclassed*, so a subtree under a small/large ancestor needs an explicit class
to return to normal.

### The derived-token cascade gotcha
The control-derived tokens (switch/checkbox/slider/icon) are declared on a
**selector list** (`:where(.stage-root), .stage-size-{small,normal,large}`,
mirrored in the touch media), **not just the root**. A custom property's `var()`
is substituted at the element where it's *declared*, then the resolved value
inherits. Declaring `--stage-switch-height: calc(var(--stage-control-height) − 5px)`
only on the root would freeze the inner control-height at the root's value, so a
subtree `size` override would resize the row + direct-use controls
(text/number/select height, label font — these read the tokens directly at the
use-site) but **not** the derived-token controls (switch/checkbox/slider/icon) —
the label would shrink while the toggle stayed put. Re-declaring per tier
re-resolves each at its own control-height. (So a *raw* `--stage-control-height`
override on a non-`.stage-size-*` element only resizes the direct-use controls;
use a `.stage-size-*` class / `size` prop to move everything.)

### Root font size

`.stage-root` and the tier classes set `font-size: var(--stage-font-size)`, so custom markup
reads at the tier's size rather than the page's. The library's rows set it themselves anyway.
The playground must not set a body font size, because that hides any gap here.

### Touch-device input bump (iOS zoom)
iOS Safari auto-zooms (and won't cleanly zoom back) on focus of a text input
whose computed font-size is under 16px — it reads the *real* computed size, so
there's no faking it smaller. `fields.css @media (pointer: coarse)` bumps just
`.stage-input`'s **font-size** to `--stage-font-size-touch` (16px) so focusing
one never zooms the viewport.

Deliberately **narrow** — three earlier-rejected over-corrections inform the
shape:

- **Font only, not the whole tier.** Only the focusable text inputs zoom (not
  buttons / select trigger / slider / checkbox), so only they need the bump. The
  row, label, bar height, icons, and panel width stay dense.
- **No row growth.** A bare 16px font would clip in the 20px control-height box
  (content = 20 − 2px border − 4px padding = 14px). Single-line inputs also pin
  `line-height: 1` and `padding-block: 0`, so 16px seats inside the *unchanged*
  row (18px content) — no reflow, no clip. (Textarea is excluded from that rule:
  it's multi-row and grows.)
- **`pointer: coarse`, not `max-width`.** The zoom is a *touch-device* problem,
  not a narrow-window one — a desktop window dragged narrow shouldn't fatten its
  inputs. (An earlier `max-width: 640px` version also wrongly set
  `--stage-bar-height` on the field *row*, an ancestor-cascade dead end — the bar
  never saw it.)

The **`small` tier opts out**: a 16px line can't fit a 16px-tall bordered row, so
`.stage-size-small .stage-input` reverts to its dense size and *accepts* the zoom
— a conscious tradeoff for a UI that chooses small inputs on touch (the revert
rules sit after the bumps and win on source order at equal specificity). Per
control, `touchSizing={false}` adds `.stage-touch-sizing-off`, which the bump
selectors exclude (`:not(.stage-touch-sizing-off)`); the shared `TouchSizingProps`
+ `touchSizingClassList` (`controls/touchSizing.ts`) thread it through the five
input-bearing controls (text / number / textarea / color / search) and wrappers.

### Narrow stage: one side panel at a time
`EditorPanels` closes one panel rather than letting two open panels clip off a narrow
stage (a phone). On by default (`exclusiveWhenNarrow`), since a clipped panel is never
wanted; codified from dsts-viewer, which built the same rule by hand.
- **Fit test:** left expanded width + right expanded width + `minCenterWidth` (320) ≤
  stage width, the same in either `PanelMode`. Widths are measured off each panel's
  `.stage-panel-inner`, which keeps its expanded width while collapsed, so tier tokens and
  dragged widths count without a px number in props. An unmeasured stage (0 width, no
  `ResizeObserver`) counts as roomy, so headless tests see no change.
- **Opening closes the other side first, inside one `batch`.** Solid runs effects on each
  write outside a batch, so opening first would let the crowding effect see both open and
  close the right panel, possibly the one just opened.
- **Both open anyway → the right one closes.** This is re-checked on mount, on a
  `ResizeObserver` over the root and both inners, and when either collapse state changes.
- **Exclusivity only, no auto-overlay.** dsts-viewer also switches panels to overlay when
  cramped; the library leaves the mode to the consumer.

### Text assistance off; Enter is "done" on single-line inputs
- **No spellcheck / autocorrect / autocapitalize / autofill on any text input.**
  Editor values are identifiers, not prose. Number gets these from Kobalte's
  defaults (plus a numeric keyboard, where capitalization is moot); text /
  textarea / color / search set them by hand. Search also needs it
  because its input text is transparent at rest, but the spellcheck underline
  still paints through.
- **Single-line inputs label the Enter key** (`enterkeyhint`): `done` on text /
  number / color, `go` on search (Enter picks the highlighted result). Without a
  hint, the on-screen key is a grey "return", which suggests a newline. Textarea
  is the one place Enter is a newline.
- **A touch-started session releases focus on Enter** (and, for search, on a
  pick by tap). Desktop keeps focus so the Tab flow and search's committed rest
  survive, but a focused input keeps the on-screen keyboard open. One shared
  helper, `createTouchKeyboard()` (`controls/touchKeyboard.ts`), owns the rule.
  Arming is per session, not per device: a `touch`/`pen` pointerdown arms it
  and blur disarms it, so a keyboard tab-in on a touch device (an iPad with a
  keyboard) still keeps focus. Check `=== 'touch' || 'pen'`, never
  `!== 'mouse'`: synthetic and some real pointer events carry an empty
  `pointerType`. Enter during IME composition is ignored. Color keeps its own
  Enter handler, which blurs on every device because Enter also closes its
  picker.

---

## 4. Focus & keyboard model

- **Focus indicator is white, not the accent** (`--stage-color-focus`, default
  `#ffffff`, consumer-overridable). A pink (accent) ring blends into
  accent-filled controls, so focus is intentionally accent-independent.
- **The white focus border is the TOP of an explicit border-state hierarchy, enforced
  with CSS cascade layers — for value controls AND buttons.** A control's border shows
  several competing colours — resting, a hover lift, a checked/active accent, a readonly
  dim, an error/warn validation flag, and the white focus border. Rather than juggle
  selector specificity (fragile, and it caused the old hover-erases-focus bug), the
  precedence is declared once in `fields.css` as an ordered layer list — a later layer
  wins over an earlier one *regardless of specificity*:

  ```
  @layer stage-cb-rest, stage-cb-hover, stage-cb-selected, stage-cb-readonly,
         stage-cb-validation, stage-cb-button, stage-cb-focus;
  ```

  So for value controls, **focus ▸ validation ▸ readonly ▸ selected ▸ hover ▸ rest**. The
  white active-control border overrides every other border state while focused; because
  each state's selector (`:focus`, `[data-stage-level]`, `[data-checked]`, …) only matches
  while that state holds, the cascade **falls back to the next-highest matching layer the
  instant a state clears** — tabbing out drops `:focus`, so a still-invalid field restores
  its error border with zero extra code. `readonly` sits above `selected` so a
  checked+readonly toggle dims instead of staying bright; a disabled control isn't
  focusable/validated, so its position below those never bites.
  - **Value controls use the fine-grained tiers; buttons fold in via one
    `stage-cb-button` layer.** A value control's state set is small and semantic, so it
    tiers cleanly. A button's border cascade is skin-driven and mature (subtle overrides
    active, tone variants, ghost overrides the action hover, on-toggle overrides toggle
    hover), already correct by specificity + source order — so it's kept **verbatim in one
    bucket** between `validation` and `focus`. Folding it into a layer changes exactly one
    thing: the `focus` layer now overrides every button state too, so a focused button
    shows the white border regardless of hover/active and restores its skin border on blur
    — the same rule every control follows. A borderless button's transparent rest border
    simply recolours white; the mouse-only `untabbable` buttons are excluded
    (`:not(.stage-button-untabbable)`) and show no cue.
  - **The layers own only `border-color`.** Each control sets its border *width/style* in
    its own (unlayered) rule and its resting *colour* in a layer — never a `border:`
    shorthand or an unlayered `border-color`, either of which would beat every layer
    (unlayered always wins over layered) and break the hierarchy. Hover for the value
    controls is fill-only (never touches the border); only the select trigger lifts its
    border on hover, via the `hover` layer.
  - **The colour field folds in as one box.** It reads as a single input (a hex box +
    a swatch tile), so its hex↔swatch **seam is dropped** (the hex loses its right
    border, the swatch its left) and the hex's three borders + the swatch's three form
    one continuous perimeter. Both segments' colours join the layers (the hex is a
    `.stage-input`, already there; the swatch's rest/readonly/validation and the
    coordinated `:has()` focus highlight are added to the matching layers), so the whole
    unit recolours together — border-strong at rest, error/warn when the hex is invalid,
    white when the hex is focused or the picker is open.
  - **Joined controls (input + attached action buttons) coordinate the seam.** An
    input-action button shares each seam with the previous element (`border-left: none`,
    so the seam *is* the previous element's right border). On focus it whites its own
    three drawn borders, and the seam it borrows is whited on the previous element by two
    coordinated `focus`-layer rules: the button↔button seam via a direct-sibling
    `.stage-input-action:has(+ .stage-input-action:focus)`, and the input↔first-action
    seam via a wrapper scope (`:is(.stage-input-group, .stage-search):has(.stage-input-action:first-child:focus) .stage-input-grouped`
    — the search input nests inside `.stage-search-field`, so scope, not a sibling
    combinator). The input's own focus already whites its right seam edge. So a focused
    segment shows a complete white outline with **real border recolour** — no box-shadow
    ring anywhere. (The same pattern would extend to any future joined group: a focused
    segment claims the seam it borrows.)
  - **Not in the border system at all:** the **glyph micro-affordances** (info icon,
    scroll hint, search-clear) and **tabs** keep their own lighter-weight cue (an offset
    outline / accent bar), by design — they're not bordered controls.
- **Every interactive spot resolves to exactly one affordance: it either lights up
  on hover (preferred) OR takes the hand cursor (`pointer`) — never both, never
  neither.** The rule is keyed off *what a click does*: if clicking there produces a
  stage change, the spot must advertise it one way. Lighting up is the default (a
  desktop editor's pointer stays a plain arrow); the hand cursor is the fallback for
  a spot where a hover lift reads unclearly.
  - **Lights up (arrow cursor + `:hover` brighten):** the button family, popover
    triggers (select / colour-swatch), menu option rows, and tabs — each a `:hover`
    lift off the **one shared fill** `--stage-color-control-hover-bg` (plus
    `--stage-color-border-hover` on bordered ones), so the "lit" state is uniform and
    reads clearly against the panel. Also the **boolean/range value controls**:
    switch + checkbox brighten on hover (off → the neutral hover tone; on → the accent
    lifted toward white via `--stage-color-accent-hover`) **including while checked**,
    because a click there turns them OFF — a real change; and the slider lights its
    **thumb** whenever the bar is hovered (the grabbable knob is the affordance), to a
    tone a step below white. These three hover-brighten the **fill only, never the
    border**, on purpose: the border carries the control's *state* (a checked/accent
    fill, an error/warn validation colour, the focus border), so leaving it to hover
    would fight those — the fill lights and whichever border the state hierarchy picks
    stays. That hierarchy (the cascade layers above) is exactly what keeps hover and
    the focus/validation borders from clobbering each other. The slider fill stays
    below pure white so that white focus border reads against the lit knob. An **active
    toggle that untoggles** — `IconToggle` / `IconToggleField`, both of which turn a
    pressed button OFF on click — likewise stays lit while active (marked with the
    `stage-icon-button-untoggles` class → an active-`:hover` brightens the fill to
    `--stage-color-accent-hover`, per tone).
  - **Hand cursor (`pointer`, no hover lift):** the **collapse affordances** — the
    static section-header toggle, the section chevron button, and the panel collapse
    bars (header / edge / collapsed-strip) — and a **module (section) header's action
    icons** (the subtle glyph-brighten alone read as *no* affordance, so these take
    the pointer instead and drop the hover styling; their active-fill + press-flash
    still show as state). A pointer is the strong native convention for "click to
    collapse", so these stay flat + pointered. The **colour swatch** joins this group:
    it opens the picker popover on click and doesn't hover-brighten (it lights only
    while the picker is open), so `cursor: pointer` is what signals "click to open".
    The **info icon** is the one control on `cursor: help` — it isn't a stage change
    at all, it reveals a tooltip, so the help cursor is its honest hint.
  - **Neither (no change on hover):** a **radio-style active option** — a
    `ButtonGroupControl` option matching `value()` — because re-clicking it does
    nothing; only its *inactive* siblings light up. This is the one case that reads
    as "already selected, no-op", so it deliberately advertises nothing. (Contrast
    the untoggling toggles above, which DO change on re-click.)
  - Menu rows keep their accent `[data-highlighted]`/`aria-selected` bar; the
    glyph-only micro-affordances (scroll hint, search-clear ×, info icon) stay on
    their lighter-weight brighten by design. Disabled/`data-disabled` states resolve
    to `default`. Grab/resize/move affordances keep their `grab` / `col-resize` /
    `ew-resize` cursors — including the **section drag-handle title**, now a pure
    `grab` move handle (it no longer doubles as a collapse target; the chevron is the
    sole collapse control).
- **`:focus`, not `:focus-visible`, on every value control** — the cue shows on
  click *and* tab, deliberately. In dense editor chrome a persistent "you are
  here" marker makes the next Tab predictable and doubles as "last thing I
  touched". (macOS Safari/Firefox don't focus `<button>`s on click, which would
  make the button ring keyboard-only there, so `BaseButton` forces `focus()` on
  click; value fields focus on click natively everywhere.)
- **Section header is the deliberate `:focus-visible` exception** — a structural
  section toggle, not a value you tab between; a lingering full-width ring on
  every click would be noise (the chevron already signals open/closed). Borderless,
  so its cue is an *inset* outline (`outline-offset: -1px` — a real border would
  shift layout and fight the open/closed bottom-border divider).
- **Space + Enter both activate** every toggle/button-like control. Section
  headers + IconButton/ActionButton/ToggleButton are native `<button>`s (free).
  `BooleanField` sits on a native checkbox (Space toggles, Enter doesn't), so it
  adds an Enter→toggle `onKeyDown` (no-op when readonly).

### Stage-wide tab order
Keyboard tab order is **native, not a registry**: a section header toggle is a
`<button>` and a section body only renders when open — actually mounted-but-`inert`
when collapsed — so DOM-order tabbing already gives `toggle → its fields → next
toggle`; a collapsed (inert) section tabs straight to the next header;
reorder-proof (native reads live DOM). Header *action* icons are mouse-only
(`tabindex=-1`), so they're skipped.

The whole stage flows in one natural traversal because `EditorPanels`'s DOM source
order *is* the target order: top bars → left panel → centre (canvas-aligned
sub-bars + the centre content, including any **nested stage**, recursively) →
right panel → bottom bars. Panels no longer trap Tab at their edges — focus flows
panel → centre → panel like any DOM. A **nested stage** nests in place: its full
cycle sits between the parent's left and right panels, so the parent's right panel
comes after the child's last stop. (DOM order equals tab order because the library
never uses a positive `tabindex` — only `0` / `-1`.)

The custom layer is small:
- Chrome is removed from the tab order (`tabindex=-1` on the expanded chevron +
  both scroll-hint buttons). The **collapsed-strip button stays tabbable** so a
  keyboard user can still expand a closed panel.
- The scrollable `.stage-panel-body` is itself `tabindex=-1`: browsers that make
  scrollable regions keyboard-focusable (Chrome 127+, Firefox) would otherwise
  insert a phantom stop there, before the first section. Our fields are the stops.
- Tabbing to a field below the fold must bring it into view. Native focus-scroll
  is unreliable for nested scrollers, so an `onFocusIn` on the body calls
  `scrollIntoView({block:'nearest'})` (a no-op when already visible);
  `scroll-padding-block: var(--stage-scroll-hint-height)` keeps the landed field
  clear of the overlay hint bars.
- An `onKeyDown` on `.stage-panel-scroll-content` handles **Escape** only: it
  blurs the active element — a quick "jump out of this panel's fields" (the next
  Tab resumes outward from there). Tab itself is left fully native. Kobalte
  overlays (select/colour) portal outside the subtree, so their own
  Escape-to-close + focus management never reach the handler.

**Optional wrap-around (`wrapFocus`):** off by default — focus exits to the
browser/page at the ends. Set `wrapFocus` on `EditorPanels` to loop Tab from the
last stop back to the first (and Shift+Tab first→last). It's installed only on the
**outermost** stage (a stage whose root has no `.stage-panels` ancestor); a nested
stage ignores it so focus flows out into the parent's traversal — the loop belongs
to the whole stage, not a region. The handler computes the global tab stops
(`stageTabbables` — focusable, not `disabled`, not `tabindex="-1"` **by attribute**,
and **not inside an `[inert]` subtree** so collapsed-section fields are skipped) and
acts only at the global first/last; the nesting check is structural (once at mount),
while whether the loop fires is read reactively, so a bound `wrapFocus` toggles live.

The modal runs its own hard **focus trap** that always wraps within its container
(`focusables(container)`), independent of stage `wrapFocus` (see §7); its host
mounts as a sibling of `.stage-panels`, so its Tab events never reach the stage
wrap handler.

- **No native `title` attribute anywhere — the library emits zero OS tooltips.** The
  browser's `title` hover bubble is unstyleable, slow to appear, and inconsistent
  across platforms, so it's banned. Every control's accessible name is an `aria-label`
  (icon-only buttons via their `title` *prop*, which maps to `aria-label`) or the
  visible label text. `BaseButton` renders only `aria-label`; the labelled skins
  (`ActionButton` / `ToggleButton`) have **no `title` prop at all** — their visible
  label is the name. A *styled, deliberate* hover tooltip goes through `stageTooltip`
  (the floating-UI singleton) instead — see §7. `IconButton`'s `title` does both jobs: an
  icon alone rarely says what a button does, so the same text is its name and its tooltip,
  shown on hover and keyboard focus. Its bubble passes the pointer through, so it never
  blocks the neighboring buttons.

---

## 5. Chrome primitives

### EditorPanels
Outer CSS-grid shell, five rows: full-width `top` bar / full-width `topToolbars`
stack / panel band (`1fr`) / full-width `bottomToolbars` stack / full-width
`bottom` bar. Side panels occupy the band (`grid-row: 3`) only. `topSub` /
`bottomSub` are canvas-aligned toolbar stacks *inside* the centre cell (column
2) so their edges match the stage.

- A root `EditorPanels` is `position: fixed; inset: 0` (owns the window).
  `embedded` makes it `position: relative` to fill a parent slot — the recursion
  point, since `center` is `JSX.Element` and already accepts another
  `EditorPanels`.
- **A root stage turns off page overscroll.** `html` and `body` get
  `overscroll-behavior: none` through `:has()` while a non-embedded stage is
  mounted, because a missed touch drag would otherwise pull-to-refresh an editor
  away. Scoped to root stages since an embedded stage may sit in a host page that
  scrolls normally, and zero-specificity so a consumer can override it. Tested on a
  real iPhone: suppresses refresh from dead space and from short and long
  panels, and pinch zoom still works, despite WebKit bug 275947 reporting otherwise.
  `touch-action` on the shell was rejected: it only covered dead space, because a
  gesture starting inside a panel's scroller is outside its reach. Home-screen web
  apps haven't been tested, and reports suggest they may differ.
- **Every slot prop is resolved once via `children()`**, not read off `props`
  directly. A slot is needed in two places — the grid-track sizing
  (`undefined ? '0px' : 'auto'`) and the render `<Show>` — and Solid getter-wraps
  an inline-JSX prop, so reading it twice **re-evaluates the JSX** and creates a
  new element each time. If the slot holds a shared DOM node (e.g.
  `top={<TitleBar left={titleLeft} />}` where `titleLeft` is a JSX `const`), that
  node gets *moved* into the latest throwaway instance and the inserted bar
  renders **blank** — a silent footgun the consumer couldn't reasonably foresee
  (inline JSX in a slot is the obvious thing to write). `children()` memoizes the
  resolved nodes, so every read returns the same instance and the getter runs
  once — robust whether the consumer passes inline JSX or a `const`. Applied to
  all slots (`top`, `topToolbars`, `topSub`, `center`, `bottomSub`,
  `bottomToolbars`, `bottom`, `leftPanel`, `rightPanel`).
- **Multi-stage composition (still a sketch):** an outer stage with bars + no
  panels whose `center` holds two embedded stages (e.g. left-panel-only primary +
  right-panel-only secondary), all sharing one `createEditorStore`. See §8 for
  the open questions.
- `persistKey` **caches each panel's collapse state** (uncontrolled only) under
  `stage-panel:<persistKey>:left` / `:right`, via the shared `readFlag`/`writeFlag`
  kernel in `state/persist.ts`. Seed precedence: cached → `defaultLeftCollapsed`
  → expanded; a controlled panel never caches. `persistKey` *is* the per-stage
  namespace — give each stage in a split a distinct one.
- Forwards `leftSize`/`rightSize` and `leftToggleVariant`/`rightToggleVariant`
  into the internal panels.
- **Expanded width is tier-derived:** `--stage-expanded-width =
  control-height × 11.5` (≈207/241.5/299px at small/normal/large), declared in
  the per-tier token block so it re-resolves per size class — a `large` stage
  gets wider panels. (`--stage-modal-max-width` keys off it, so modals scale too.)
- **Overlay panels (`leftPanelMode` / `rightPanelMode`).** The panel's track holds only its
  collapsed width, open or not, and its
  cell becomes an absolutely positioned grid item spanning every column in the band row, so
  it stays inside its own stage. It's the same element in both modes, which is what lets the
  mode switch live without a remount. The collapse animation moves to the cell's `width`, so
  it never touches the center. The cell is its own stacking context above the center's HUD,
  but a floating panel always draws above it: `.stage-float-host` and `.stage-panels` are
  separate stacking contexts, and lifting the stage over the host would also lift its opaque
  center over every floating panel.
- **Collapsed variants (`leftCollapsedVariant` / `rightCollapsedVariant`).** A full-height bar
  laid over the center permanently covered part of it, and no surveyed editor does that (see
  `docs/editor-panel-docking-patterns.md`). So `'strip'` always has its own column, and it stays
  that wide while an overlay panel is open, because shrinking it would resize the center. `'tab'`
  and `'none'` have no column. A tab drags along the edge under the section layout's `panelsLocked` flag, the same lock
  that freezes floating panels, and `layout.reset()` restores it. It lives in `stage-panel:<persistKey>:<side>:tab`
  rather than the layout's blob because the blob has no per-stage key. On release it re-anchors
  to the third of the band holding its center, so the position survives a window resize. The tab is a sibling of
  `.stage-panel`, which clips to its collapsed width of zero.
- **`layout.reset()` reaches panels and static sections.** They follow an internal `resetCount`
  signal, each restoring its own default and clearing its own key. A signal alone would miss
  anything unmounted, such as a hidden split stage, which would restore its saved state on its
  next mount. So panels and sections record their keys with `trackSavedKey`, stored under
  `stage-layout:<persistKey>:saved-keys` to survive a reload, and `reset` clears that list first.
  The list itself stays: it's names, not choices. Only uncontrolled state is recorded, because
  controlled state belongs to the app.
- **`resizable` (per-stage opt-in)** turns on drag-to-resize, with the handle
  matching the collapse-toggle placement:
  - *Header variant* — `Panel` renders a wide transparent gutter on the inner
    edge and thickens that edge's divider to **3px** as the affordance (no colour
    hint; the `col-resize` cursor confirms it). **Double-click the gutter resets**
    to the authored default, or the tier token without one.
  - *Edge variant* — the full-height collapse **button itself is the drag
    handle** (no separate gutter, no visual change). Click collapses, drag
    resizes; a small movement threshold makes them mutually exclusive — a real
    drag sets a flag that swallows the synthetic click pointer-capture fires on
    release.
  `EditorPanels` owns the grid track and clamps to `[140px, 40% of the stage]`
  (stage width read off the captured root). Width plumbing mirrors the collapse
  trio per side — uncontrolled + `persistKey` persists the dragged px under
  `stage-panel:<persistKey>:left:width` / `:width` (via
  `readNumber`/`writeNumber`/`removeStored`), **written on release only**; pass
  `leftWidth`/`onLeftResize` (+`right*`) to control it, and the parent owns
  persistence. A `undefined` internal width means "use the token" (the
  default state when no `defaultLeftWidth`/`defaultRightWidth` is set). The dragged px also overrides `--stage-expanded-width` on
  the panel's cell so the fixed-width `.stage-panel-inner` follows the track (not
  just the cell). During a drag the root carries `.stage-panels-resizing` to
  suppress text selection.

### Panel
Collapsible side panel. Tab/focus behaviour is §4. `toggleVariant`
(`'header'` default | `'edge'`, fixed per instance like `side`) moves the
collapse toggle: `'edge'` drops the top header strip and puts a full-height
vertical toggle bar on the panel's *inside* edge (right edge for a left panel,
left for a right — `.stage-panel-edge-button`), reclaiming the header's vertical
space; collapsed, the strip toggle fills full panel height
(`.stage-panel-strip-edge`). The edge button is chrome (`tabindex=-1`). No grid
change — the edge bar sits inside the existing expanded-width track.

Overflow is tracked with an `IntersectionObserver` over top/bottom sentinels
(guarded for happy-dom), **not** a scroll handler — an `onScroll` that positions
elements is a scroll-linked effect Firefox warns about.

Collapse is animated: the strip↔expanded column track transitions (see the motion
bullet in §2). The expanded content lives in `.stage-panel-inner` (the flex column
for `header`, a row for `edge`), holding the panel's true width while
`.stage-panel` clips to the animating track so the body slides rather than
reflowing; the inner is pinned to the pane's outer (screen) edge.

**Collapsed = in the document, not torn down.** Same mental model as `Section`: one
root element and one always-rendered inner, with collapse only visual. What holds that
together:

- The inner is `inert` and `visibility: hidden` when collapsed. The `visibility`
  transition lives on the closing side only: it keeps the body visible while the track
  closes, and on the opening side it would leave the body hidden at progress 0, so
  `focus()` right after an expand would silently fail.
- Portaled overlays live outside the inner, so inertness doesn't reach them and they
  would stay open, pointing at a hidden trigger. `closeWhenInert` closes them from the
  DOM state rather than a collapse signal, so it covers `Section`, `Panel` and any
  consumer-applied `inert` alike, with no context to thread through `EditorPanels`' slots.
  `stageTooltip` watches its anchor the same way.
- `.stage-panel-strip-button` is absolutely positioned over the inner, and its fill
  fades in with the collapse. `.stage-panel-strip` is `position: relative` to anchor
  it, which is safe because the resize gutter (which must anchor to the cell) only
  exists while expanded.
- `.stage-panel` uses `overflow: clip`, not `hidden`. A hidden box is still a scroll
  container, so focusing a field while the panel opens scrolls it sideways for good.
- `.stage-panel-strip` has `contain: inline-size` + `min-width`, or the laid-out inner
  would prop a standalone panel open in a content-sized parent.
- **Geometry must skip collapsed docks.** A collapsed panel's dock keeps its full rect,
  reaching out over the centre, so `hitTestDock` skips `[inert]` zones. Any new
  rect-based hit testing needs the same check.
- `focusField` expands collapsed panels as well as sections.
- Effects in a collapsed body keep running, and its content width doesn't change, so a
  `ResizeObserver` inside doesn't fire on collapse.

### Section
Collapsible container (header + chevron + body); the unit a consumer builds
editor UI from. Holds anything — naming it `Section` does **not** imply a registry
(see thesis §1).

- **Persists collapse to localStorage out of the box** (`stage-section:<persistKey ?? title>`;
  `persist={false}` opts out). Seed precedence: cached → `defaultOpen` → open
  (default *expanded*; "no cached value" reads as expanded). Controlled sections
  (`open()` supplied) never cache.
- **Collapsed = mounted but hidden, not torn down.** The body is always rendered;
  collapsing animates its height to zero (the `grid-template-rows: 1fr↔0fr` trick
  on `.stage-section-collapse`, keyed off `.stage-section-open`) rather than
  unmounting (`<Show>`). Mental model: a section is always there, collapse just
  tucks it away — so a field keeps its state and stays deep-linkable (`focusField`
  can expand + focus it; §6). The collapsed body is also `inert` — that drops it
  from the tab order + a11y tree (the role `display:none` used to play, swapped out
  so the height animation works; see the motion bullet in §2). Trade: collapsed
  content's effects stay live and it renders at load — fine for field panels; avoid
  parking something genuinely expensive in a section expecting unmount to free it.
- **Dismissable `onClose` mode:** header static (no chevron/toggle/hover), body
  always open, persistence skipped, a `×` button top-right calls `onClose`. This
  is the shape the global modal hosts; the prop lives on `Section` generally.
- **`headerActions`** (`SectionHeaderAction[]`: `{ icon, title*, onClick, active?,
  disabled?, tone? }`) puts icon buttons on the title bar — each a **borderless**
  IconButton (`border` is never exposed; the header skin is always borderless),
  with the **`subtle` variant** + **`tabbable={false}`** (secondary meta-actions:
  mouse-only, out of tab order, no focus ring; subtle skin = muted glyph, shape
  brightens on hover with no bg, press flashes faint bg, active stays
  bright-shape with no accent fill). `title` is required (icon-only → the
  accessible name, rendered as `aria-label`). In a dismissable section they sit
  left of the `×`.
- **The header is a `<div>` row with three label shapes + a `.stage-section-header-actions`
  cluster of *sibling* buttons on the right (so clicking an action never bubbles to
  the toggle — no nested `<button>`). The label shape is context-driven:**
  - *Default collapsible:* one toggle `<button>` (chevron + title, `flex:1` +
    `align-self:stretch`) — a click anywhere across the header collapses (the
    forgiving target for a section that can't be dragged).
  - *Drag-handle (`dragHandle` prop, set by `DockZone`):* the chevron is its **own**
    `.stage-section-chevron-button` (the keyboard + AT collapse control — `aria-expanded`),
    and the title is wrapped in a `.stage-section-drag-handle` grip (`grab` cursor,
    `user-select:none`, `touch-action:none`, `aria-hidden` since the chevron button is
    already labelled by the title). **The grip only moves; the chevron alone collapses.** A
    press with no travel does nothing, so the title reads purely as a move handle and a
    fumbled drag can't toggle anything. Keyboard/AT collapse stays on the chevron button, so
    there's no second tab stop. The grip is what `DockZone`'s pointer gesture looks for; the
    chevron and the actions are outside it, so neither drags.
  - *Dismissable (`onClose`):* a static title, no toggle (see below).
- **No header hover affordance.** Lighting the whole bar on hover would misread the
  grip-vs-actions split, so the header stays flat. Keyboard focus is the exception: the
  collapse control draws an inset `--stage-color-focus` ring (`:focus-visible`, offset
  `-1px`). (There is no per-section custom glyph — the chevron is the single
  collapsed/expanded indicator. A consumer icon slot may return when the activity rail
  is revisited.)

### Movable sections (dock model)
A section can be defined **as data** and rendered through a model that owns *which
sections exist and where each lives*, instead of as static `<Section>` JSX children
of a panel. This is the substrate for reorder / float / cross-panel transfer
(the movable-sections work). Built in phases; **Phase 1 is reorder-within-panel + persist**,
**Phase 2 is float over canvas + re-dock**, **Phase 3 is cross-panel / cross-stage
transfer**, **Phase 4 is floating *panels*** (the subsections at the end). The
canonical API description here reflects Phase 4 — Phases 2–3 are kept as historical
narrative (a floated section was a single always-open *card*; Phase 4 reframed it as
an ordinary section inside a floating *panel-that-is-a-dock*).

**Why a model at all.** Static authoring (`leftPanel={<><Section/><Section/></>}`) has
no notion of placement, so move/reorder with a *single-instance guarantee* (a section
is never duplicated) is unrepresentable. The dock model is the single source of truth
for placement; panels render *from* it.

- **`createSectionLayout(opts)` → `SectionLayoutController`** (`layout/sectionLayout.ts`).
  A Solid store over a placement map.
  - `opts.sections: Record<id, SectionDef>` — the render registry. `SectionDef =
    { title, render: () => JSX.Element, dock, defaultOpen?, size?, headerActions? }`.
    `headerActions` is forwarded to the underlying `Section` whether the section is docked
    or floating, so a movable section keeps full `Section` capability (no per-state loss).
    `render`
    is a **thunk** (not eager JSX) so a section's body instantiates under the rendering
    `DockZone`'s owner — a section that moves docks remounts cleanly, effects never
    orphaned. `dock` is the section's *home* dock (seeds the default placement;
    declaration order within a dock sets the default order). The other fields forward
    straight to the underlying `Section`. The id is also the section's collapse-persist
    namespace, so keep it stable.
  - **App panels** (`opts.appPanels: Record<id, { movable?; sortable? }>`). For panels with
    no claim to a permanent slot (summoned on demand, then dismissed). Every section still
    has a home: a section whose `dock` names an app panel lives in it, and the app opens and
    closes the *panel* (`openPanel(id, x?, y?, w?)` / `closePanel` / `isPanelOpen`), never a
    section. Two kinds of floating panel share `floatingPanels`: **user panels** (`float-N`,
    made by floating a section out, pruned when empty) and **app panels** (declared id; the
    entry appears on first open and stays while closed, which *is* the position memory).
    *Why not homeless sections (`dock` omitted, `open`/`close` per section):* they need
    per-section position memory captured on every exit from a panel the section is alone in,
    and once a homeless section can share a user panel with homed ones, dock-all no longer
    does what it says. Making the panel the unit removes both.
    - **The docking rule** (`canDock(id, dockId)`, via `dockAllowed`): an app panel's
      section stays in its panel; any other section goes anywhere except an app panel. So a
      user panel only ever holds side-homed sections and dock-all is always honest. Enforced
      in the model (`setDockOrder` skips refused ids, `move`/`dockPanel` return before their
      force-expand so a refused drop can't collapse an accordion's siblings, `floatOut`
      refuses app-panel sections) and in the gestures (`hitTestDock`'s `accepts` option: a
      refused dock still occludes, so a point over it hits nothing and a section dropped there
      floats out as on empty space; an app panel's header drag never previews a dock).
      `loadSeed` resets a stored placement the rule refuses to its default, for a section
      whose home changed in code, and drops stored app-panel entries no longer declared.
    - `openPanel` on an open panel only raises it, so a repeated shortcut never yanks a panel
      the user moved. Position: args, else the stored entry, else the float region's top-left
      + 16px (`StageFloatHost` hands the controller its `floatRegion` via `setFloatHost`); the
      panel's mount-time clamp covers a window that shrank since.
    - Chrome: the panel header shows × (`closePanel`) where a user panel shows dock-all; its
      sections never get the redock magnet (already home). A section's grip shows in an app
      panel only when `sortable !== false` and the panel renders more than one section, since
      the grip can only reorder there; without it a header click collapses.
    - `openPanels: Record<id, true>` is persisted in the blob (open across reload);
      `reset()` clears it and the entries, so every app panel closes and forgets its spot.
    - Ids starting with `float-` throw at construction: they'd collide with the user-panel
      counter.
    - **Controlled `open`** (`AppPanelDef.open: () => boolean`), the library's usual
      controlled/uncontrolled split: `isPanelOpen` reads it, `openPanel` ignores the panel
      (else it would seat an entry for a hidden panel), it never enters `openPanels`, and an
      effect on `[open, resetCount]` seats it (position + top `z`) each time it turns true and
      after a reset clears its entry while showing. `reset()` writes inside a `batch` so that
      effect sees the finished reset rather than re-seating before the entries are cleared.
      Its × calls `onClose` (none without one).
    - **Declared geometry.** Opening position: args → last entry (skipped when `movable:
      false` or `framed: false`, so a fixed panel can't drift from its declared spot after a
      code change; `appPanelMovable` is the one rule both the model and the host read) →
      `x`/`y` → float region top-left + 16. `width` is the panel's *authored* width
      (`authoredDockWidth` returns it), i.e. the width its sections are designed for: panel
      width and minimum, not `w`, which stays "the user resized it". Seeding `w` instead was
      wrong: a declared width below the library default lost to the designed-width minimum.
    - **Frame and close are explicit** (`framed`, `closable`, both default `true`). The header
      strip is the frame: shown iff `framed`, even when it holds nothing, because it is the
      thing that reads as "a panel". Inferring it ("omit the strip when empty") made a fixed HUD
      silently look like a bare section, a look the app should choose, not stumble into.
      Grip glyph only while the panel can move (`movable`, framed, not panel-locked). The ×
      comes from `appPanelClose` (none when `closable: false`, or controlled without
      `onClose`); framed, it's on the strip, frameless, `DockZone` appends it to the top
      *rendered* section's header actions, so it follows a reorder or a hidden section with
      no bookkeeping. A frameless panel is never user-movable: there's no surface to drag
      that isn't already a section's (header = collapse/reorder).
  - **`SectionDef.collapsible: false`** → `Section`'s `collapsible={false}`: always open, no
    chevron; with a grip, the grip alone (`.stage-section-drag-handle-bare` restores the
    title inset the chevron used to provide). It joins `alwaysOpen` with the modal and
    floating-card modes, so nothing is cached. In an accordion dock it's open beside the
    one open collapsible section: `openInDraft` doesn't collapse siblings for it.
  - **Two locks** (`sectionsLocked` / `panelsLocked`, each controlled or uncontrolled with a
    `default…` seed). The section lock hides grips; the panel lock freezes floating-panel
    move/resize/dock and the side-panel tab drag. *Why split:* one `locked` flag meant a user
    who wanted to stop accidental section drags (to click-collapse a floating section safely)
    also lost the ability to move their floating panels. An app panel's `movable: false`
    freezes it regardless of the panel lock.
  - **Hidden sections** (`SectionDef.visible?: () => boolean`). For sections that belong to
    one app mode: not rendered, placement / order / open state kept. Visibility is *not*
    arrangement state (never in the store, nothing for `reset()` to clear); it's purely a
    render filter. One derived accessor, `renderedDockOrder(dockId)` (`@internal`), is what
    every piece of chrome that draws or counts a dock's sections reads: `DockZone`'s `<For>`,
    the float host's mount filter, panel width, dock-all, the sole-section rule. `dockOrder`
    keeps returning every id, since the model ops index into it.
    - **Index mapping.** `hitTestDock` counts over the cards it sees (the zone's *direct*
      children, so a dock nested in a section body doesn't skew the count), then maps that
      visible index to the full order: just before the card below the line, or the end of the
      list below the last card. So `DockHit.index` indexes `dockOrder` (hidden included,
      ignored section excluded) and `move` / a reorder / `dockPanel` take it unchanged.
    - **All-hidden floating panel:** not mounted (no hit, fusion or Tab target) but **not
      pruned**. The prune reads placements, which hidden sections keep, so this needs no
      special case. On show it remounts at its stored `x/y/w/z`; the mount-time clamp re-fits
      it to the float region; it isn't raised.
    - **Sole visible section dragged to empty space** = the panel moves: `floatOut` (keeping
      `w`), then `setDockOrder(newPanel, oldFullOrder)` carries the hidden companions, a
      reorder write so their open state is untouched. A panel header drag (`dockPanel`)
      already moves every section, hidden ones too.
    - Visibility never writes open state, so an accordion dock whose open section is hidden
      shows the rest collapsed; nothing auto-opens. Hiding mid-drag ends the gesture through
      the existing "grip left the document" per-frame check.
  - `placements: Record<id, Placement>` where `Placement = { dock; order }` — **uniform**
    (no floating variant). A section is always docked *somewhere*; a floating panel is itself
    a dock, so a floated section is `{ dock: <panelId>, order }`. Single-instance holds by
    construction: an id appears in exactly one dock's list.
  - `floatingPanels: Record<panelId, { x; y; z; w? }>` — the floating-container registry.
    Each entry is a free-positioned panel-that-is-a-dock; its `panelId` keys both this map
    and the `dock` of every section it holds. `x`/`y` are host-local, `z` a dense paint
    rank, `w` the dragged width (omitted → default CSS width).
  - `open: Record<id, boolean>` — **every section's open state**, owned by the layout (not
    each `Section`). Every `MovableSection` renders *controlled*, so collapse is plain
    reactive model state — a drop force-expands via one write the section reflects with no
    remount and no per-`Section` localStorage cache to race. (The old design left non-
    accordion sections *uncontrolled*, seeding open state from a cache at mount; "expand on
    drop" then wrote the cache and hoped for a remount, which raced the old drag library and
    lost in many edge cases. Unifying to controlled made drop-expand bulletproof.)
  - Methods: `dockOrder(dockId) → id[]` (derived, reactive, sorted by order),
    `setDockOrder(dockId, ids)` (the reorder sink — each id re-docked at its index;
    unknown ids ignored; a within-dock **reorder**, so open state untouched),
    `move(id, dock, index)` (imperative, clamped; **always force-expands the section as it
    lands**, overriding any prior/stored collapse — see the drop-clarity note below),
    `redock(id, dockId?)` (back to a dock via `move`, defaults to the home dock), `reset()`.
    *Floating-panel methods:* `floatingPanelIds()` (panel ids sorted by `z` ascending —
    paint order), `floatOut(id, x, y, w?)` (lift `id` into a **fresh panel** at x/y — new
    panel id + `move(id, panelId, 0)`; `w` seeds the panel width so it doesn't jump to the
    default expanded width on first drop), `setFloatingPanel(panelId, x, y)` (x/y only,
    keeps z/w), `setFloatingPanelWidth(panelId, w)` (width only), `raisePanel(panelId)`
    (z to top), `isFloatingDock(dockId)` (true if `dockId` is a floating panel),
    `dockPanel(panelId, dockId, index)` (relocate **all** of a panel's sections into
    `dockId` at `index` in one store write, then force-expand each — the batch op behind
    panel drag-to-dock + panel→panel fusion; emptying the source panel prunes it; no-op for
    self / empty panel / either side an app panel). Panel `z`
    is re-normalized to a dense `0..n-1` on each `floatOut`/`raisePanel` so it never drifts.
    Panel ids are `float-<n>` (a monotonic counter seeded past the max stored suffix on
    load, so a reload never reissues a live id).
  - **Draw order is window focus.** A capture-phase `pointerdown` and a `focusin` anywhere in
    a panel call `raisePanel`, capture so nothing inside can stop it.
    Raising only changes `z`: the host renders panels in creation order, not paint order,
    because moving a node would drop its focus and reshuffle the Tab order. `z`
    only orders panels within one float host: `position: fixed` makes the host and
    `.stage-panels` separate stacking contexts, so nothing in a stage can sit between two
    floating panels.
  - **Floating width comes from the home dock.** `SectionDef` has no width, because a
    section is designed for its home panel. `EditorPanels` provides `defaultLeftWidth` /
    `defaultRightWidth` through context around each panel slot, since it doesn't know which
    docks a slot holds, and each `DockZone` registers its width on the layout. The registry
    is reactive, not read from the DOM, because a panel restored on load renders before its
    home dock is in the document. It's kept out of the persisted store (the markup declares
    it on every load) and survives a dock unmounting. `FloatingPanel` derives its width
    from its current sections, which covers every path into a panel (`move`, `dockPanel`, a
    reorder, a home panel mounting late). The widest width is the panel's width and a
    hard minimum, kept as a CSS `max()` so a library-default section follows the size tier.
    **`w` only ever means an explicit choice** (a resize drag, or `floatOut`'s argument): nothing
    derived is stored, so a section leaving shrinks an unresized panel with no extra logic, and
    a resized one keeps its width above the minimum. Nothing is seeded from a measured section,
    since that would carry a leftover width along. A home dock that has
    never mounted, or an app panel (which has no authored width), counts as the library default.
  - **Empty-panel prune.** A user panel exists only to host sections; when its last
    one leaves (redocked, moved to another panel, or floated into a new one) the container
    disappears. An app panel's sections never leave, so it's never pruned while declared
    with sections. `pruneEmptyPanels(placements, floatingPanels)` runs inside `setDockOrder`'s
    `produce` (so every placement mutation, incl. `move`, prunes), and once more on the
    persisted seed (a panel whose sections were all removed from code is dropped on load).
    *Open-state methods:* `isExpanded(id)` (reactive — drives every controlled section),
    `setExpanded(id, open)` (the chevron's toggle sink: in an accordion dock, opening
    collapses its siblings + closing leaves the dock all-collapsed; in any other dock it
    just sets this section's own state).
  - **Accordion docks** (`opts.accordionDocks: string[]`). A listed dock holds **at most
    one open section**: `setExpanded(id, true)` (whether from the chevron or a drop's
    force-expand) collapses the dock's other sections, so opening one closes the rest and a
    section **dropped in** becomes the open one. The default-open section is the dock's
    first. Because *all* `MovableSection`s are controlled now (not just accordion ones),
    accordion is purely a **setter constraint** — `setExpanded`/`move` collapse siblings for
    an accordion dock and don't for any other; the section's render path is identical either
    way (no controlled-vs-uncontrolled flip on crossing docks).
  - **Persistence** (`persistKey` set): one **versioned blob** under
    `stage-layout:<persistKey>` via `savePersisted` + a local read/version-gate
    (`loadSeed`). The placement map and the open map each seed via `seedById(defaults,
    stored)`: a **per-id replace** — start from defaults, then for every id in *both* stored
    and defaults take the stored value wholesale (a stored placement may target a `float-N`
    panel id; kept as-is). Replace, not `deepMerge`, so a code-side change wins over a stale
    stored value cleanly. A section added in code but absent from storage falls to its
    declared dock + default open state; an id in storage but no longer in `sections` is
    dropped. Storage is an **override**: while the arrangement equals the declared defaults
    the key is *removed* — so the default layout persists nothing, a `reset()` leaves storage
    clean, and a code-side default change wins on next load. Writes are deferred + debounced
    (the seed isn't echoed back; a panel move/resize's per-frame churn coalesces to one
    write). The blob carries `{ placements, open, floatingPanels, openPanels }` (`open` = per-section
    expanded bool; `floatingPanels` restored within the same version, then `pruneEmptyPanels`
    drops any container left with no sections). **Bump `opts.version` on a breaking blob-
    shape change to discard stale blobs.** Phase 3 bumped it (float coords went host-local →
    global); **Phase 4 (uniform `{ dock, order }` placement)** and the **controlled-open
    refactor** (`accordion` map → `open` map) each bumped it — a blob holding the old
    floating-section variant or accordion map is invalid (the arrangement is throwaway,
    discarded cleanly; the playground is `4`).
- **`SectionLayoutProvider` / `useSectionLayout()`** (`layout/SectionLayoutContext.tsx`).
  Context exposing the controller; wrap the **whole app, above every stage**, so all
  `DockZone`s and the single app-root float host (`StageFloatHost`) share one model, which
  is what lets a section move between any panels under the provider (cross-stage reach).
- **`DockZone id`** (`layout/DockZone.tsx`). A drop zone that (a) renders
  `<For each={layout.renderedDockOrder(id)}>` of `MovableSection`s, and (b) starts a drag on a press
  of a section's grip. It drops into any `leftPanel`/`rightPanel`
  slot (those already take arbitrary JSX) — **`EditorPanels` needs no change**. Each
  section renders through one stable component per id (`MovableSection`, a `Section`
  wrapper carrying `data-section-id`) so a **within-dock reorder is a node-move, not a
  rebuild**.

**Single-instance enforcement.** `placements` maps each id to at most one location (exactly
one for a homed section); a `DockZone` renders only visible ids whose placement targets its dock. An
id is in at most one rendered list by construction — duplication is unrepresentable.

**One pointer model, no drag library.** Sections (`layout/sectionDrag.ts`) and floating
panels (`FloatingPanel` in `StageFloatHost.tsx`) both drag with pointer events and pointer
capture, and share one hit test (`layout/dockHitTest.ts`) and one insert line
(`layout/insertLine.ts`).

*Why not native HTML5 drag.* Sections used to drag natively through
`@formkit/drag-and-drop`, and heavily lagged in Chromium only. Traces on Linux/X11 (Chromium
vs Waterfox, same scene): our handlers cost 0.1-0.2ms in both and Chromium's renderer main
thread sat at 1-6%, but its GPU main thread sat near 100% for the first 600ms after
`dragstart`, then 2-15%, with `dragover` arriving about every 15ms against Waterfox's 4ms.
That cost lives in the browser's native drag session and can't be tuned from our side, so we
left the path. It was also why touch only half worked and why float-out needed a second
system beside the library. Synthetic drags (CDP, `Input.setInterceptDrags`) never showed the
lag, so a person's eyes in Chromium are the acceptance test for this class of problem.

**The gesture (`startSectionDrag`).** A direct `pointerdown` on `.stage-dock-zone`, for the
primary button, when the target is inside this dock's own `.stage-section-drag-handle` (a dock
nested in a section body handles its own grips). Only the grip starts anything, so a press in a
section body bubbles untouched: text selection and document-delegated Kobalte selects just work.
Nothing is `draggable`, and a `dragstart` is prevented during a press, since a native drag starting
over selected text would `pointercancel` ours (Gecko hit this on panel headers).

- **4px of travel starts a drag.** A press with no travel does nothing.
- **Commit on release only.** Nothing in the model changes mid-drag, so nothing unmounts and a
  source panel can't prune early: the dragged node stays in place, dimmed
  (`.stage-movable-section-dragging`), with the ghost and line as the only feedback. This is an
  insertion-line model rather than live-sort, because reshuffling sections under the cursor reads
  as jumpy.
- **One animation-frame loop.** Pointer events only record the latest point. Each frame moves the
  ghost, hit-tests and writes the line, skipping all of it while nothing has moved, and a release
  hit-tests again at its final point.
- **Outcomes on release.** Same dock: `setDockOrder`, keeping collapse state (no write if the order
  is unchanged). Another dock: `move`, landing expanded (a sole open arrival in an accordion). No
  dock, inside the float host: `floatOut`. Outside the host or with no host mounted: nothing.
- **Cancel.** Escape (captured and stopped, so it doesn't also close something beneath),
  `pointercancel` and a lost capture end with no change. So does the grip leaving the document
  (a lock, a reset, a redock button), checked each frame. Exactly one gesture runs at a time. The
  `lostpointercapture` listener must check `target === handle`: a touch press implicitly captures
  to the grip's inner title, and moving that capture to the grip reports a loss from the child.
- **Selection and cursor** are pinned by `.stage-section-drag-active` on `<html>` while dragging.

**The ghost.** A clone of the section dressed as a `.stage-float-panel`, built once at drag start
inside `.stage-root` so tokens resolve, then moved only by `translate3d` on its own layer
(`will-change: transform`), with its height capped so a tall section stays cheap to paint.
`pointer-events:none`, so hit-testing sees through it; `z-index` matches the line's so the line
(later in the document) draws over it. Rejected: the popover top layer, which beats any stacking
context but hides the line. The clone is `inert` with every `id` and `name` stripped *before* it's
inserted, because a cloned radio sharing a `name` unchecks the real one the moment it's in the
document. Its width is what a float-out would land at: the panel's `w` if the section is alone in a
resized panel, else `sectionDesignedWidth`, the same value `FloatingPanel` derives from. The grab
offset is clamped into that width so the pointer stays on the ghost, and it's subtracted from the
drop point, so a floated panel's top-left lands exactly where the ghost's was.

**The hit test (`hitTestDock`).** Geometry against every dock of the dragging layout, spanning all
stages, so it works mid-drag with no event target to read. Traps it handles:

- *Stacking.* Floating docks are checked first, highest `z` first. Side docks only overlap when an
  overlay panel covers a nested stage; they have no rank in the model, so `elementsFromPoint` settles
  those few cases (ghost and line take no pointer events, so they never appear in that stack).
- *Drop area.* A side panel accepts a drop anywhere in its `.stage-panel-body`. A floating panel
  accepts one anywhere in the panel, so its header strip can't let a drop fall through to a side dock
  beneath it.
- *Same-dock index.* `ignoreSectionId` leaves the dragged section out of the count, which is what
  `move` and a reorder expect (counting it was an off-by-one).
- *Ownership.* A module `WeakMap<zoneEl, layout>` that `DockZone` fills. An app can run one layout per
  pane, and a hit on another layout's dock would place a section in a dock its layout never renders.
- *Inert docks.* A collapsed panel's dock keeps its full rect, reaching out over the center.
- *The line* stays inside the visible part of the dock, so a scrolled-away card can't push it out of
  the panel. It lives on `document.body` in page coords so it never reflows a panel or gets clipped,
  which puts it outside the token scope: colour and z are copied inline from the nearest stage root.

**Auto-scroll (`autoScrollDock`).** Within 32px of the top or bottom of the hovered dock's
`.stage-panel-body`, it scrolls at up to 12px/frame, ramping toward the edge, and the caller hit-tests
again since every card moved. Shared by section and panel drags. A floating panel has no scroller.

**Float-out bounds.** `StageFloatHost` registers its element through the `@internal`
`layout.setFloatHost` / `layout.floatHost()`, and `sectionDrag` reads it on release. `floatRegion` keeps
working through `FloatingPanel`'s mount clamp.

**Touch.** `touch-action:none` on the grip only, so a finger on the grip drags and a finger anywhere
else in a section scrolls the panel. No long-press gesture.

**The remount tradeoff.** *Within-dock* reorder → Solid's keyed `<For>` *moves* the node (no remount).
*Cross-dock / float* transfer → the id leaves one list and joins another, so that section remounts.
Acceptable: field values live in `createEditorStore` (external) and collapse state is in the layout,
so it reconstitutes; at no point do two copies exist. If a future expensive section makes cross-dock
remount visibly janky, revisit with a stable-wrapper-pool + reparent — not now.

The static `leftPanel`/`rightPanel` JSX path is **untouched** and remains the
non-movable default; the two authoring modes coexist (the playground runs one panel
each way).

> **Superseded by Phase 4 (floating panels).** Phases 2–3 below describe the original
> *float card* model — a floated section was one always-open card with a left-side magnet
> and no collapse, carrying its own `floating` placement variant + `floatingIds` /
> `setFloating` / `setFloatingWidth` / `raise`. Phase 4 removed all of that: a floated
> section is now an ordinary `MovableSection` inside a floating *panel* (a dock that
> floats). The panel-level drop area and `floatRegion` carry over. The drag mechanics these
> phases built on were replaced by the pointer model above.

#### Phase 2 — float over canvas + re-dock
A section can be dragged **out of a dock to float over the canvas**, moved + resized
freely, and dragged **back into a dock**. Move semantics throughout: a section floats by
relocating the one instance (the single-instance invariant holds), never by cloning.
Float `x`/`y` + `z` + width `w` persist alongside the docked placements.

- **`StageFloatHost`** (`layout/StageFloatHost.tsx`). The **single** click-through overlay
  (`.stage-float-host`, `position:fixed`, `inset:0`, `pointer-events:none`) the consumer
  mounts **once at the app root** under the provider, inside a `.stage-root` for the token
  scope — *not* inside a stage. Its fixed box is the **global** coordinate origin for every
  float's `x`/`y`, so a card floats over the whole app and is draggable across stages
  (Phase 3). It renders `<For each={layout.floatingIds()}>` of
  positioned `.stage-float-card`s; a card's `z-index` is
  `calc(var(--stage-z-float) + var(--stage-float-z))` so a raised card paints over its
  neighbours. New token **`--stage-z-float: 40`** (above the stage pointer layer, below
  popovers). The host needs no drop-target element of its own: a section drag reads its box
  as the float-out bounds.
- **The float card.** The registry section rendered through the ordinary `Section` in
  `dragHandle` mode, but with **`leadingAction`** set — a generic `Section` capability
  that replaces the disclosure **chevron** with a custom leading icon button (here the
  magnet that redocks) and forces the section **always open** (a float never collapses).
  The header is therefore `[magnet=dock] [grip=move | title]`.
- **Redock clarity — a dropped section always lands expanded.** `move` writes the section's
  `open[id]` to `true` (in the layout's own open map — see the controlled-open note in §
  Movable sections) after re-docking it, so a section dropped / transferred / floated into a
  panel is always expanded, never reverted to its last collapse state (which could drop it
  back in collapsed and hide where it went). Because the section is rendered **controlled**,
  that one model write is the whole mechanism — no `Section` localStorage cache, no remount
  timing to race. Scoped to `move` (the drop path, incl. magnet redock + cross-dock transfer); a
  **within-dock reorder** goes through `setDockOrder`, which leaves open state alone.
- **Float move + resize + redock.**
  - **Move + resize + redock is ours.** The header grip is a pointer handler
    (`pointerdown` on `.stage-section-drag-handle` → `raise` + `setPointerCapture`;
    `pointermove` → reposition via `setFloating`, **live-clamped to the float region**
    (`clampToRegion`) so the preview always follows the cursor but never leaves the region;
    `pointerup` → redock or rest). On each move it *independently* **hit-tests the docks**
    (see panel-level drop, below): over a dock it previews the shared insertion line
    (`createInsertLine`) and arms a redock target, but **no longer freezes the card** — you
    keep seeing where you're dropping. On release: a hit redocks via `move(id, dock, index)`
    (overwrites the floating placement — redock-by-drag reuses `move`, no new path);
    otherwise the card floats at its current (already-clamped) position. The two
    `.stage-float-card-resize` side-edge grips resize the width via `setFloatingWidth` (left
    edge holds the right fixed by shifting `x`; floored at `MIN_FLOAT_WIDTH`, ceiled at the
    viewport; `clampIntoView` on release). The magnet leading button is the keyboard/click
    redock.
  - **Panel-level drop area.** The dock hit-test (`hitTestDock`/`overDock`, both via
    `dockDropRect`) targets the **enclosing `.stage-panel-body`**, not the dock's short
    content box — so a panel that contains a `DockZone` accepts a drop *anywhere* in it
    (over a section or the empty space below). Floatability is thus effectively a *panel*
    property: a panel with a dock lets any of its sections pull off (grip) and any float
    drop in; a panel without one does neither. Falls back to the zone's own rect for a bare
    dock (no panel ancestor / tests). The insertion line uses this rect, so it spans the
    panel width; the insert index still counts the dock's section midpoints.

#### Phase 3 — cross-panel / cross-stage transfer
A floating section can be re-docked into **any panel on any stage**, not just its origin
stage — so float-out-then-redock *is* the transfer mechanism. Two changes unlock it; both
build on Phase 2 rather than adding a new drag system.

- **One global float host.** The host moved from per-stage (mounted over a stage's
  `center`) to a **single app-root overlay** (`position:fixed`, above). With one global
  coordinate origin a card can be dragged anywhere on screen, and the dock hit-test
  scans **every** `.stage-dock-zone` document-wide (targeting the enclosing panel body, see
  Phase-2 panel-level drop), so a release over a panel on a *different* stage redocks there
  via `move(id, dock, index)`.
- **Two distinct regions — float-rest vs dock-drop.** *Where a card may come to rest* and
  *where a drop re-docks* are deliberately **separate sets that need not overlap**. The
  optional **`floatRegion?: () => DOMRect`** prop on `StageFloatHost` is the rest region (a
  viewport-space rect; default = the host box). The drag **live-clamps** the preview into
  it (`clampToRegion`, shared with the release/resize `clampIntoView`), translating it into
  the host-local frame `x`/`y` live in. Dock targets are the panel-body rects, hit-tested
  *independently* each move and checked in `onPointerUp` **before** the rest position — so a
  drop over a panel *outside* the float region still re-docks (the preview rests at the
  region edge meanwhile). This lets a consumer allow floating only over the canvas while
  side panels remain valid drop targets. Multi-rect / predicate regions are deferred
  (`docs/feature-ideas.md`) until a consumer needs them.

Out of scope (Phase 3): tabbed/stacked dock groups; floating *panels* and **direct
panel↔panel transfer** arrived in Phase 4 (below).

#### Phase 4 — floating panels
A floating element is now a **panel of its own**, not a single card: multiple sections
stack in it, each collapses independently (chevron back), each carries a right-side
**magnet** to snap itself home, and a section can be dragged **straight from a side panel
into a floating panel** (and between floating panels) with no intermediate float-out step.
The whole floating panel moves/resizes as a unit via a slim **drag-strip header** (+ a
**dock-all** button that sends every section home and closes the panel).

**Core reframe — a floating panel *is a dock that floats*.** This collapses most of the
work onto the existing dock machinery:
- `Placement` became **uniform** `{ dock; order }` (the `floating` variant is gone). A
  section in a floating panel is `{ dock: <panelId>, order }`.
- A new registry `floatingPanels: Record<panelId, { x; y; z; w? }>` holds the containers.
  `StageFloatHost` renders `<For each={layout.floatingPanelIds()}>` of positioned
  `.stage-float-panel`s, **each wrapping a real `<DockZone id={panelId}>`** — so the
  sections inside are ordinary `MovableSection`s and **chevron-collapse + grip-reorder
  return for free**. A panel's `z-index` is still `calc(var(--stage-z-float) +
  var(--stage-float-z))`.
- **The magnet** (the redock affordance — rendered as an `arrows-in-simple` glyph) is
  just a right-side `headerActions` entry merged on in `MovableSection`
  when `layout.isFloatingDock(currentDock)` — *not* a `leadingAction`, so the disclosure
  chevron stays and each section collapses on its own. (Phase 2's always-open card used
  `leadingAction` to replace the chevron; that path is unused by the layout now.)

**Drag outcomes.** A section's release follows § the gesture: another dock is a direct `move`,
covering side→floating, floating→side and floating→floating with no intermediate float-out.
- **The panel's header drag is dock-aware.** A panel's header strip
  (`.stage-float-panel-header`) is a pointer-drag (`pointerdown` not on its dock-all button
  → `raisePanel` + `setPointerCapture`; `pointermove` → `setFloatingPanel`, live-clamped to
  `floatRegion` via the shared `clampToRegion`). On each move it *also* hit-tests the docks
  (`hitTestDock` with `excludeDockId`, so never the panel's own zone): over a dock it arms a drop
  + previews the shared insertion line (`createInsertLine`, on `document.body` at
  `--stage-z-popover` 1000 > the float z, so it shows above the panel); over none it clears
  both. On `pointerup`: an armed drop calls **`dockPanel(panelId, dockId, index)`** — every
  section relocates into that dock (the source panel then prunes, unmounting the
  `FloatingPanel`); otherwise the panel comes to a free rest (`clampIntoView`).
  Escape and `pointercancel` clear the line + drop and put the panel back at its starting
  `x`/`y`. **`hitTestDock` finds *every* dock,
  including other floating panels — so panel→dock (put away) and panel→panel (fusion) are
  the same operation**, exactly as cross-stage section transfer fell out of float→redock; a
  panel *is* a dock. The two `.stage-float-card-resize` side edges resize via
  `setFloatingPanelWidth` (left edge holds the right fixed by shifting `x`; floored at
  `MIN_FLOAT_WIDTH`, ceiled at the host width). **Dock-all** iterates `dockOrder(panelId)`
  and `redock`s each — emptying + pruning the panel.

**Persistence / version.** The blob gained `floatingPanels`; the uniform `Placement` shape
is breaking, so `opts.version` bumps (playground `2 → 3`) and stale floats discard cleanly.
See the persistence note above.

### TabMenu
Horizontal tab-strip **bar control** (not a field/section), modelled on a
document/object tab bar.

- Each `.stage-tab` has a **mouse-only** `×` close — a `<span role="button">`
  out of the tab order (middle-click closes too via `onAuxClick` `button===1`).
  An optional `+` new-tab button renders *inside* the strip at the end (scrolls
  with the tabs; only when `onNewTab` is set) as a real **`IconButton`** (a local
  scalable `PlusIcon` SVG — no icon pack — `subtle` variant) so it gets the shared
  button chrome + focus ring; it stays a tab stop. Overflow surfaces `‹`/`›`
  scroll arrows (a `ResizeObserver` over the strip toggles them, guarded for
  happy-dom); those + the `×` stay unicode bare-glyph affordances.
- **Keyboard model = browser tab bar (ARIA `tablist` + roving tabindex):** the
  whole strip is *one* tab stop. The tab carrying the roving `tabindex=0` is the
  active one (or the first if none active); every other tab is `-1`. **←/→** (and
  Home/End) move *and select* the adjacent tab — selection follows focus, wrapping
  at the ends (`onStripKeyDown` on the `role=tablist` strip, guarded to fire only
  when a `.stage-tab` is the event target, not the `+`). The whole tab is the
  click/select target (no inner button); its `.stage-tab-label` is a caption, so
  it's `user-select: none` (like `.stage-label`) — a drag never selects the text.
  **Clicking a tab focuses it**
  (`e.currentTarget.focus()`) so ←/→ work straight from a click. **The focus ring
  shows in keyboard mode only** — the strip toggles `stage-tabmenu-strip-show-ring`
  when focus arrived by keyboard (tabbed in, or the first Tab/arrow after a click),
  never on a bare click (a deliberate per-tab deviation from the library-wide
  `:focus` rule — it reads better). Modality is tracked with a `tabFromPointer`
  flag (set on a tab `pointerdown`, consumed in `focusin`); the gated rule is
  `.stage-tabmenu-strip-show-ring .stage-tab:focus` with `outline-offset:-1px` so
  it doesn't bleed onto the butted neighbour. The **active** tab's top accent is a
  **2px inset box-shadow** (not a
  border): thick enough to read *through* the 1px focus ring, and box-shadow means
  bumping it to 2px never nudges the label/× (the reserved 1px transparent
  `border-top` keeps layout identical to an inactive tab). The scrollable strip is
  `tabindex=-1` so it never becomes a focusable-scroll-container phantom stop.
- **Controlled + uncontrolled mirrored:** uncontrolled seeds internal signals
  from `initialTabs` (strings → `{id:gen(),label}`) + `defaultActiveId` (else
  first tab); controlled passes `tabs()` (+ usually `activeId()`) and the hooks
  become notification-only (the menu mutates nothing). `onNewTab` returns a
  string label (else `'New tab'`) or `false` to veto; `onClose` returns `false`
  to veto; after a non-vetoed uncontrolled close the active tab re-points
  next→prev→none.
- **Close-glyph reveal is VSCode-style (pure CSS, the button keeps its width so
  the label never shifts):** `.stage-tab-close-x` is hidden on an inactive,
  unhovered tab; shows on the active tab and on `:hover`. A tab may set
  **`modified`** (`TabMenuTab`): a dot (`.stage-tab-dot`) shows by default
  (active or not) and yields to the `×` on hover. The library only renders these;
  deciding *when* a tab is modified is the consumer's (controlled `tabs`).
- **Visual style is blocky VSCode folder tabs:** square corners, butted together
  (no gap), no bottom border so each tab's open bottom flows into the bar's
  bottom border. The menu fills its slot height → it wants a full-height bar slot
  (see the playground's `.playground-tabbar`, a plain full-height div, not a
  centred Toolbar anchor). Inactive tabs brighten on hover; the active tab does
  **not** (marked by a 1px **top** accent line + lifted surface + brighter
  label). Drop in a bar slot (e.g. `topSub`); tabs size off control-height/font.

### Toolbar
One bar with `left` / `center` / `right` anchor cells (`1fr auto 1fr` grid;
center stays centered). The equal tracks exist only to protect that centering, so
an empty center switches the bar to flex (keyed off `:empty`, no prop) and `left` /
`right` share the whole width. Transparent layout only — the hosting region (sub-toolbar
stack / stage bar stack) supplies background + borders. Every bar is a
pre-composed `Toolbar` (or plain JSX), not a registry; stack by listing several
in a slot.

### TitleBar
A **prominent** bar — the same `Toolbar` anchors (it wraps one), but it **paints
itself** with the recessed `--stage-color-bg` + an edge separator (`.stage-title-bar`;
`footer` flips the border to the top edge). This is the deliberate inverse of Toolbar's
"region paints, bar is transparent" rule: TitleBar *is* chrome, so the prominent shade
travels with the component and can sit in **any** bar slot. **It replaces a removed
positional accident** — the `top`/`bottom` `EditorPanels` slots used to be hard-coded
darker (`.stage-top-bar`/`.stage-bottom-bar` painted `--stage-color-bg`) while every
other bar region was panel-bg, so "prominent" was a side effect of *being top/bottom*.
Those slots are now transparent cells; prominence is opt-in via `TitleBar`. (Migration:
a consumer that relied on a dark `top`/`bottom` swaps its `Toolbar`/bespoke div for a
`TitleBar` — no version bump, the slots still accept any JSX.)

### CanvasStage
Multi-layer canvas container with ResizeObserver. Vertical flex: `topBars` stack
/ `.stage-viewport` (`1fr`, holds the layers) / `bottomBars` stack. Bars *inset*
(reflow) the viewport rather than overlaying it; the ResizeObserver watches the
viewport so `onResize` excludes the bars. Source guards
`typeof ResizeObserver !== 'undefined'` (happy-dom).

---

## 6. Field framework (`src/controls/`)

Ported once both consumers grew the same shape. A `Field` layout base +
`FieldGroup`, seven bare value **controls** (Text / Number / Textarea / Color /
Select / Boolean / Slider) each paired with a captioned **field** wrapper of the
same name, a display-only `Label`, a button family (IconButton / IconToggle /
ActionButton / ToggleButton / ButtonGroupControl / ButtonGroupField), and icon fields
(IconButtonField / IconToggleField).

### Control vs Field
The widgets split into two tiers, mirroring the industry hierarchy (Control =
any interactive widget; Field = the captioned, value-bound subset):

- A **`*Control`** is the bare widget — a value (`value` / `onChange`), its
  widget-specific props (`min`/`max`/`step`, `options`/`optionLabels`,
  `placeholder`, `alpha`, `variant`, …), `readonly`, an `aria-label`, plus a
  `level?: 'error' | 'warn'` (→ `data-stage-level` on the widget) and the three
  validation handlers (`onFocusIn` / `onFocusOut` / `onPointerEnter`) it forwards
  onto its root. It renders **only** the widget DOM (the `.stage-input`, the
  `.stage-slider` cluster, the select trigger + portal, the colour hex + swatch +
  popover, the bare switch/checkbox). No caption, no `Field`, no
  `createFieldValidation`. The shared `ControlValidationProps` type
  (`controls/createFieldValidation.ts`) carries `level` + the handlers.
- A **`*Field`** is the captioned row that **composes** the control: it runs
  `createFieldValidation`, wraps `<Field name … fieldType … info … description …>`,
  and renders the bare control inside the render-prop, threading
  `level={v.borderLevel()}` and `{...v.controlHandlers}` through. The control is
  the single source of truth for the widget; the field never re-implements it.
  Example — `SliderField` is just
  `<Field …>{(value) => <SliderControl value={value} … level={v.borderLevel()} {...v.controlHandlers} />}</Field>`.

Both halves are public (the bare control for a consumer composing their own
layout, e.g. a slider in a toolbar; the field for the captioned row). The bare
controls emit the **same widget classes** the fields always did, so the theme is
shared — only the field row (`.stage-field-*`) is absent from a bare control.

**The Boolean exception.** `BooleanField` does *not* compose `BooleanControl`.
Click-the-label-to-toggle needs the caption inside the Kobalte `Switch`/`Checkbox`
root for label association, so the field keeps its own bespoke caption wiring;
`BooleanControl` is a parallel bare widget (the switch/checkbox with no caption,
rooted on `.stage-boolean-control`). It is the one pair that doesn't collapse to
the generic compose-a-control contract.

### Layout
Every row is a `.stage-field-control` carrying a layout class
(`stage-compact` | `stage-expanded`) + a per-type class (`stage-field-{type}`).
`Field` renders the matching skeleton: compact = label | value grid; expanded =
label row (with trailing rule) above a full-width value. Default `compact`; a
control may pin one (`BooleanField` + `ColorField` compact-only, `TextareaField`
expanded-only).

The caption span is **`.stage-field-name`** (matching the `name` prop; the
expanded caption row is `.stage-field-name-row`) — renamed from
`.stage-field-label` so that segment is free for `Label`'s per-type
discriminator.

### Kobalte wrapping
**Most value controls wrap a Kobalte headless primitive** (text-field /
number-field / select / switch / checkbox / slider / color) while keeping our
public accessor+event API; the matching field composes that control and adds the
`Field` layout (complete as of v0.5.0). The exceptions — the button/icon family
and `SearchControl` — are hand-rolled on purpose (see below).

- The button + icon fields stay ours **deliberately, not a gap**: they're
  already native `<button>`s, and Kobalte's `Button` primitive only confers
  button semantics on *non-button* elements, so wrapping buys nothing. The
  rewrite targeted complexity/ARIA machinery (listbox nav, slider
  `aria-valuenow`, the colour area, spinbutton) — which buttons don't have.
- **`SearchControl` is also deliberately ours, not Kobalte.** Kobalte's
  `Combobox` is value-list-bound and can't host the bespoke loading / recents /
  total / empty chrome the search dropdown needs, so the input is a plain
  `<input>` and the dropdown is a hand-rolled `Portal` positioned by
  `@floating-ui/dom` (the same dep `tooltip.ts` uses). It still honours the
  control contract (`data-stage-level`, the `ControlValidationProps` focus/hover
  handlers).
- **The committed value has one render path — `valueRender` (the slot) with plain
  text as its default**, not two branches. The control always renders the
  `<input>` (the accessible value + sole tab stop) *plus* a
  `pointer-events:none` / `aria-hidden` overlay that paints the committed value
  over it **while at rest**; at rest the input's own text goes `transparent` so
  the two don't double (the `::placeholder` colour is pinned, else Firefox derives
  it from the now-transparent text colour and an empty field would show nothing).
  Omit `valueRender` and the overlay paints the plain label — so "plain text" is
  just the slot's default, no separate code path. The slot is **consumer-driven**
  (`() => JSX.Element`, reads the consumer's own signals) rather than handed the
  committed `SearchItem`, because a value seeded from persistence has no picked
  item — the consumer still derives the rich display from the name. Mirrors
  `SelectField`'s `renderOption` (rich trigger), closing the select-vs-search
  asymmetry.
- **"At rest" is gated on `!isEditing()`, not `committed()`** — `committed()` is
  only true after a pick/step, but the overlay must also paint the unfocused
  boot/externally-set value (no pick made). `isEditing()` is `isFocused() &&
  !committed()`; `isFocused` was promoted from a plain `let` to a **signal** so the
  overlay (and the resting-only × clear) re-render on focus change. The one
  pre-existing reader (the external-value→draft sync effect) reads `isEditing()`
  under `untrack` so it still fires on `value()` change only — the focus/commit
  transitions set the draft in their own handlers. The inline × clear is also
  gated to rest (hidden while editing): an × in an actively-typed field is
  confusing, and resting-only means it never fights the overlay.
- **Attached input buttons are one primitive — `InputActions`.** The "buttons
  seamed to the right edge of a text input" pattern (the search ◀▶ stepper, and
  now `TextControl.actions` — copy / apply / reset) lives in a single internal
  presentational component (`controls/InputActions.tsx`) so the joined-seam look
  (squared input edge via `.stage-input-grouped`, shared border, the focus-ring-
  over-seam trick, icon-only vs labelled sizing) is defined once. `InputAction`
  mirrors `SectionHeaderAction` (icon **or** `label`, `title`, `onClick`, reactive
  `disabled`); the buttons are real `<button>`s so they're tab-reachable by default
  (the established stepper behaviour). `SearchControl` feeds its stepper through it
  while keeping the step *logic* (`stepThrough`, committed state) local — the
  primitive is purely the button cluster + CSS, NOT a base the controls extend
  (SearchControl's combobox `<input>` can't be a plain `TextControl`). The type is
  public (`InputAction`); the component is internal (reached via the controls).
- **The search pipeline is factored out and exported** — `controls/search.ts`
  owns the `SearchItem` / `SearchResult` / `SearchContext` / `SearchFn` types,
  **`createSearchSource`** (the debounce + monotonic-token + `AbortController`
  pipeline exposing `{ results, loading, schedule, reset, cancel }`), and
  **`stepThrough`** (the ◀▶ wrap math). `SearchControl` is built on it, and it's
  public so a consumer can compose their *own* search-style control (e.g. a
  live-query "filter" model that keeps the query in the input and shows the
  selection elsewhere) without re-deriving the machinery — paired with a sibling
  `SelectControl` for a category filter (its value passed via `schedule(query,
  filter)` → `SearchContext.filter`) and `createFieldValidation` for the field
  glue. We *evaluated* shipping that filter model as a first-class `FilterControl`
  and **pulled it**: it was one-consumer, fully composable from
  these primitives, and its only non-composable trait — query-in-input +
  selection-below — fights the compact-field thesis. The reusable extraction
  (`search.ts`) is the part that earned its keep. `SearchControl.tsx` re-exports
  the search types so `./SearchControl` import sites stay stable.
- Kobalte ships **zero visuals** — style its parts with `stage-*` classes keyed
  on its `data-*` state attrs (`data-invalid` / `data-disabled` /
  `data-readonly` / `data-checked` / `data-expanded` / `data-highlighted` /
  `data-selected`); no Kobalte stylesheet is imported.
- Slider/Color thumbs are positioned horizontally only by Kobalte (`left%` +
  `translateX(-50%)`, `top` unset) — centre them with `box-sizing: border-box` +
  `top: calc((track − thumb) / 2)`.

### What field and option rendering guarantees

- **`onChange` means a user edited the value.** `NumberControl` drops Kobalte's reports of the
  value it was just given, on mount and on outside changes, so consumers don't need guards.
- **`ButtonGroupControl`, `IconButtonField` and `IconToggleField` render options by position,
  with `Index`.** Inline arrays commonly read signals, which builds new objects on every
  change. A keyed `For` would remount each button and lose keyboard focus. A static slot
  still re-renders when its `render` changes, because reusing it could show stale content.
- **`ReadoutField` is separate from `readonly`.** `readonly` means this editable field is
  locked for now, so it keeps the input's shape and drops pointer events. A readout was never
  editable, so it's plain selectable text with no focus stop.

### The button family & BaseButton
The family shares an **internal `BaseButton`** (NOT exported) so skins can't
drift. It owns the native `<button>` (so `disabled` removes it from the tab
order + blocks click-focus for free), the debounce click wrapper,
`title`/`aria-label`/`aria-pressed`, and the shared `stage-button` class (focus
ring + the disabled cursor `default`, matching every other inert control — not
the OS `not-allowed`). It forces `focus()` on click (for the cross-browser focus
ring, §4). IconButton/ActionButton/ToggleButton are thin skins adding only their
visual classes + children.

- **Naming: `ButtonGroupControl` (not `ButtonGroup`) — the one family member with
  a `*Field` partner follows the `*Control`/`*Field` symmetry.** Buttons are
  actions, not values, so the standalone members keep plain action names
  (`IconButton`, `ActionButton`, `ToggleButton` — no `Control` suffix, no field
  wrapper). But `ButtonGroupControl` *does* have a captioned `ButtonGroupField`
  wrapper, and a consumer who has internalised "`XControl` pairs with `XField`"
  would otherwise hunt for a `ButtonGroupControl` that didn't exist. Discoverability
  of the pair beat the "buttons aren't values, so no `Control` suffix" purity. The
  bare control still emits `.stage-button-group` (class unchanged).
- **`ButtonGroupControl` self-alignment: `justify?: 'start'|'center'|'end'|'fill'`.**
  Opt-in (omit = natural shrink-wrap width, so a `Toolbar` anchor / field value cell
  keeps positioning it). When set, the group spans its container (`width:100%`):
  `start`/`center`/`end` set `justify-content`; `fill` spans + gives the *option*
  buttons `flex:1` to share the width (replaces the old `fill` boolean — folded into
  `justify` for one knob; `kind:'static'` slots aren't stretched, since the group
  can't force flex onto arbitrary JSX). Meaningful in block / `1fr` contexts; a
  `width:100%` group in an `auto`-sized host (a `Toolbar` `center` cell) has nothing
  to fill. `ButtonGroupField` forwards `justify` (buttons within the value cell) and
  keeps its own `align` (a `FieldAlign` that places the cell) — two layers, two
  props, deliberately not the same name.
- **`primary` is the variant default everywhere — a standalone `ActionButton`
  and a `ButtonGroupControl`'s label options both default to it.** `primary` is
  simply "how a button looks normally" (filled input-bg + strong border), and a
  `ButtonGroupControl` is just *multiple buttons behaving normally* — so the
  group must not silently restyle them. An earlier build defaulted the group to
  `ghost` (reasoning: a segmented group reads lighter, and the **active** option
  already carries the accent fill). That was rejected: the library shouldn't
  impose a de-emphasis the consumer didn't ask for, and the standalone-vs-grouped
  discrepancy actively confused a consumer (dsts-viewer). `ghost` stays an opt-in
  (`buttonVariant="ghost"`) for when a consumer *does* want to soften a group.

- **`tabbable?: boolean`** (default true): `tabbable={false}` sets
  `tabindex=-1`, skips click-focus, adds `.stage-button-untabbable`
  (`:focus { box-shadow: none }`) — a mouse-only button (exposed on IconButton).
- **`subtle` variant** on IconButton (`.stage-icon-button-subtle`) for
  secondary/meta actions: muted glyph, shape brightens on hover (no bg), `:active`
  flashes a faint bg, `subtle.active` stays bright-shape with NO accent fill.
  Its rules sit AFTER the default `.stage-icon-button*` rules so they win on the
  equal-specificity `:hover` pairs.
- a11y is just two ARIA attrs: `aria-pressed` on the toggles (and on
  IconButton/ActionButton **whenever `active` is supplied** — omitted otherwise
  so a plain action button stays plain) and `aria-label` (from `title`) on the
  icon-only IconButton.
- **No click "press" animation** — the focus ring (now shown on click too)
  already marks the clicked control, so the old scale-punch was removed as a
  redundant holdover.
- **There is no close button control.** A close is an `IconButton` with an `X`, styled by
  where it sits. A `Section`'s `onClose` appends one to its `headerActions` row, so every
  button there behaves alike. A toast's dismiss has its own skin in `toast.css`. TabMenu's
  tab close stays bespoke: it carries the modified-dot + hover-reveal behaviours and sits in
  a glyph-button family with the `+` / scroll arrows.

### Per-field notes
- **Label** — static, display-only descriptive text (section blurb, status
  line, bar app title). No value, no `onChange`, untouched by `bind()`; the
  consumer drives it via a reactive `text` (Solid props are reactive — no setter
  API needed). `text` is a `LabelContent` = `string | (() => JSX.Element)`: a
  **thunk** carries light inline rich content (chiefly a **hyperlink**) or a live
  status line. The thunk is **called inside the Label's JSX** (`{fn()}`), not
  rendered via `<Dynamic component={fn}>` — `Dynamic` treats it as a component
  invoked once, so a signal read inside a string-returning thunk silently went
  *stale* (the string-form was reactive but a thunk returning the same string was
  not — a quiet footgun). Calling it inline wraps it in Solid's `insert` tracking
  computation, so **both** the string form and any thunk (string- or JSX-
  returning) track inner signals and re-render. Links inside read in the accent
  (`.stage-label a`). Kept deliberately to inline accents — a Label is a caption,
  not a rich-text surface. No caption/value split
  — a single full-width `.stage-label` text element — so it renders a **bespoke
  `.stage-field-control` skeleton** (`fieldType="label"`) instead of going through
  `Field`. Three layouts: `compact` (one line, ellipsis; `nowrap` collapses
  explicit newlines so they truncate too), `expanded` (`pre-wrap`: wraps and keeps
  newlines with **natural prose `line-height: 1.4`** — multiline reads compactly,
  not one control-height per line; a single line still reserves one control-height
  via `min-height` so a short blurb aligns with its neighbours), `bar` (one inline
  content-sized line, no truncation; `align` is a no-op inline). Props: `text`,
  `align` (compact+expanded only → `.stage-label-{center,right}`), `layout`,
  `size`, `class` (the **style hook** — appended to `.stage-label` for consumer
  italic/bold/colour). Replaces all free text in bars.
- **BooleanField** — `variant` `'toggle'` (default, Kobalte switch:
  `.stage-switch` + `.stage-switch-thumb`) | `'checkbox'` (Kobalte checkbox:
  `.stage-checkbox` + CSS-tick `.stage-checkbox-indicator`). Its row
  (`.stage-field-boolean`) overrides the compact grid to `minmax(0,1fr) auto` so
  the label expands to meet a right-anchored control.
- **NumberField** — Kobalte `number-field`: increment/decrement steppers (a
  bordered up/down column inset on the input's right edge) replace the OS
  spinner; they light on hover/press and dim via `data-disabled` at min/max.
  `steppers={false}` hides them; always hidden when `readonly`. Public API
  unchanged (`value: () => number` + `onChange(next)`); the wrapper adapts to
  Kobalte's `rawValue`/`onRawValueChange` internally.
- **TextareaField** — puts the caret at the **start** on *keyboard* focus
  (tabbing in otherwise gives no visible caret and silently appends at the end).
  Pointer focus keeps native placement (caret where you clicked) — distinguished
  by a `fromPointer` flag set on `onPointerDown` (fires before `focus`) and
  cleared each focus.
- **SelectField** — keeps its full surface (`optionLabels`, trailing `actions`,
  `align`, `disabled`); trigger is `.stage-select-trigger` (focusable button),
  Kobalte root is `.stage-select`, caret/items style off
  `data-expanded`/`data-highlighted`/`data-selected`.
- **SearchField** — combobox over an async `search(query, ctx) => Promise<
  SearchResult>` the caller supplies; the primitive owns all chrome. **Selection
  model:** `value()` is the committed label string; picking a result fires
  `onChange(item)` (the full `SearchItem`, incl. the caller's raw `payload`) and
  commits its `label`. **Focus is one simple rule (tab or click alike):**
  select-all the term, always open recents, and wait for typing — no
  pointer-vs-keyboard split. A `dirty` flag stays false until the user types, so
  focusing never fires a search for the committed value; the search kicks off on
  input (≥ `minQueryLength`, default 1). **Keyboard nav:** ↑/↓ move the highlight,
  Enter / click commits via `pick()` (the single handoff). ←/→ are *not*
  intercepted (native text cursor) — **prev/next is the tabbable ◀▶ stepper**
  instead (real buttons, Space/Enter to step `stepItems`; on `:focus` they take a
  box-shadow ring + `z-index` — the button convention — so the ring shows on all
  four sides incl. the shared left seam, painted over the neighbour's border,
  never the browser default ring). On a
  **committed** rest, **Enter re-engages** (re-opens recents + select-all, same as
  clicking back in) — `preventDefault` also swallows Enter's `insertLineBreak`
  beforeinput (null `data`), which the committed-rest branch would otherwise treat
  as a new empty query and clear the field (also guarded in `onBeforeInput`).
  **Dropdown is
  hand-rolled, NOT Kobalte** — full control of the chrome — portalled into the
  nearest `.stage-root` and positioned with `@floating-ui/dom`. It **grows to fit
  content** (the `size` middleware floors `min-width` at the input; CSS
  `width: max-content` + `--stage-search-max-width` caps it); `autoUpdate` runs
  while open (deferred one microtask in the panel ref so the Portal node is
  connected before floating-ui walks its ancestors — else `getComputedStyle` on a
  detached parent throws and aborts the dropdown render), torn down on close/empty.
  **One structure across modes** — header + list + footer — so recents and
  results read the same: recents → "Recent searches" / rows / "{n} recent
  searches"; results → "Search results" / rows / "Showing {n} of {m} results.".
  Each label is a default the consumer overrides as **text or JSX** (`recentsHeader`,
  `resultsHeader`, `recentsEmptyLabel`, `emptyLabel`, `recentsFooter`,
  `resultsFooter`; footers also accept a count fn). Footers + empty states are
  italic. **Request hygiene:** a monotonic token discards stale resolutions and a
  per-request `AbortController` (handed to `search` via `ctx.signal`) cancels the
  in-flight call; input is debounced (`debounceMs`, default 150). **Empty value:**
  by default blurring an emptied field reverts to the committed label; `allowEmpty`
  flips that — empty/whitespace on blur stays empty and fires `onClear` (the
  consumer drops the value), and an inline clear (×) button shows while non-empty
  (`.stage-search-clear`, mouse-only). **Committed rest:** after a pick (or step)
  the input *rests* on the selection — still focused (so Tab works) but the caret
  is hidden (`.stage-search-input-committed` → `caret-color: transparent`) so it
  doesn't read as "ready to type". It reads as both "showing your pick" and "ready
  for new input": a printable keystroke (or paste) restarts the query from empty
  with that text (`beforeinput` blocks the in-place edit and re-seeds the draft) —
  no click/tab needed; a click or tab-in instead select-alls for replacement. When
  a stepper is wired, the resting field's ◀▶ arrow keys drive it (like ↑↓ in a
  dropdown); otherwise the resting keyboard is inert (Tab still moves focus).
  Clicking a ◀▶ button steps *and* lands inert focus on the input (so the arrow
  keys flow straight after) and closes any open dropdown.
  **Stepper:** pass `stepItems` (an ordered
  list accessor — consumer-chosen: current results or whole catalog) to get a ◀▶
  pair attached to the input that cycles the committed selection through that list
  (wrapping), committing each neighbour via `onChange` without opening the
  dropdown. Position is anchored by the last-committed `id` (label-match fallback
  for externally-set values); stepping never records a recent. **Recents** are
  library-managed, opt-in via `recentsKey` (persisted through `loadPersisted`/
  `savePersisted`, version 1, MRU deduped by `id`, capped at `maxRecents`). By
  default they're the verbatim snapshot; **`reconcileRecent`** opts into validating
  each stored recent against the live source right before display — return it
  (optionally refreshed) to keep, `null` to drop a deleted/renamed entry. It's
  **non-destructive** (filters/refreshes the *displayed* recents; the snapshot is
  untouched, so a temporarily-missing entry returns when it resolves) and reactive
  (re-runs as a live catalog changes). Rows
  pick on `onMouseDown` + `preventDefault` so the input keeps focus through the
  click; the default row renders `badge`/`label`/`description` (`itemRender`
  overrides). `SearchItem` / `SearchResult` / `SearchFn` / `SearchContext` are
  public types. (A *filter-style* variant — query-in-input, selection shown
  separately, sibling category filter — is **not** a built-in; it's composed
  consumer-side from `createSearchSource` + `SelectControl` + `createFieldValidation`,
  see Kobalte-wrapping above.)
- **ColorField** (compact-only) — value is a hex string **without** `#`, UPPERCASE
  (`'8A8A8A'`/`'8AF'`; 8-digit when `alpha`). A **single** editable hex box (left) +
  a swatch button (right) anchor right (auto value cell). The swatch opens a
  portalled popover (ColorArea + hue slider + optional alpha slider) — **no second
  hex box**: the picker and the field box edit the same value, so the box stays
  usable while the popover is open. The box's `hexDraft` model shows `#` + uppercase
  hex (the `#` is a **sticky presentation prefix**, stripped back out of the stored
  value); entering it (tab or a focusing click) selects the whole value. Typing
  **filters to hex digits** (`#` and any non-hex stripped), caps to channel width,
  and **live-applies the moment the draft is complete** (3/6 digits, or 4/8 with
  `alpha`); an incomplete draft reverts on blur. **The hex box is the field's single
  tab stop** — the swatch is mouse-only (`tabindex=-1`). Picker dims (not removed)
  when `readonly`. The swatch tile is square (a **definite** `width:
  var(--stage-control-height)`, not `aspect-ratio` — a derived width gives the
  shrink-to-fit trigger button no intrinsic size, collapsing it); the hex box has
  `min-width: 0` and the whole field `max-width: 100%` so the box (not the tile)
  shrinks in place and the full `#RRGGBB[AA]` never overflows.
  - **Popover behaviour.** The popover anchors to the **whole field** (via
    `Popover.Anchor`), not just the swatch — so opening right clears the swatch and a
    left flip clears the hex box instead of covering it. Placement follows
    `FieldLayoutContext`: `'right'` (flips left) in a panel/module, `'bottom'` in a
    `'bar'`; both centred so the arrow points at the field. It's **controlled**
    (`open` signal) and stays open until an interaction lands outside **both** the
    field and the popover — `onInteractOutside` calls `preventDefault()` when the
    target is inside the field, so typing in the hex box never dismisses it; Enter/
    Escape in the box closes it. Kobalte's `Popover.Arrow` (size 8, matching the
    tooltip) auto-matches the popover fill/border; `gutter` is the anchor→arrow-tip
    gap (Kobalte offsets the content past the arrow), set slightly negative so the
    tip laps the field edge.
- **Icon fields** — compact set right-anchors in a content-width column
  (`grid-template-columns: minmax(0,1fr) auto`, like boolean/colour) so the label
  keeps max room and a full compact set never wraps at any tier; overflow is the
  field's `>4 → expanded` switch (`COMPACT_MAX`), not a squeezed row, and
  expanded wraps purely by width (no hard count).

### Readonly
Every value field takes `readonly?: () => boolean`. It maps to the native
`readonly` attribute where one exists (text/number/textarea, ColorField's hex
input) and to `disabled` otherwise (select/boolean/slider, ColorField's swatch).

- A readonly text-like input is inert (`.stage-input[readonly]`: no caret,
  `pointer-events`/`user-select: none`) and visually distinct via **SOLID
  colours** — lighter fill (`--stage-color-input-readonly-bg`), muted text,
  softer border. **Dim readonly with colour, never `opacity`/alpha** (a
  translucent slider knob shows the rail through it).
- Dropped from the tab order: text-likes keep the native `readonly` attr (still
  tabbable) so they get explicit `tabindex={-1}`; the `disabled`-mapped ones are
  auto-skipped; NumberField's steppers are already `-1` (Kobalte).

### Field focus (`id` + `focusField`)
Every value field takes an `id?: string` — a focus/scroll deep-link handle (wire
a link, a toast action, a "jump to setting" button to it). `focusField(id)`
focuses the field's primary control and returns whether it found one.

- For `Field`-based fields the `id` lands on the **row** (`.stage-field-control`);
  `focusField` finds the first *real* focusable inside it (skips `tabindex=-1`
  chrome — swatch / steppers / clear ×), so it lands on the input / select trigger
  / etc. **BooleanField** (bespoke) puts the `id` on its Kobalte `.Input` directly
  (via a conditional `{...(id ? { id } : {})}` spread — Kobalte types `id` as
  non-optional, which trips `exactOptionalPropertyTypes`). `focusField` handles
  both: if the id'd element is itself focusable it's focused, else a descendant is.
- Browsers scroll a focused control into view, so deep-linking to a field in
  another (scrollable) panel scrolls that pane to it for free.
- Decoupled by design: `focusField('x')` works from anywhere (a toast handler, a
  different panel) — no ref threading, since the id is a global DOM handle.
- **Collapsed sections expand first.** A collapsed `Section` keeps its body
  *mounted but height-collapsed + `inert`* (see §5), so the field is always in the
  DOM — `focusField` finds it, walks up expanding any collapsed `Section` ancestors
  (clicking their toggles — synchronous render clears `inert`, persists like a
  manual expand), then focuses. No registry needed, and it works even for a section never opened
  since load (its fields are mounted all along).

---

## 7. Overlay singletons (`src/overlay/`)

### stageTooltip (`overlay/tooltip.ts`)
The library's first global singleton. One self-mounting "speech-bubble" popout.

- A single host element is lazily built on first `show()` and **re-parented**
  (never re-created) into the triggering anchor's nearest `.stage-root` so that
  root's tokens cascade (fallback `document.body`). Positioned by
  `@floating-ui/dom` (`computePosition` + `autoUpdate` + `arrow`,
  `strategy:'fixed'` so it escapes panel `overflow`). `@floating-ui/dom` is a
  direct dep (auto-externalized by vite.config; already transitive via Kobalte).
- Four levels (`info`/`success`/`warn`/`error`) → `stage-tooltip-{level}` skins
  from `--stage-tooltip-{level}-{bg,text,border}` (color-mix tokens). Fade via
  `stage-tooltip-open` + `transitionend`, with a ~300ms fallback timer
  (reduced-motion drops the transition, so teardown can't depend on it).
- **`owner`-gated:** `hide(owner)`/`owns(owner)`/`requestHide(owner)` no-op
  unless that owner holds the bubble (owner = the control element), so a field
  only touches its own.
- **The controller owns auto-hide**, uniformly for fields / info icons /
  imperative callers, via a document `pointermove`: it hides the moment the
  pointer leaves the **union bounding box of anchor + bubble** (padded ~6px),
  which spans the gap between them — no grace timer, no flicker (Nuffle's
  improvement over the original 120ms grace). The open bubble is
  `pointer-events:auto` (inert otherwise) so hovering it reads as the bubble, not
  the field beneath. A capture `pointerdown` hides on an outside click but
  **never when the pointerdown is inside the anchor or bubble** — clicking the
  element a tooltip points at never hides it. A degenerate (zero-size) rect is
  treated as "inside" so hover-hide just doesn't engage (happy-dom / pre-layout).
- **A removed anchor hides the bubble.** A disconnected anchor measures as that same
  zero rect, so the hover check can't catch it. The `autoUpdate` callback checks
  `isConnected` instead, since its observers fire on removal even with no pointer
  movement (touch).
- **Per-session options** are written on every `show()`, so none leak into the next
  session. `placement` sets the side floating-ui prefers. `interactive: false` sets
  `.stage-tooltip-non-interactive` (`pointer-events: none`) and shrinks the hover area
  to the anchor, since the bubble can't be hovered. `onHide` fires when hiding starts,
  or when `show()` replaces the session, before any new state is set. It is cleared
  before it's called, so re-entrant `show()`/`hide()` can't double-fire it, and `hide`
  calls it last so a re-entrant `show()` finds the exit ready to cancel.
- **No crossfade between anchors.** An outside `pointerdown` starts the fade before a
  `click` can call `show()`, and the library can't tell that the press belongs to
  another anchor. Consumers who want a seamless move call `show()` in `pointerdown`
  (same dispatch, so no frame paints between). A stale `transitionend` or exit timer
  can't end the new session, because teardown only acts while `state === 'leaving'`.
- `keepOpen?: () => boolean` (a field passes `() => focused`) suppresses
  pointermove-hide so a focused field survives a stray mouse-out; blur routes
  through `requestHide` (immediate, gated by `keepOpen`).
- The arrow is a rotated square bordered on only its two outer edges (a triangle,
  not a diamond), side chosen from the resolved placement. **One element ever** —
  `hide` releases content but leaves the host in the DOM. SSR-guarded.

### createFieldValidation (`controls/createFieldValidation.ts`)
The one factory the 7 value wrappers share (no 7× focus/hover duplication).
Computes a reactive `result` (helpers FIRST, first failure wins, then `validate`
in a try/catch → `console.error` + treat-as-valid; **never trap the user**,
mirrors `persist.ts`). Exposes `borderLevel` (`error`/`warn` only — info/success
don't recolour) and `controlHandlers` (spread on the control:
`onPointerEnter`/`onFocusIn` show with `keepOpen: () => focused`, `onFocusOut` →
`requestHide`; the controller owns hover-out hide, so no `onPointerLeave`).
`textHelpers` is the shared minLength/maxLength/pattern check.

**Validation REPLACED the old `error?: () => string` prop (breaking):** the
inline `.stage-field-error` line + `.stage-input-invalid` CSS are gone; the cue
is now the border recolour (a `data-stage-level` attr the hook sets on each
control, keyed in fields.css after the focus rules so it out-specifies the focus
white) plus the tooltip. `validationState` stays on the Kobalte primitives for
ARIA only.

### Info bubble (`controls/InfoIcon.tsx`)
`info?: string | (()=>string)` renders the bundled Phosphor `info` glyph
(`InfoIcon`, from the library's own icon set; override via `IconComponent`) beside the caption
(only when `info` set AND `name!==''`). The icon is **mouse-only**
(`tabindex=-1` — power users tabbing fields skip it). Hover opens after a 500ms
delay; click opens immediately (chiefly touch, no hover) and **never hides**.
Hiding is the controller's unified auto-hide; `createInfoTrigger` only schedules
the open. Shares the one tooltip — last `show()` wins; info-close does NOT
restore a validation tooltip (re-shows on next focus/hover). NB BooleanField's
icon sits inside the Kobalte `.Label`, so its onClick must
`preventDefault`+`stopPropagation` or the click also toggles the boolean.

Mixins (`FieldValidationProps` / `TextValidationProps` / `FieldInfoProps`) are
exported and composed onto each value field's props.

### modal (`overlay/modal.tsx`)
The library's second global singleton — one app-level modal for settings-style
flows. Unlike the self-mounting tooltip it needs a one-time `<StageModalHost>`
mounted inside the consumer's `.stage-root`; the `stageModal` controller (`open`
/ `close` / `isOpen`) pokes section-level signals the host reads.

- **`open` takes a *thunk* `() => JSX.Element`, NOT pre-built JSX** — it's called
  from event handlers (no Solid owner), so eager JSX would orphan its effects;
  the host instantiates the thunk under its own owner via `<Dynamic>`.
- The host renders a `fixed inset-0` backdrop (dims + swallows clicks: they
  neither close nor pass through — no backdrop close handler, and being topmost
  it blocks pass-through) wrapping a centred `.stage-modal-container`.
- **The container is a portal mount target the field popovers + tooltip
  recognise alongside `.stage-root`** — the three `.closest('.stage-root')`
  lookups became `.closest('.stage-root, .stage-modal-container')`, so fields
  opened inside the modal portal into the container (the closer match) and stack
  above the dim. The backdrop's `--stage-z-modal` (1050) opens a stacking context
  lifting the whole modal above page-level popovers while keeping a modal field's
  tooltip on top.
- **The container is deliberately NOT a nested `.stage-root`** — that would
  re-assert the `:where(.stage-root)` default tokens and drop consumer overrides
  (a switch's accent went grey inside the modal); as a plain descendant it
  inherits every token cleanly. Its `max-width` is `1.5×` the expanded panel width
  (token-coupled).
- The host owns a11y: **focus trap** (hard Tab **wrap** within
  `focusables(container)` — the Panel tab-stop rule but wrap, not hold),
  **Escape closes**, **focus restored to the opener** on close (captured in
  `open()`, restored in a `createEffect(on(content))`), plus
  `role=dialog` + `aria-modal` + optional `open(..., { label })` → `aria-label`.
- It hosts a single `Section` in its `onClose` (dismissable) mode (§5).

### toast (`overlay/toast.tsx`)
The library's third global singleton — a corner stack of transient notifications.
Like the modal it needs a one-time `<StageToastHost>` inside `.stage-root`; the
`stageToast` controller (`push` / `dismiss` / `clear`) pokes a module-level
`toasts` signal the host renders via `<For>`.

- **`push(opts)` returns an id**; `dismiss(id)` / `clear()` remove. Levels reuse
  the tooltip/validation vocabulary (`info` / `success` / `warn` / `error`) →
  left-border accent off `--stage-color-{level}`. Default level `info`.
- **`message` is `string | (() => JSX.Element)`** — a thunk (not eager JSX) for
  rich content like a link/button, rendered via `<Dynamic>` under the bubble's
  owner so any effects are scoped (mirrors `stageModal.open`'s thunk rule). The
  JSX's own `onClick` wires the toast into the app: call `stageModal.open(...)` to
  deep-link to a dialog, or focus a control. (Focusing a *library field* is a DOM
  `focus()` on its `aria-label`ed input — controls don't expose a `ref`/`id` yet.)
- **Auto-dismiss is owned by each bubble**, not the controller: a `ToastBubble`
  runs its own auto-dismiss timer (default 5000ms; `autoDismissMs: null` pins it)
  and clears it in `onCleanup`, so removing a toast (any path) tears its timer
  down. Keeps the module-level controller timer-free. **Hover pauses the whole
  stack:** a module `hoverCount` (per-bubble `onMouseEnter`/`Leave`, guarded to
  count once and to release on unmount-while-hovered) drives a `paused` accessor;
  a `createEffect` per bubble banks the unspent time and stops the clock while
  `paused`, then resumes with what's left on un-hover — so reading one toast never
  lets its neighbours slip away under the pointer. Hovering *any* toast pauses
  *every* toast (count, not bool, so sliding between bubbles stays paused).
- **Exit is two-phase so the fade-out can play — except the ×.** Each entry carries
  a reactive `leaving` signal. `dismiss(id)` (the API + the auto-dismiss path) sets
  it (the mounted bubble adds `.stage-toast-leaving` → slides+fades) then schedules
  the real `remove(id)` after `TOAST_EXIT_MS` (220ms — the JS mirror of the CSS exit
  duration; a much slower `--stage-toast-motion` only loses the fade tail, the data
  still clears). The entry object is kept **identity-stable** (a per-entry signal,
  not a replaced object) so the keyed `<For>` doesn't remount the bubble mid-fade.
  `dismiss` is idempotent (a second call while leaving is a no-op). **Three paths
  remove outright (no animation):** the **dismiss × button** (demands immediate
  feedback — a user clicking close wants it *gone*), `clear()` (a reset), and the
  overflow `clearHidden` (hidden toasts have no mounted bubble to animate). Enter
  plays inversely: the bubble mounts in `.stage-toast-enter` (edge-offset +
  transparent) and a double-rAF flips it to the resting state so the slide-in
  transition runs. Tests drive the exit delay (and the hover-pause clock) with fake
  timers.
- The host is `pointer-events: none` (empty space passes clicks through; bubbles
  opt back in), an `aria-live="polite"` region, and takes a `placement` prop
  (`bottom-right` default; bottom corners grow upward via `column-reverse`, top
  corners downward). `--stage-z-toast` (1060) sits above the modal (a toast fired
  from a modal action shows over the dim) but below the tooltip. **`contained`**
  swaps `position: fixed` (viewport) for `position: absolute`, so mounting the
  host inside a positioned region (e.g. a `CanvasStage` viewport, which is
  `position: relative; overflow: hidden`) scopes + clips toasts to that region
  rather than the screen corner.
- The dismiss × is an `IconButton` with its own skin in `toast.css` (see §6).
- **Overflow cap:** `limit` (default 5) caps the *real* toasts shown; the excess
  collapses into one pinned "+N more…" indicator whose × clears all the hidden
  ones at once. `hide` (`'oldest'` default / `'newest'`) picks which end collapses
  — visible bubbles keep the live array order, and the indicator sits at the end
  the hidden ones came from. Hidden toasts aren't rendered, so their (bubble-owned)
  auto-dismiss timers are effectively paused until they resurface — fine, since the
  indicator is the explicit handle for them.
- Mirrors the modal's split (singleton + host) rather than the tooltip's
  self-mount: a stack of N live bubbles with per-item timers wants a real Solid
  `<For>` under an owner, not a hand-rolled single element.

---

## 8. State container (`src/state/`)

### createEditorStore&lt;T&gt;
A Solid `createStore`-backed reactive source of truth with optional debounced
localStorage persistence (`{ v, d }` wrapper, discard-on-version-mismatch,
deep-merge-over-defaults load) and a typed `bind(...path)` field binder (depth
1–4 overloads). It is a **store + helper, not a schema/registry**: fields stay
hand-composed and the consumer owns `T`'s shape; `bind` only removes wiring
boilerplate (spread `{...bind(...)}` into the unchanged value field). App
notification is the consumer's `createEffect` — no subscribe API.

### createPersistedToggle(key, default)
A `createSignal`-shaped `[value, setValue]` whose writes mirror to localStorage
(same `readFlag`/`writeFlag` kernel as `Section`/panel collapse). For **chrome/
layout state the library doesn't render itself** — chiefly split-view stage
visibility, where the app owns the `<Show>`/mount decision (a canvas tears down
its GL context on unmount, so only the app can own that) but the *state* belongs
with the other `stage-*` flags, not the versioned editor-content store. The
returned pair can also feed a controlled `collapsed`/`onToggle` slot directly.

### The persist kernel (`state/persist.ts`)
One shared `readFlag`/`writeFlag` pair underpins `Section` collapse, panel collapse
(`EditorPanels.persistKey`), and `createPersistedToggle`. It never traps the user
(read/parse failures are swallowed, mirrored by `createFieldValidation`).

---

## 9. Multi-stage model (sketch)

The recursive-stage layout (§5 EditorPanels) is **still a sketch** (playground
demo only). What's proven: recursion via `embedded`, one shared
`createEditorStore`, per-stage panel-collapse namespacing via `persistKey`, and
the library/app split for visibility (`createPersistedToggle`).

The deliberate asymmetry: a **panel** collapse is library-owned (stays mounted,
shrinks to a strip); a **stage**'s visibility is app-owned structure with
library-owned state (the GL-context-teardown reason above).

Open questions before this leaves "sketch":
- **Stage naming** — no naming/identity scheme yet.
- ~~**Focus/Tab across stages**~~ — *resolved (§4):* one native traversal spans
  the whole stage and a nested stage nests in place; the outermost stage can
  `wrapFocus` to loop.
- **Per-stage *section* persist-key namespacing** — panels are namespaced by
  `persistKey`; sections still key globally by `title`.

---

## 10. Hard rules — what NOT to do

- **Don't add a section registry.** `EditorPanels` takes children (thesis §1).
- **Don't hard-`import` a third-party icon set** (or `clsx`, or any styling
  helper) in library source. Chrome renders the bundled Phosphor set
  (`@dolphinspired/solid-stage/icons`); consumer-supplied icons come through the
  `IconComponent` prop. Styling is CSS variables (thesis §4).
- **Don't add SSR shims** or `typeof window` dances beyond the `ResizeObserver`
  guard. Browser-only (thesis §5).
- **Don't write `!important` anywhere.** Token defaults use `:where()`
  (specificity 0) so consumer overrides win without it (thesis §3).
- **Don't re-export `test-utils.ts` from `index.ts`.** Internal only.
- **Don't broaden the public API surface** without updating this doc *and*
  `README.md`.