@ponchia/ui 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -5,6 +5,105 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.6.7 — 2026-06-15
+
+### Added
+
+- **Tailwind v4 bridge.** `@ponchia/ui/tailwind` / `@ponchia/ui/tailwind.css`
+  ships a CSS-first `@theme inline` bridge, `bronto-dark` and `bronto-oled`
+  custom variants, and source-registration guidance for Tailwind v4 projects.
+  `docs/interop/tailwind.md` documents `@reference` / `@source`, and
+  `examples/tailwind-vite` builds from the packed tarball and browser-smokes
+  the emitted Bronto utilities.
+- **Svelte and Vue lifecycle adapters.** `@ponchia/ui/svelte` exports
+  dependency-free actions over the delegated behavior layer, and
+  `@ponchia/ui/vue` exports directives, plugin helpers, and the shared
+  imperative `useToast()` helper.
+  The SvelteKit example now uses the Svelte adapter, and `examples/vue-vite`
+  covers Vue consumer install/build/runtime smoke from the packed package.
+- **Figma Variables handoff artifact.** `tokens/figma.variables.json` is
+  generated from the token source, exported as
+  `@ponchia/ui/tokens/figma.variables.json`, drift-checked in `check:fresh`,
+  and documented as a local import/sync handoff alongside the DTCG token export.
+- **Report-primitive batch** — four additive opt-in leaves for static reports
+  and explanation surfaces: `ui-figure` (`css/figure.css`) for reusable
+  chart/diagram/media stages with overlay, key and fallback-data slots;
+  `ui-interval` (`css/interval.css`) for host-normalised low/high evidence
+  windows; `ui-clamp` (`css/clamp.css`) for bounded excerpts with CSS-only
+  show-more / show-less; and `ui-highlights` (`css/highlights.css`) for named
+  CSS Custom Highlight API paints (`bronto-evidence`, `bronto-search`,
+  `bronto-current`). All stay out of `dist/bronto.css`; `figure.css` and
+  `highlights.css` join the analytical roll-up.
+- **Background-job state primitive.** `state.css` now includes `ui-job` for
+  persistent asynchronous work: written status, determinate progress via
+  `--job-progress`, optional actions, compact mode, and queued/running/blocked/
+  failed/complete tones. The host still owns polling, retries, cancellation,
+  and announcements.
+- **Workbench splitter primitive.** `workbench.css` now includes
+  `ui-splitter` / `__pane` / `__handle` plus the optional `initSplitter`
+  behavior (`data-bronto-splitter`) for focusable ARIA separator handles,
+  keyboard and pointer resizing, `--splitter-pos` / `aria-valuenow` sync, and a
+  `bronto:splitter:resize` event. React, Solid, Qwik, Svelte, and Vue adapters
+  expose the matching hook/action/directive.
+- **Service identity demo and report kit.** The public demo set now includes
+  `demo/service.html`, a cross-service `ui-app-shell` specimen that keeps the
+  default bundle centered on shared app identity. Static reports get the new
+  opt-in `@ponchia/ui/css/report-kit.css` roll-up for the complete report
+  vocabulary, plus `@ponchia/ui/schemas/report-claims.v1.schema.json` for
+  claim/source sidecar validation.
+- **Public-package hardening gates.** `check:public-hygiene`,
+  `check:variables`, and `check:migrations` are now part of the aggregate
+  `npm run check` chain, covering packed public text leaks, undefined CSS
+  custom-property references, and migration-map/doc alignment.
+
+### Fixed
+
+- **Silent CSS token typos.** `css/workbench.css` now uses the real
+  `--focus-ring` token for splitter focus outlines, and `css/report.css` uses
+  `--text-base` for finding/evidence value text. The new variable-reference
+  gate prevents the same class of no-op declaration from shipping again.
+- **Print: stat tiles and table rows no longer slice across PDF page
+  boundaries** — the report-layer `@media print` break-inside guard covered
+  the report shell (`.ui-report__*`, `.ui-claim`, `.ui-evidence-item`) but
+  not `.ui-stat` tiles, generic `.ui-statgrid` children, or `tr`, so a stat
+  card landing on a page boundary printed half its value on one page and the
+  delta on the next (observed in a consumer report's PDF export). Guarded at
+  the item level — the tile / the row, not the container — so a long
+  statgrid or table can still span pages.
+
+- **Sidenote gutter contract actually works now** — `--sidenote-width` /
+  `--sidenote-gap` are root-scoped instead of declared only on the notes.
+  The documented host wiring (container
+  `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))`)
+  referenced vars an ancestor could never see, so the calc was invalid and
+  silently reserved NO gutter — the floated notes spilled past the page edge
+  (caught by a real report's visual QA). The demo now uses the documented
+  calc verbatim (it previously masked the bug with a hardcoded literal), and
+  a wide-viewport e2e asserts the contract: gutter resolves, float stays
+  on-page, no horizontal scroll. Overriding either knob on the container now
+  re-sizes the notes and the gutter together.
+
+### Changed
+
+- `docs/d2.md` tokenize recipe covers the full embedded-style surface
+  (`.color-*` / `.background-color-*` rules, not just `fill`/`stroke`) and
+  warns that `tooltip:`/`|md` shapes embed GitHub-Primer styling that
+  survives tokenization. `docs/sidenote.md` documents the root-scoped knobs.
+- Local verification is now reproducible through named scripts:
+  `npm run test:e2e:nonpixel` runs every non-screenshot Playwright spec across
+  Chromium, Firefox, and WebKit, while `npm run test:examples` packs the real
+  tarball, builds all examples in temp directories, and browser-smokes the
+  runtime examples. `CONTRIBUTING.md`, `docs/release.md`, and
+  `docs/architecture.md` describe when to use those local gates versus the
+  pinned-container screenshot gate.
+- `check:examples` keeps the example inventory, CI matrix, browser-smoke list,
+  README rows, and preview ports aligned from one registry; `check:dead` now
+  runs in the aggregate `npm run check` chain.
+- README, package metadata, usage docs, workbench examples, and the docs index
+  now frame `@ponchia/ui` as the shared UI identity layer for services, tools,
+  sites, and reports, with reports as an opt-in consumer rather than the center
+  of the package.
+
 ## 0.6.6 — 2026-06-10
 
 Consolidation pass from the 2026-06-10 multi-agent audit: two real PDF-export
@@ -68,13 +167,13 @@ changes, no `MIGRATIONS.json` entry.
   post-0.6.0 leaves. The broadened scan immediately caught the demo/reference
   class defects above. `core.css` imports are now closed over an explicit
   CORE_BUNDLE allowlist in both directions.
-- `ROADMAP.md` / `docs/frontier-primitives.md` reconciled to 0.6.5: the
+- `ROADMAP.md` / `docs/frontier-primitives.md` reconciled to 0.6.7: the
   report/provenance/explanation lane is named the proven core; ui-job,
-  ui-conflict, ui-splitter, the tree roving-focus kernel, and
-  command/workbench follow-ons are explicitly dormant until a real app
-  consumer exists; the 2026-06-09 scout keeps (ui-interval, ui-clamp,
-  ui-highlights) are recorded as report-lane candidates gated behind the
-  routing hub. The adoption stance is stated in ROADMAP.
+  ui-conflict, drag/drop workbench follow-ons, the tree roving-focus kernel,
+  and command follow-ons are explicitly dormant until a real app consumer
+  exists; the 2026-06-09 scout keeps (ui-interval, ui-clamp, ui-highlights) are
+  recorded as report-lane candidates gated behind the routing hub. The adoption
+  stance is stated in ROADMAP.
 
 ## 0.6.5 — 2026-06-09
 

package/README.md

@@ -8,25 +8,27 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first design system for interfaces that explain themselves.** It works in
-plain HTML, every modern framework, and print/PDF, with no component runtime to
-adopt and zero runtime dependencies.
+**A CSS-first identity and UI layer for services, tools, sites, and reports.** It
+works in plain HTML, every modern framework, and print/PDF, with no component
+runtime to adopt and zero runtime dependencies.
 
 The look is a deliberate stance: a neutral monochrome canvas with one rationed
 accent (colour signals, it never decorates), dot-matrix display type, and
 hairline borders — all re-skinnable from a single `--accent` knob (opt-in
 amber-CRT, phosphor-green, and e-ink colorways).
 
-Beyond the standard component set it ships an opt-in analytical & report layer —
-SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text
-marks, a colourblind-safe data-viz palette, and a static/PDF report grammar — for
-dashboards and LLM-authored reports.
+The default bundle is the shared service identity: app shells, navigation,
+forms, tables, feedback, overlays, workflow surfaces, prose, motion and the
+token system that lets each app feel related without sharing a component
+runtime. On top of that it ships opt-in tooling/report layers — workbench panes,
+commands, system state, provenance, figure stages, annotations, legends,
+evidence highlights, intervals, data-viz tokens and a static/PDF report grammar.
 
-### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Static report →](https://ponchia.github.io/bronto-ui/demo/report-standalone.html)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
+### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Service shell →](https://ponchia.github.io/bronto-ui/demo/service.html)  ·  [Static report →](https://ponchia.github.io/bronto-ui/demo/report-standalone.html)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
 The demo is the kitchen sink — every component, light/dark, RTL, live theming.
-The static report is the differentiator in one file: a complete, no-build,
-no-JS, Chromium-PDF-ready report built from the report grammar.
+The service shell shows the shared app identity; the static report shows the
+same system under a no-build, no-JS, Chromium-PDF-ready constraint.
 
 <p>
   <img alt="A research report built with the @ponchia/ui report layer" src="https://raw.githubusercontent.com/Ponchia/bronto-ui/main/demo/_preview-report-research.png" width="49%" />
@@ -48,7 +50,13 @@ and the accent is a spotlight, not a paint bucket. Because everything lives in a
 single `@layer bronto`, your own un-layered CSS overrides the framework with no
 specificity fight and no `!important`.
 
-It ships a complete, accessible **standard component set**, but that's not where it competes — its differentiator is the opt-in **analytical & communication layer** sketched above. The line that holds it together: each primitive owns only its visual grammar and pure geometry — no chart engine, no state, no hit-testing. See **[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)** for the thesis.
+It ships a complete, accessible **standard component set** because that is the
+identity layer every service consumes. Its sharper edge is the opt-in **tooling,
+analytical, and communication layer** sketched above. The line that holds it
+together: each primitive owns only its visual grammar and pure geometry — no
+chart engine, no domain state, no hit-testing. See
+**[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)**
+for the thesis.
 
 ## Install
 
@@ -59,7 +67,7 @@ npm i @ponchia/ui
 Or drop it in with no build step, straight from a CDN:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/bronto.css">
 ```
 
 ## Quick start
@@ -77,7 +85,7 @@ Or drop it in with no build step, straight from a CDN:
 
 > Prefer source leaves through a bundler? Use `@import '@ponchia/ui/css'` (a thin `@import` fan-out) instead. Both resolve the Doto `@font-face` with relative URLs, so there's no `/fonts` path assumption.
 
-> The bundle is the standard component set. The opt-in analytical & report layers — `report.css`, `dataviz.css`, `annotations.css`, `legend.css`, and the rest — are **not** in `bronto.css`; link each one you need from `dist/css/`. For LLM-authored static reports see [docs/reporting.md](docs/reporting.md).
+> The bundle is the standard component set. The opt-in analytical & report layers — `report.css`, `dataviz.css`, `figure.css`, `annotations.css`, `legend.css`, `interval.css`, `clamp.css`, `highlights.css`, and the rest — are **not** in `bronto.css`; link each one you need from `dist/css/`. For LLM-authored static reports see [docs/reporting.md](docs/reporting.md).
 
 **2. Write markup with `ui-*` classes** (primary is the default button; modifiers are opt-in):
 
@@ -130,10 +138,10 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Feedback** — alert/callout, toast, tooltip, `ui-progress` (task) and `ui-meter` (measured value).
 - **Overlay** — modal + drawer on native `<dialog>`, dropdown menu, `ui-carousel` + `ui-lightbox` (gallery, user-driven — not an auto-slider).
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
-- **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
+- **Shells** — a service/app shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
-- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
-- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, figures, chart wrappers and print utilities.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: **figure** stages, SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, a cross-cutting **selection** vocabulary, and CSS Custom Highlight API **highlights**. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust), **interval**, **clamp**, and **lifecycle `state`** leaves.
+- **Reports** _(opt-in)_ — `@ponchia/ui/css/report-kit.css` for a complete static/PDF report vocabulary, or `@ponchia/ui/css/report.css` plus only the leaves a narrow report uses. Covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, `ui-figure` composition, intervals, bounded excerpts, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
 - **Glyphs** — `@ponchia/ui/glyphs`, a 71-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
 - **Colorways** _(opt-in)_ — `data-bronto-skin="amber-crt | phosphor-green | e-ink"`: a root-level recolour of the one accent (OKLCH, per-theme, contrast-gated), never in the default bundle.
@@ -143,13 +151,17 @@ Full generated catalog of every class: **[docs/reference.md](https://github.com/
 
 ## Theming: one knob
 
-Everything accent-colored derives from a single `--accent` variable via `color-mix()`. Re-brand the entire app — both light and dark — with one declaration, globally or scoped to any subtree:
+Everything accent-colored derives from a single `--accent` variable via `color-mix()`. Re-brand the entire app — both light and dark — with root-level, per-theme overrides:
 
 ```css
 :root   { --accent: #2f6df6; }   /* whole app blue   */
-.promo  { --accent: #16a34a; }   /* …or just this section green */
 ```
 
+Scoped `--accent` overrides recolor direct accent uses in that subtree, but the
+derived family (`--accent-text`, `--accent-soft`, focus/dot/ramp tokens) is a
+root-level skin contract. Use the full per-theme recipe in
+[`docs/theming.md`](docs/theming.md) for production rebrands.
+
 Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the default monochrome look is **one skin, not the architecture**.
 
 **One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
@@ -162,7 +174,7 @@ Not an afterthought — a gate. Every contractual token pairing has a declared W
 
 ## Works with anything
 
-The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps, so the core stays zero-dependency.
+The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps. Svelte and Vue get dependency-free lifecycle adapters too: `@ponchia/ui/svelte` exports actions, and `@ponchia/ui/vue` exports directives/plugin helpers over the same behavior layer.
 
 Per-framework getting-started guides + runnable example apps live in the repo:
 
@@ -171,16 +183,17 @@ Per-framework getting-started guides + runnable example apps live in the repo:
 | Vanilla / Vite / plain HTML | [vanilla.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vanilla.md) | [`examples/vanilla-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vanilla-vite) |
 | Astro | [astro.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/astro.md) | [`examples/astro`](https://github.com/Ponchia/bronto-ui/tree/main/examples/astro) |
 | SvelteKit | [sveltekit.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/sveltekit.md) | [`examples/sveltekit`](https://github.com/Ponchia/bronto-ui/tree/main/examples/sveltekit) |
+| Vue | [vue.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vue.md) | [`examples/vue-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vue-vite) |
 | React | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/react-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/react-vite) |
 | Solid | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/solid-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/solid-vite) |
 | Qwik | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/qwik-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/qwik-vite) |
-| Tailwind / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | — |
+| Tailwind v4 bridge / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | [`examples/tailwind-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/tailwind-vite) |
 
 ## Extras
 
-- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` — concrete hex per theme for canvas/SVG/MapLibre).
+- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, `tokens/resolved.json` for concrete values in canvas/SVG/MapLibre, and `tokens/figma.variables.json` for local Figma Variables import/sync scripts).
 - **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json' with { type: 'json' }` in Node ESM, or the same path through a bundler JSON import (resolved hex per theme; series 1 = your accent) plus the opt-in `@ponchia/ui/css/dataviz.css`.
-- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure, claim/evidence/action grammar, source-card bindings, and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
+- **Static reports for LLMs** — add `@ponchia/ui/css/report-kit.css` for the complete report vocabulary, or `@ponchia/ui/css/report.css` plus the specific leaves a smaller report needs. Sidecar claim/source contracts can validate against `@ponchia/ui/schemas/report-claims.v1.schema.json`. Full cookbook: `docs/reporting.md`.
 - **Modern-platform motion** — overlays (modal/drawer/popover), toasts and the `<details>` accordion animate **in and out** with zero JS (`@starting-style` + `allow-discrete`, `::details-content` + `interpolate-size`). Progressive-enhancement extras: `.ui-scroll-progress` / `.ui-scroll-reveal` (scroll-driven, no JS) and `.ui-vt` for View Transitions. All degrade to a static end-state and respect `prefers-reduced-motion`. For smooth **cross-document** navigations, add the document-global one-liner to your own top-level (unlayered) CSS: `@view-transition { navigation: auto; }`.
 - **Editor IntelliSense** — point VS Code at the shipped custom-data file so every token autocompletes in `var(--…)`:
   ```json
@@ -188,7 +201,7 @@ Per-framework getting-started guides + runnable example apps live in the repo:
   ```
 - **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, `docs/package-contract.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
 
-> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, and `/charts`.
+> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. CSS helper subpaths are explicit too, including `/tailwind` for the Tailwind v4 theme/variant bridge. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/annotations`, `/connectors`, `/react`, `/solid`, `/qwik`, `/svelte`, `/vue`, `/skins`, `/charts`, `/mermaid`, `/d2`, and `/vega`.
 > JS subpaths are **ESM-only**. CommonJS consumers should use dynamic
 > `import('@ponchia/ui/behaviors')`.
 

package/behaviors/carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAuK3C"}
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA0K3C"}

package/behaviors/carousel.js

@@ -74,6 +74,9 @@ export function initCarousel({ root } = {}) {
       if (!b) continue;
       if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
     }
+    for (const b of thumbs) {
+      if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
+    }
     if (prevBtn && !prevBtn.hasAttribute('aria-label'))
       prevBtn.setAttribute('aria-label', 'Previous');
     if (nextBtn && !nextBtn.hasAttribute('aria-label')) nextBtn.setAttribute('aria-label', 'Next');

package/behaviors/dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["dialog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA0D3C"}
+{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["dialog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAgE3C"}

package/behaviors/dialog.js

@@ -23,19 +23,19 @@ export function initDialog({ root } = {}) {
   const host = resolveHost(root);
   if (!host) return noop;
   const managedDialogs = new WeakSet();
+  const focusRestorers = new Map();
   const canManageDialog = (dlg, origin) => host.contains(origin) || managedDialogs.has(dlg);
 
   const openFrom = (opener) => {
     const dlg = byIdInHost(host, opener.getAttribute('data-bronto-open'));
     if (!dlg || typeof dlg.showModal !== 'function' || dlg.open) return;
     managedDialogs.add(dlg);
-    dlg.addEventListener(
-      'close',
-      () => {
-        if (opener.isConnected && typeof opener.focus === 'function') opener.focus();
-      },
-      { once: true },
-    );
+    const restoreFocus = () => {
+      focusRestorers.delete(dlg);
+      if (opener.isConnected && typeof opener.focus === 'function') opener.focus();
+    };
+    focusRestorers.set(dlg, restoreFocus);
+    dlg.addEventListener('close', restoreFocus, { once: true });
     dlg.showModal();
   };
 
@@ -72,6 +72,12 @@ export function initDialog({ root } = {}) {
   };
   return bindOnce(host, 'dialog', () => {
     document.addEventListener('click', onClick);
-    return () => document.removeEventListener('click', onClick);
+    return () => {
+      document.removeEventListener('click', onClick);
+      for (const [dlg, restoreFocus] of focusRestorers) {
+        dlg.removeEventListener('close', restoreFocus);
+      }
+      focusRestorers.clear();
+    };
   });
 }

package/behaviors/forms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["forms.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8CAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA6K3C"}
+{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["forms.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8CAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmL3C"}

package/behaviors/forms.js

@@ -29,6 +29,12 @@ export function initFormValidation({ root } = {}) {
   if (!hasDom()) return noop;
   const host = resolveHost(root);
   if (!host) return noop;
+  let priorNoValidate = new Map();
+
+  const suppressNativeValidation = (form) => {
+    if (!priorNoValidate.has(form)) priorNoValidate.set(form, form.noValidate);
+    form.noValidate = true;
+  };
 
   const ensureId = (el, prefix) => {
     if (!el.id) el.id = `${prefix}-${nextFieldUid()}`;
@@ -150,7 +156,7 @@ export function initFormValidation({ root } = {}) {
   const onSubmit = (e) => {
     const form = e.target.closest?.('[data-bronto-validate]');
     if (!form) return;
-    form.noValidate = true;
+    suppressNativeValidation(form);
     const invalid = controlsOf(form).filter((c) => !validateField(c));
     refreshSummary(form, invalid);
     if (invalid.length) {
@@ -165,7 +171,7 @@ export function initFormValidation({ root } = {}) {
     if (!control.willValidate) return;
     const form = control.closest?.('[data-bronto-validate]');
     if (!form) return;
-    form.noValidate = true;
+    suppressNativeValidation(form);
     validateField(control);
     const summary = form.querySelector('[data-bronto-error-summary]');
     if (summary && !summary.hidden)
@@ -183,10 +189,9 @@ export function initFormValidation({ root } = {}) {
     // summary — contradicting the documented contract. (Forms added
     // after init are still covered by the in-handler set.)
     const forms = collectHosts(host, '[data-bronto-validate]');
-    const priorNoValidate = new Map();
+    priorNoValidate = new Map();
     for (const f of forms) {
-      priorNoValidate.set(f, f.noValidate);
-      f.noValidate = true;
+      suppressNativeValidation(f);
     }
     host.addEventListener('submit', onSubmit, true);
     host.addEventListener('focusout', onBlur);
@@ -194,6 +199,7 @@ export function initFormValidation({ root } = {}) {
       host.removeEventListener('submit', onSubmit, true);
       host.removeEventListener('focusout', onBlur);
       for (const [f, v] of priorNoValidate) f.noValidate = v;
+      priorNoValidate.clear();
     };
   });
 }

package/behaviors/index.d.ts

@@ -18,6 +18,7 @@ export { initSpotlight } from "./spotlight.js";
 export { initCrosshair } from "./crosshair.js";
 export { initCommand } from "./command.js";
 export { initSources } from "./sources.js";
+export { initSplitter } from "./splitter.js";
 export type Cleanup = import("./internal.js").Cleanup;
 export type DelegateOpts = import("./internal.js").DelegateOpts;
 export type ThemeStorageOpts = import("./theme.js").ThemeStorageOpts;
@@ -29,5 +30,6 @@ export type LegendToggleDetail = import("./legend.js").LegendToggleDetail;
 export type CrosshairMoveDetail = import("./crosshair.js").CrosshairMoveDetail;
 export type CommandSelectDetail = import("./command.js").CommandSelectDetail;
 export type SourceFocusDetail = import("./sources.js").SourceFocusDetail;
+export type SplitterResizeDetail = import("./splitter.js").SplitterResizeDetail;
 export { applyStoredTheme, initThemeToggle } from "./theme.js";
 //# sourceMappingURL=index.d.ts.map

package/behaviors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;sBAmBa,OAAO,eAAe,EAAE,OAAO;2BAC/B,OAAO,eAAe,EAAE,YAAY;+BACpC,OAAO,YAAY,EAAE,gBAAgB;6BACrC,OAAO,YAAY,EAAE,cAAc;gCACnC,OAAO,YAAY,EAAE,iBAAiB;wBACtC,OAAO,YAAY,EAAE,SAAS;+BAC9B,OAAO,YAAY,EAAE,gBAAgB;iCACrC,OAAO,aAAa,EAAE,kBAAkB;kCACxC,OAAO,gBAAgB,EAAE,mBAAmB;kCAC5C,OAAO,cAAc,EAAE,mBAAmB;gCAC1C,OAAO,cAAc,EAAE,iBAAiB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;sBAmBa,OAAO,eAAe,EAAE,OAAO;2BAC/B,OAAO,eAAe,EAAE,YAAY;+BACpC,OAAO,YAAY,EAAE,gBAAgB;6BACrC,OAAO,YAAY,EAAE,cAAc;gCACnC,OAAO,YAAY,EAAE,iBAAiB;wBACtC,OAAO,YAAY,EAAE,SAAS;+BAC9B,OAAO,YAAY,EAAE,gBAAgB;iCACrC,OAAO,aAAa,EAAE,kBAAkB;kCACxC,OAAO,gBAAgB,EAAE,mBAAmB;kCAC5C,OAAO,cAAc,EAAE,mBAAmB;gCAC1C,OAAO,cAAc,EAAE,iBAAiB;mCACxC,OAAO,eAAe,EAAE,oBAAoB"}

package/behaviors/index.js

@@ -28,6 +28,7 @@
  * @typedef {import('./crosshair.js').CrosshairMoveDetail} CrosshairMoveDetail
  * @typedef {import('./command.js').CommandSelectDetail} CommandSelectDetail
  * @typedef {import('./sources.js').SourceFocusDetail} SourceFocusDetail
+ * @typedef {import('./splitter.js').SplitterResizeDetail} SplitterResizeDetail
  */
 export { applyStoredTheme, initThemeToggle } from './theme.js';
 export { dismissible } from './dismissible.js';
@@ -50,3 +51,4 @@ export { initSpotlight } from './spotlight.js';
 export { initCrosshair } from './crosshair.js';
 export { initCommand } from './command.js';
 export { initSources } from './sources.js';
+export { initSplitter } from './splitter.js';

package/behaviors/internal.d.ts

@@ -19,7 +19,8 @@ export type Cleanup = () => void;
 export type DelegateOpts = {
     /**
      * Event-delegation root; also scopes which controls are queried. Default: `document`.
+     * `null` means a scope was requested but is not ready yet, so the behavior no-ops.
      */
-    root?: Document | Element | undefined;
+    root?: Document | Element | null | undefined;
 };
 //# sourceMappingURL=internal.d.ts.map

package/behaviors/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.js"],"names":[],"mappings":"AA8BA,iEAGC;AAeD,sEAUC;AAED,oDAQC;AAED,yDAMC;AAMD,8DAIC;AAID;;SAMC;AAUD,gDAQC;AAMD,+DAKC;AA9GM,6BAAqB;AAErB,kCAAoD;AAsBpD,uCAAqC;;;;;sBAjC/B,MAAM,IAAI"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.js"],"names":[],"mappings":"AAiDA,iEAIC;AAeD,sEAUC;AAED,oDAQC;AAED,yDAMC;AAMD,8DAIC;AAID;;SAMC;AAUD,gDAQC;AAMD,+DAKC;AAjIM,6BAAqB;AAErB,kCAAoD;AAyCpD,uCAAqC;;;;;sBArD/B,MAAM,IAAI"}

package/behaviors/internal.js

@@ -9,16 +9,34 @@
  *   behavior's listeners/observers.
  *
  * @typedef {object} DelegateOpts
- * @property {Document | Element} [root]
+ * @property {Document | Element | null} [root]
  *   Event-delegation root; also scopes which controls are queried. Default: `document`.
+ *   `null` means a scope was requested but is not ready yet, so the behavior no-ops.
  */
 
 export const noop = () => {};
 
 export const hasDom = () => typeof document !== 'undefined';
 
+function isDelegationHost(value) {
+  if (!value || typeof value !== 'object') return false;
+  if (value.nodeType === 9) {
+    return (
+      typeof value.addEventListener === 'function' && typeof value.querySelectorAll === 'function'
+    );
+  }
+  if (value.nodeType === 1) {
+    return (
+      typeof value.addEventListener === 'function' &&
+      typeof value.matches === 'function' &&
+      typeof value.querySelectorAll === 'function'
+    );
+  }
+  return false;
+}
+
 // Resolve the delegation host from an init call's `root` option, distinguishing
-// three cases so an unattached/null root never silently widens to whole-document
+// cases so an unattached/null root never silently widens to whole-document
 // delegation (the "scoped island hijacks every control" foot-gun):
 //   • root absent/undefined → no scope requested → delegate from `fallback`
 //     (default `document`). This is the intended global-wiring path.
@@ -26,11 +44,13 @@ export const hasDom = () => typeof document !== 'undefined';
 //     framework ref still null at mount). Return null so the caller no-ops
 //     instead of hijacking the whole document.
 //   • root is an element    → use it.
+//   • root is anything else → no-op; the public contract is Document | Element.
 // The bindings (@ponchia/ui/{react,solid,qwik}) emit `root: null` for the
 // not-ready case precisely so this distinction survives across the boundary.
 export function resolveHost(root, fallback = document) {
   if (root === null) return null;
-  return root || fallback;
+  if (root === undefined) return isDelegationHost(fallback) ? fallback : null;
+  return isDelegationHost(root) ? root : null;
 }
 
 // Monotonic counter for auto-minted field / list ids, shared across

package/behaviors/legend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["legend.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmD3C;;;;;YAvEa,MAAM,GAAG,MAAM;;;;YACf,OAAO"}
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["legend.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmF3C;;;;;YAvGa,MAAM,GAAG,MAAM;;;;YACf,OAAO"}

package/behaviors/legend.js

@@ -29,14 +29,18 @@ export function initLegend({ root } = {}) {
   const host = resolveHost(root);
   if (!host) return noop;
   const isButton = (el) => el.tagName === 'BUTTON' || el.getAttribute('role') === 'button';
-  const onClick = (e) => {
-    const item = e.target.closest('.ui-legend__item');
+  const legendFor = (item) => {
     if (!item || !host.contains(item)) return;
     const legend = item.closest('[data-bronto-legend]');
     if (!legend || !host.contains(legend)) return;
+    return legend;
+  };
+  const toggle = (item) => {
+    const legend = legendFor(item);
+    if (!legend) return;
     // The contract requires a real `<button>` (keyboard-operable, focusable). A
-    // non-button item is mouse-only — refuse to toggle it rather than ship a
-    // pointer-only control (WCAG 2.1.1 — C11). The author is warned at bind.
+    // non-button item is mouse-only unless role=button is keyboard-normalized
+    // below — refuse anything else rather than ship a pointer-only control.
     if (!isButton(item)) return;
     const active = item.getAttribute('aria-pressed') !== 'false';
     const next = !active;
@@ -54,23 +58,51 @@ export function initLegend({ root } = {}) {
       }),
     );
   };
+  const onClick = (e) => {
+    toggle(e.target.closest('.ui-legend__item'));
+  };
+  const onKey = (e) => {
+    if (e.key !== 'Enter' && e.key !== ' ') return;
+    const item = e.target.closest('.ui-legend__item');
+    if (!item || item.tagName === 'BUTTON' || item.getAttribute('role') !== 'button') return;
+    e.preventDefault();
+    toggle(item);
+  };
   return bindOnce(host, 'legend', () => {
-    // Warn once per non-button item present at bind: it gets cursor:pointer from
-    // the CSS but is neither focusable nor keyboard-operable (C11).
+    // Normalize role=button entries and warn once per unsupported non-button
+    // item present at bind. A real <button> remains the recommended markup.
+    const legends = [...(host.querySelectorAll?.('[data-bronto-legend]') ?? [])];
+    for (const legend of legends) {
+      for (const el of legend.querySelectorAll('.ui-legend__item')) {
+        if (el.closest('[data-bronto-legend]') !== legend) continue;
+        if (el.tagName === 'BUTTON' && !el.hasAttribute('type')) el.type = 'button';
+        if (
+          el.tagName !== 'BUTTON' &&
+          el.getAttribute('role') === 'button' &&
+          !el.hasAttribute('tabindex')
+        ) {
+          el.tabIndex = 0;
+        }
+      }
+    }
     if (typeof console !== 'undefined') {
-      for (const legend of host.querySelectorAll?.('[data-bronto-legend]') ?? []) {
+      for (const legend of legends) {
         const stray = [...legend.querySelectorAll('.ui-legend__item')].some(
           (el) => el.closest('[data-bronto-legend]') === legend && !isButton(el),
         );
         if (stray) {
           console.warn(
-            '[bronto] initLegend(): interactive legend entries must be <button> (or role="button") to be keyboard-operable — a non-button .ui-legend__item is ignored.',
+            '[bronto] initLegend(): interactive legend entries must be <button> or role="button" — unsupported .ui-legend__item controls are ignored.',
           );
           break;
         }
       }
     }
     host.addEventListener('click', onClick);
-    return () => host.removeEventListener('click', onClick);
+    host.addEventListener('keydown', onKey);
+    return () => {
+      host.removeEventListener('click', onClick);
+      host.removeEventListener('keydown', onKey);
+    };
   });
 }

package/behaviors/splitter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wire focusable ARIA splitters. Each `[data-bronto-splitter]` host contains
+ * two `.ui-splitter__pane` elements separated by one `.ui-splitter__handle`
+ * (`role="separator"`). The behavior keeps `--splitter-pos` and
+ * `aria-valuenow` in sync for keyboard and pointer resizing, then dispatches
+ * `bronto:splitter:resize` with `{ value, orientation }`.
+ *
+ * Bronto owns the control affordance only. The host owns pane content,
+ * persistence, min/max policy, collapse behavior, and any saved layout state.
+ * SSR-safe and idempotent per splitter; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initSplitter({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type SplitterResizeDetail = {
+    /**
+     * The first pane size as a 0..100 percentage.
+     */
+    value: number;
+    /**
+     * Splitter orientation.
+     */
+    orientation: "vertical" | "horizontal";
+};
+//# sourceMappingURL=splitter.d.ts.map

package/behaviors/splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.d.ts","sourceRoot":"","sources":["splitter.js"],"names":[],"mappings":"AAiLA;;;;;;;;;;;;;GAaG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAU3C;;;;;WA3La,MAAM;;;;iBACN,UAAU,GAAG,YAAY"}