@ponchia/ui 0.6.7 → 0.6.9

package/docs/connectors.md

@@ -41,6 +41,17 @@ import { initConnectors } from '@ponchia/ui/behaviors';
 const stop = initConnectors(); // redraws on resize/scroll; returns a cleanup
 ```
 
+For static SVG output, author the same parts directly: `.ui-connector__path`
+holds the line path, and `.ui-connector__end` holds an optional arrowhead/dot
+path from `arrowHead()` or `dotMark()`.
+
+```html
+<svg class="ui-connector ui-connector--accent" aria-hidden="true">
+  <path class="ui-connector__path" d="M20,10C48,10 72,50 100,50" />
+  <path class="ui-connector__end" d="M100,50L92,46L92,54Z" />
+</svg>
+```
+
 A connector is decorative — mark it `aria-hidden="true"` and make sure the
 relationship it depicts is also clear from the content/DOM order.
 
@@ -81,6 +92,11 @@ const head = arrowHead(to, angle); // place at the endpoint
 - `endTangentAngle(from, to, shape)` — the angle the path *arrives* at `to`
   (chord for `straight`, axis-aligned for `elbow`/`curve`); rotate an end marker
   by this so it points along the path. `connectRects().angle` already uses it.
+- Low-level scalar/SVG kernel helpers are exported for hosts that need the same
+  rounding and guard semantics as the path builders: `PRECISION`,
+  `roundNumber(value)`, `fmt(value)`, `point(x, y)`, `finite(name, value,
+  fallback)`, `dimension(name, value, fallback)`, `clamp(value, min, max)`, and
+  `rectPath(left, top, right, bottom)`.
 
 ## Coordinate model
 

package/docs/crosshair.md

@@ -48,7 +48,7 @@ document.querySelector('[data-bronto-crosshair]').addEventListener(
 | `ui-crosshair` | The overlay. Hidden until `.is-active` (set on the first pointer move over the plot). |
 | `ui-crosshair__line` + `--x` / `--y` | Vertical / horizontal rule, positioned by `--crosshair-x` / `--crosshair-y`. |
 | `ui-crosshair__badge` | An axis value chip (you set its text + edge). |
-| `ui-readout` | A pinned readout chip; follows the crosshair point. |
+| `ui-readout` inside `.ui-crosshair` | A pinned readout chip; follows the crosshair point and flips before/above near plot edges via `data-readout-inline` / `data-readout-block`. Standalone `.ui-readout` remains the dot-matrix numeric row from `dots.css`. |
 
 `ui-crosshair--muted` is a subtler neutral crosshair. `ui.crosshair({ muted })`
 builds the class string. Include only the lines you need (just `--x` for a

package/docs/dots.md

@@ -62,7 +62,7 @@ container MUST carry a host-written `role="img"` + `aria-label` with the exact
 value — rounding to whole cells is presentation-only, so keep the figure in the
 label (WCAG 1.4.1).
 
-### `.ui-matrix` cell grid
+### `.ui-dotmatrix` cell grid
 
 `.ui-dotmatrix` is the raw data-bound grid (the one the glyphs render on): a grid
 of `.ui-dotmatrix__cell` (with `--hot` / `--accent` tones) plus the `--reveal` /
@@ -125,6 +125,9 @@ Knobs: `--v`, `--gauge-size`, `--gauge-sweep` (default 270deg), `--gauge-from`,
 The row wrapper produced by `renderReadout` (see `docs/glyphs.md`) — a Nothing-style
 hero numeric composed from digit glyphs. Tune character spacing with
 `--readout-gap`; spaces render as a `.ui-readout__spacer` of width `--readout-space`.
+Large multi-character readouts are intentionally intrinsic; on narrow report or
+demo pages, either tune the glyph dot size or wrap the readout in a local
+keyboard-focusable horizontal scroller so it does not widen the page.
 
 ### `.ui-spark--dots`
 

package/docs/glyphs.md

@@ -49,6 +49,17 @@ the same as a hot `#` cell (both become opaque mask regions).
 | `render` | `'mask'` | — | the one-node `.ui-icon` path |
 | `size` | CSS length | `1em` | with `render: 'mask'`, the icon size (`--icon-size`) |
 
+## Registry and lower-level helpers
+
+The public registry is intentionally plain data:
+
+- `GLYPH_SIZE` is the grid edge length.
+- `GLYPHS` is the frozen name → bitmap registry.
+- `GLYPH_NAMES` is the sorted, frozen name list.
+- `glyph(name)` returns the raw bitmap rows or `undefined`.
+- `glyphCells(name)` returns the 256 row-major cell descriptors.
+- `glyphMask(name)` returns the CSS `url(...)` value used by the mask renderer.
+
 ## Big numeric readout — `renderReadout`
 
 Compose digits and punctuation into a row of dot-matrix glyphs — the

package/docs/interop/react-flow.md

@@ -0,0 +1,89 @@
+# React Flow interop
+
+`@ponchia/ui` does not wrap or depend on React Flow / Xyflow. Use React Flow as
+the renderer and keep graph state, layout, hit-testing, and node components in
+the host application.
+
+The one Bronto-specific gotcha is the base media reset:
+
+```css
+img,
+svg {
+  display: block;
+  max-inline-size: 100%;
+}
+```
+
+That reset is correct for normal inline SVGs, report figures, icons, and rendered
+diagrams. React Flow edge SVGs are different: the edge layer uses absolutely
+positioned SVG wrappers that paint by overflow. If `max-inline-size: 100%` is
+allowed to constrain those wrappers, edges can disappear or clip.
+
+## Edge SVG escape hatch
+
+Scope the escape hatch to the React Flow surface in your app stylesheet. Keep it
+un-layered, or place it in an app layer declared after `bronto`.
+
+```css
+/* app.css */
+@import '@ponchia/ui';
+
+.flow-surface .react-flow__edges svg,
+.flow-surface .react-flow__edge svg {
+  display: initial;
+  max-inline-size: none;
+  overflow: visible;
+}
+```
+
+```tsx
+import { ReactFlow } from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+
+export function GraphView() {
+  return (
+    <div className="flow-surface">
+      <ReactFlow nodes={nodes} edges={edges} />
+    </div>
+  );
+}
+```
+
+Do not remove Bronto's global SVG reset to fix this. The incompatibility is
+specific to React Flow's edge-layer geometry, so the override should stay scoped
+to the canvas.
+
+## HTML edge labels
+
+If you use React Flow's `EdgeLabelRenderer`, remember that labels are HTML
+overlays, not SVG text. Container/group nodes can paint over them. Lift the label
+overlay only inside the graph surface, and keep labels pointer-transparent unless
+they are deliberately interactive:
+
+```css
+.flow-surface .react-flow__edgelabel-renderer {
+  z-index: var(--z-raised, 10);
+}
+
+.flow-surface .flow-edge-label {
+  pointer-events: none;
+}
+```
+
+For dense operational diagrams, prefer sparse edge labels plus a side inspector
+for detail. Use Bronto primitives inside nodes or inspectors (`ui-badge`,
+`ui-dot`, `ui-property`, `ui-legend`) rather than adding a Bronto graph-node
+component before a second consumer proves the pattern repeats.
+
+## What belongs in the app
+
+Keep these outside `@ponchia/ui`:
+
+- authored or automatic node placement;
+- graph data models and domain status names;
+- brand/product icons;
+- animation semantics, such as travelling reconciliation dots;
+- click/hover selection behavior.
+
+Bronto should provide the visual vocabulary and interop recipe. The graph
+renderer and product meaning remain the host application's job.

package/docs/migrations/0.2-to-0.3.md

@@ -74,7 +74,7 @@ declarations are literal unions.
 ## Deprecation policy
 
 From 0.3.1 onward, removals follow the policy in
-[CONTRIBUTING.md](../../CONTRIBUTING.md#deprecation-policy): a class is
+[stability.md](../stability.md#deprecation-policy): a class is
 deprecated for **one minor** (kept working, marked in CHANGELOG +
 `MIGRATIONS.json`) before it is removed. 0.2 → 0.3 predates this policy,
 which is why it was a hard cut.

package/docs/package-contract.md

@@ -169,6 +169,7 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/workbench.md` | `./docs/workbench.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/command.md` | `./docs/command.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/interop/tailwind.md` | `./docs/interop/tailwind.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/interop/react-flow.md` | `./docs/interop/react-flow.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.2-to-0.3.md` | `./docs/migrations/0.2-to-0.3.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.3-to-0.4.md` | `./docs/migrations/0.3-to-0.4.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.4-to-0.5.md` | `./docs/migrations/0.4-to-0.5.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -266,6 +267,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/workbench.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/command.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/interop/tailwind.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/interop/react-flow.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.2-to-0.3.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.3-to-0.4.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.4-to-0.5.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -282,15 +284,15 @@ result. The listed gates are part of `npm run check`.
 
 | Surface | Source of truth | Generated outputs | Generator | Gate | Note |
 | --- | --- | --- | --- | --- | --- |
-| Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh | The complete export/file matrix in this document is generated from the manifest. |
+| Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh; check:exports; check:pack; check:consumer-surface; check:consumer-types; check:publint; check:attw | The complete export/file matrix in this document is generated from the manifest; packed tarball imports, concrete file resolution, and package-level type resolution are smoke-tested in clean consumers. |
 | Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/figma.variables.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; figma:variables:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved and Figma handoff values are visual tuning before 1.0. |
 | Class registry | `classes/index.js plus css/*.css selectors` | classes/classes.json; classes/index.d.ts; classes/vscode.css-custom-data.json; docs/reference.md | `npm run classes:json:build; dts:build; vscode:build; reference:build` | check:fresh; check:classes; check:contract | The typed registry, JSON vocabulary, and generated reference stay aligned with real selectors. |
-| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (46 layered outputs) | `npm run dist:build` | check:dist; check:exports | Default bundle and direct layered leaf imports are generated from authored CSS and size-gated. |
-| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:attw; check:publint | Declarations are emitted from the shipped JS, not separately maintained. |
-| Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; npm test | Glyph names and render options are public. The registry stays sorted and type-covered. |
+| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (46 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
+| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/; svelte/; vue/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
+| Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; check:unit | Glyph names and render options are public. The registry stays sorted and type-covered. |
 | Display colorways | `tokens/skins.js` | css/skins.css; tokens/skins.d.ts | `npm run skins:build` | check:skins; check:contrast | Skins are opt-in root-level choices and never part of dist/bronto.css. |
 | Chart palette | `tokens/charts.js` | css/dataviz.css; tokens/charts.json; tokens/charts.d.ts | `npm run charts:build` | check:charts | Data-viz colors are opt-in, CVD-gated, and never UI chrome. |
-| External renderer themes | `tokens/mermaid.js; tokens/d2.js; tokens/vega.js` | tokens/{mermaid,d2,vega}.{js,json,d.ts} | `npm run mermaid:build; d2:build; vega:build` | check:mermaid; check:d2; check:vega | Renderer configs use resolved colors because the external renderers cannot consume CSS variables directly. |
+| External renderer themes | `tokens/mermaid.js; tokens/d2.js; tokens/vega.js` | tokens/{mermaid,d2,vega}.{js,json,d.ts} | `npm run mermaid:build; d2:build; vega:build` | check:mermaid; check:d2; check:vega; check:unit | Renderer configs use resolved colors because the external renderers cannot consume CSS variables directly; unit tests prove helper defaults and Vega render landing. |
 | Contrast report | `tokens/resolved.json; tokens/skins.js; tokens/charts.js` | docs/contrast.md | `npm run contrast:build` | check:contrast | WCAG floors are hard-gated; APCA is reported as advisory. |
 
 ## Internal Paths

package/docs/reporting.md

@@ -54,18 +54,18 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/css/report-kit.css" />
 ```
 
 Leaf-by-leaf CDN imports use the same `dist/css/` paths:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -87,8 +87,8 @@ the default bundle — add the leaves a given report actually needs.
 `@ponchia/ui/css/analytical.css` is a convenience roll-up of the **nine
 figure/evidence-layer leaves only** (figure, annotations, legends, marks,
 connectors, spotlight, crosshair, selection, highlights) — sources, generated,
-state, interval, clamp, and the prose/evidence leaves below are NOT in it and
-must be linked individually. Reach for:
+state, interval, clamp, workbench, command, and the prose/evidence leaves below
+are NOT in it and must be linked individually. Reach for:
 
 | Layer | Import | Reach for it when… |
 | --- | --- | --- |
@@ -98,12 +98,20 @@ must be linked individually. Reach for:
 | **Interval** (`.ui-interval*`) | `css/interval.css` | Evidence is a low/high estimate, confidence window, target band, or uncertain reading. The host normalises `--lo`, `--hi`, and optional `--v`; Bronto only paints the range and point. See [interval.md](./interval.md). |
 | **Clamp** (`.ui-clamp*`) | `css/clamp.css` | A source excerpt, claim basis, or caveat should scan as a bounded text block but remain reachable through explicit "Show more" / "Show less" labels and print expansion. See [clamp.md](./clamp.md). |
 | **Highlights** (`.ui-highlights`) | `css/highlights.css` | The host registers CSS Custom Highlight API ranges for cited evidence, search hits, or the current match without wrapping DOM text nodes. See [highlights.md](./highlights.md). |
+| **Chart palette** (`--chart-*`) | `css/dataviz.css` | A figure needs categorical, sequential, or diverging chart colours. The palette is opt-in, CVD-gated, and never UI chrome. See [theming.md](./theming.md#data-viz-palette). |
 | **Annotations** (`.ui-annotation*`) | `css/annotations.css` | A figure needs an explicit callout — a peak, a limit, a watched region — or a small decorative margin mark. SVG only. See [annotations.md](./annotations.md) and the [off-chart + scaling notes](./annotations.md#using-annotations-off-chart) before you size one. |
+| **Connectors** (`.ui-connector*`) | `css/connectors.css` | A note, card, or region needs a leader line to another DOM element. Bronto supplies overlay styling plus pure SVG path geometry; the host owns layout and meaning. See [connectors.md](./connectors.md). |
 | **Legends / data keys** (`.ui-legend*`) | `css/legend.css` | A chart figure needs a colour key. WCAG 1.4.1 by construction. See [legends.md](./legends.md). |
+| **Spotlight** (`.ui-spotlight*`, `.ui-tour-note*`) | `css/spotlight.css` | A screen report or guided workflow needs a visual focus cutout and callout note. It is not a tour engine; the host owns step order, persistence, and focus movement. See [spotlight.md](./spotlight.md). |
+| **Crosshair / readout** (`.ui-crosshair*`, `.ui-readout`) | `css/crosshair.css` | A plot needs pointer-tracking ruler lines and a readout chip. Bronto reports pixels/fractions; the host maps those to data values with its own scales. See [crosshair.md](./crosshair.md). |
+| **Selection emphasis** (`.ui-sel*`) | `css/selection.css` | Host-owned brush, filter, or selection logic needs a shared visual state vocabulary for selected / excluded / candidate items. See [selection.md](./selection.md). |
 | **Mermaid theme** (`@ponchia/ui/mermaid`) | _(JS/JSON, no CSS)_ | The report embeds a [Mermaid](https://mermaid.js.org) diagram (flowchart, sequence, pie…) and you want it on-brand instead of generic. A resolved `base` theme projected from the same tokens as `charts.json`; annotate the rendered SVG with the annotation layer. See [mermaid.md](./mermaid.md). |
 | **D2 theme** (`@ponchia/ui/d2`) | _(JS/JSON, no CSS)_ | The report embeds a [D2](https://d2lang.com) diagram and you want it on-brand. Resolved theme-override slots (monochrome base + one rationed accent) projected from the same tokens; annotate the rendered SVG. See [d2.md](./d2.md). |
+| **Vega theme** (`@ponchia/ui/vega`) | _(JS/JSON, no CSS)_ | The report embeds a live or generated Vega-Lite chart and you want token-matched axes, text, legends, and ramps. See [vega.md](./vega.md). |
 | **Generated-content trust** (`.ui-generated`, `.ui-origin-label`, `.ui-reasoning`, `.ui-tool-log`) | `css/generated.css` | The report (or a section of it) is AI/system-authored and should _say so_ — an origin label plus quiet, collapsible reasoning / tool-call logs. Pairs with the sources layer. See [generated.md](./generated.md). |
 | **Lifecycle / system state** (`.ui-state`, `.ui-syncbar`) | `css/state.css` | A status report needs to show the state a thing is in — saving / queued / stale / conflict / reviewed — as a labelled object, not a bare coloured dot. See [state.md](./state.md). |
+| **Workbench surfaces** (`.ui-inspector`, `.ui-property`, `.ui-selectionbar`, `.ui-splitter`) | `css/workbench.css` | A screen report or analytical tool needs an inspector, property rows, selected-item actions, or resizable panes. Not in `report-kit.css`; pair splitters with `initSplitter`. See [workbench.md](./workbench.md). |
+| **Command palette** (`.ui-command*`) | `css/command.css` | A screen report or analytical tool needs a searchable command shell. Not in `report-kit.css`; pair with `initCommand` and a host-owned opener/action registry. See [command.md](./command.md). |
 | **Spark** (`.ui-spark*`) | `css/spark.css` | A trend belongs _inside a sentence or table cell_ — a word-sized inline microchart, the inline counterpart to `ui-delta`/`ui-num`/`ui-stat`. See [spark.md](./spark.md). |
 | **Bullet graph** (`.ui-bullet*`) | `css/bullet.css` | A measure needs "inside budget? vs target?" at a glance — the canonical SLO / error-budget figure that `ui-meter` structurally cannot express. See [bullet.md](./bullet.md). |
 | **Diff** (`.ui-diff*`) | `css/diff.css` | The report shows what _changed_ — code review, changelogs, version history, config diffs. Marks call out a sentence; diff calls out a line. See [diff.md](./diff.md). |
@@ -117,8 +125,11 @@ must be linked individually. Reach for:
 
 These compose with the report-native primitives already called out in
 [Composition rules](#composition-rules): `ui-statgrid`, `ui-alert`, `ui-table`,
-`ui-timeline`, `ui-meter`, and `ui-num`. None of them require behavior JS, so
-they are all safe in the static, PDF-first report path.
+`ui-timeline`, `ui-meter`, and `ui-num`. The static leaves do not require
+behavior JS, so they are safe in the PDF-first report path. `workbench.css` and
+`command.css` are deliberately screen-tool leaves: they stay out of
+`report-kit.css` and only become interactive when the host imports the matching
+behavior JS.
 
 ## Canonical skeleton
 
@@ -868,7 +879,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.9/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/stability.md

@@ -11,28 +11,75 @@ For the exhaustive package-manifest inventory — every `exports` key, every
 shipped `files` entry, and the generated artifact provenance map — see
 [package-contract.md](./package-contract.md).
 
+## Path To 1.0
+
+`1.0.0` is a stability declaration, not a catalog milestone. The package is
+ready for 1.0 when the existing public contract is boring to upgrade:
+
+- **Core boundary settled.** The default bundle contains shared app/service
+  identity only. Report, analytical, provenance, generated-content, renderer,
+  workbench, and command surfaces remain opt-in unless they solve universal
+  application chrome.
+- **Refusal list enforced by review.** The package still refuses chart scales,
+  data fetching, persistence, routing, workflow execution, global action
+  registries, virtualized grids, framework component APIs, theme marketplaces,
+  and second-accent visual systems.
+- **Consumer proof is routine.** Packed tarball checks, packed example builds,
+  packed TypeScript resolution, and at least one real downstream upgrade prove
+  each release candidate; source-tree checks are not treated as enough.
+- **Generated contracts stay registry-backed.** Exports, shipped docs, CSS
+  leaves, examples, generated artifacts, visual baselines, and ownership
+  matrices derive from shared local registries wherever possible.
+- **Bundle budget has headroom.** The default CSS bundle and tarball size have
+  deliberate margin, or any budget increase is explicit in the changelog.
+- **Deprecation history is clean.** Every breaking change has a changelog note,
+  migration entry when machine-actionable, and the deprecate-one-minor policy
+  has been followed or explicitly exempted for provably-unreferenced surface.
+
+### 1.0 Readiness Ledger
+
+This ledger is the release-candidate checklist. A row is ready only when the
+evidence column is green for the candidate commit; prose approval alone is not
+enough.
+
+| Criterion | Current evidence | 1.0 bar |
+| --- | --- | --- |
+| Core boundary settled | `check:exports`, `check:dist`, `check:component-matrix`, `check:report`, and the `CORE_BUNDLE` registry keep default CSS, opt-in leaves, and report/analytical surfaces separate. | No unexplained growth in the default bundle; any move from opt-in to core is called out in `CHANGELOG.md`. |
+| Refusal list enforced by review | `test/analytical-boundary.test.mjs`, `check:contract`, `check:behavior-matrix`, `check:helper-matrix`, and review against `docs/architecture.md` keep scales, routing, persistence, workflow execution, global action registries, and framework component APIs out of package-owned behavior. | No public helper, behavior, or doc implies Bronto owns application state, data, routing, workflow execution, or framework component rendering. |
+| Consumer proof is routine | `check:pack`, `check:consumer-surface`, `check:consumer-types`, `check:examples`, `check:publint`, and `check:attw` prove the packed npm artifact before release; the release process requires a public-safe Release evidence note. | Every 1.0 candidate has packed import/type/example proof plus at least one real downstream upgrade note that names the consumer class, imported surface, and result without leaking private repo or product names. |
+| Generated contracts stay registry-backed | `check:fresh`, `check:classes`, `check:dts-emit`, `check:doc-links`, `check:public-metadata`, `check:public-hygiene`, and the matrix gates prove generated artifacts, shipped docs, public hygiene, and ownership maps do not drift. | New public surface has one registry/source of truth before it gets a hand-authored gate row. |
+| Bundle budget has headroom | `check:dist`, `check:public-metadata`, `check:pack`, and the README size badge keep default bundle and tarball claims visible. | Budget increases are intentional, reviewed, and named in `CHANGELOG.md`; accidental growth fails before release. |
+| Deprecation history is clean | `check:migrations`, `check:release`, `check:versions`, `MIGRATIONS.json`, and this deprecation policy tie breaking changes to changelog and migration evidence. | No removal ships without either a deprecate-one-minor trail or an explicit BREAKING note for provably-unreferenced surface. |
+
+After 1.0, breaking changes move to majors. Until then, the table below is the
+current public-surface matrix and the release policy above still applies.
+
 | Surface | Stability | Contract |
 | --- | --- | --- |
 | CSS package root (`@ponchia/ui`) | Stable | CSS-only entrypoint. CSS side-effect imports are supported in CSS-aware bundlers; Node/runtime JS root imports are not. |
 | JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
 | CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
-| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
-| Class vocabulary as data (`@ponchia/ui/classes.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and its entries are public — for validating markup from a non-JS/non-TS host. Generated from `cls` (the `classes` list cannot drift from the CSS); `states`/`customProperties` are gated against the stylesheet. New classes/hooks are additive. |
+| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, `attrs`, recipe names, ARIA attribute helper names, and option unions are public. |
+| Class vocabulary as data (`@ponchia/ui/classes.json`, `@ponchia/ui/vscode.css-custom-data.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and class/custom-property entries are public — for validating markup from a non-JS/non-TS host or editor integration. Generated from `cls` and CSS selectors; `classes.json`, `.d.ts`, reference docs, and VS Code custom data are drift-checked together. New classes/hooks are additive. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
-| Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
-| Schemas (`schemas/*.schema.json`) | Stable additive | Declarative JSON Schema contracts for package-adjacent tooling data. Existing schema files and enum values are public within a compatible minor; new optional properties and new schema files are additive. No validator runtime ships. |
+| Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`, `tokens/figma.variables.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers and handoff tooling. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). `tokens/figma.variables.json` mirrors the token contract for local Figma Variables import/sync. Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
+| Schemas (`schemas/*.schema.json`, `schemas/report-claims.v1.schema.json`) | Stable additive | Declarative JSON Schema contracts for package-adjacent tooling data. Existing schema files and enum values are public within a compatible minor; new optional properties and new schema files are additive. No validator runtime ships. |
 | Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. Computed-style smoke tests guard that the presets apply to their intended token families. |
+| Tailwind v4 bridge (`@ponchia/ui/tailwind`, `@ponchia/ui/tailwind.css`) | Stable additive | CSS-only token/variant bridge for Tailwind v4. It maps Bronto tokens and variants into Tailwind namespaces; it must not import Bronto component CSS or change the default bundle. |
 | Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
 | Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
 | Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
 | `.ui-icon` mask renderer | Stable | Class name, `--icon-size`, currentColor inheritance, and `--icon-mask` contract are public. The internal data URL encoding is not. |
 | Framework lifecycle adapters (`react`/`solid`/`qwik`/`svelte`/`vue`) | Stable thin adapters | Hook/action/directive names, optional peer behavior where applicable, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
-| Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
-| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
+| Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. Skin CSS is opt-in, not in the default bundle. |
+| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
+| External renderer themes (`@ponchia/ui/mermaid`, `@ponchia/ui/mermaid.json`, `@ponchia/ui/d2`, `@ponchia/ui/d2.json`, `@ponchia/ui/vega`, `@ponchia/ui/vega.json`) | Stable additive | Theme helper names, JSON shapes, and supported renderer theme slots are public. Values are resolved colours because Mermaid, D2, and Vega cannot consume Bronto CSS variables directly. Exact colours may tune with token changes, but `check:mermaid`, `check:d2`, and `check:vega` must prove every exported theme resolves with no `var()` leaks. No renderer runtime ships. |
+| Shiki theme data (`@ponchia/ui/shiki/nothing.json`) | Stable additive | The bundled Shiki theme JSON shape and token-derived scope roles are public for syntax-highlighting consumers. Exact colours may tune with the token model and must stay generated from the governed palette. |
 | Reports (`css/report.css`, `.ui-report*`, print utilities) | Stable additive | Report class names, BEM part names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`; charting is via the Vega theme target (`@ponchia/ui/vega`, see [vega](./vega.md)) or a token-themed inline SVG, not a shipped renderer. |
 | Report kit roll-up (`css/report-kit.css`) | Stable additive | A convenience `@import` of the complete static-report vocabulary. The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
-| Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
+| Figure stage (`css/figure.css`, `.ui-figure*`) | Stable additive | Figure class names, overlay/key/fallback-data slots, and report composition hooks are public. Opt-in, not in the default bundle. Bronto owns the figure frame, not chart rendering, scales, or data mapping. |
+| Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. Opt-in, not in the default bundle. Rich placement, renderer, editing, and chart/diagram adapter APIs belong to the sibling `@ponchia/annotations` package; `@ponchia/ui` does not depend on it at runtime or through public declarations. |
 | Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
 | Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
 | Connectors (`@ponchia/ui/connectors`, `css/connectors.css`, `.ui-connector*`, `initConnectors`) | Stable additive | Connector class names, the `data-bronto-connector` attribute contract, geometry helper function names, and recipe options are public. Helper internals/heuristics may tune before 1.0. Opt-in, not in the default bundle. |
@@ -41,15 +88,44 @@ shipped `files` entry, and the generated artifact provenance map — see
 | Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
 | Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the nine analytical leaves (figure, annotations, legend, marks, connectors, spotlight, crosshair, selection, highlights). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
 | Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`, `initSources`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), the optional `data-bronto-sources` / `data-bronto-source-ref` behavior contract, `bronto:source:focus`, and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
+| Interval ranges (`css/interval.css`, `.ui-interval*`) | Stable additive | Interval class names and the normalised `--lo`/`--hi`/`--v` custom-property contract are public. Opt-in, not in the default bundle. The host owns domains, units, and estimate math. |
+| Clamp blocks (`css/clamp.css`, `.ui-clamp*`) | Stable additive | Clamp class/part names, expanded/collapsed affordance slots, and print-expansion behavior are public. Opt-in, not in the default bundle. The host owns disclosure copy and state persistence. |
+| Text highlights (`css/highlights.css`, `.ui-highlights`) | Stable additive | Highlight container classes and token-backed Custom Highlight API paint are public. Opt-in, not in the default bundle. The host owns range registration and search/current-match logic. |
 | Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
 | Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
 | Workbench (`css/workbench.css`, `.ui-splitter*`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`, `initSplitter`) | Stable additive | Splitter, inspector, property-row and selection-bar class + BEM part names are public (no recipe). `data-bronto-splitter`, `--splitter-pos`, `bronto:splitter:resize`, and the `initSplitter` cleanup contract are public. Opt-in, not in the default bundle. The host owns pane content, persistence, collapse policy, and selection state. |
-| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand` / `command` / `vCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the framework binding adapters. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Spark microcharts (`css/spark.css`, `.ui-spark*`) | Stable additive | Spark class names and inline sizing/label slots are public. Opt-in, not in the default bundle. The host owns data reduction and accessible surrounding text. |
+| Bullet graphs (`css/bullet.css`, `.ui-bullet*`) | Stable additive | Bullet class names and measure/target/range custom-property slots are public. Opt-in, not in the default bundle. The host owns thresholds, units, and data mapping. |
+| Diffs (`css/diff.css`, `.ui-diff*`) | Stable additive | Diff container/line/gutter class names and add/remove/highlight state modifiers are public. Opt-in, not in the default bundle. Bronto styles evidence; it does not compute diffs. |
+| Code evidence (`css/code.css`, `.ui-code*`) | Stable additive | Code block/gutter/line-state class names and token-backed syntax-theme roles are public. Opt-in, not in the default bundle. Bronto styles code-as-evidence; it does not parse or highlight code at runtime. |
+| Sidenotes (`css/sidenote.css`, `.ui-sidenote`, `.ui-marginnote`) | Stable additive | Sidenote and marginnote class names, numbering behavior, and responsive in-flow fallback are public. Opt-in, not in the default bundle. |
+| Text references (`css/textref.css`, `.ui-textref`) | Stable additive | Text-reference class names and `::target-text` styling are public. Opt-in, not in the default bundle. The host owns URL text fragments and quote provenance. |
+| Terms / glossary (`css/term.css`, `.ui-term`, `.ui-glossary`) | Stable additive | Term and glossary class names plus native-popover definition hooks are public. Opt-in, not in the default bundle. The host owns glossary content and terminology policy. |
+| Contents rail (`css/toc.css`, `.ui-toc*`) | Stable additive | TOC rail class/part names and current-section state classes are public. Opt-in, not in the default bundle. The host owns section observation and active-state updates. |
+| Tree outlines (`css/tree.css`, `.ui-tree*`) | Stable additive | Tree outline class names, depth styling, and native `<details>` composition are public. Opt-in, not in the default bundle. The host owns tree data, lazy loading, and selection state. |
 | Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
-| Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
+| Agent and migration data (`llms.txt`, `MIGRATIONS.json`) | Stable additive | `llms.txt` stays shipped as the offline agent entrypoint. `MIGRATIONS.json` stays a machine-readable migration map for breaking renames/removals. New migration entries are additive; removal of a migration record requires the same breaking-change discipline as the surface it describes. |
+| Generated docs shipped in npm | Stable paths | Exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
 
+## Deprecation Policy
+
+Public surface (`.ui-*` classes, `data-bronto-*` attributes, `cls`/token keys,
+behavior signatures, and exported schema values) is removed on a
+**deprecate-one-minor** cycle:
+
+1. **Deprecate** in minor _N_: the surface keeps working unchanged, is marked
+   deprecated in `CHANGELOG.md`, and, for renames, gets an entry in
+   [`MIGRATIONS.json`](../MIGRATIONS.json).
+2. **Remove** no earlier than minor _N+1_, with a **BREAKING** changelog entry
+   and migration note.
+
+A token/class/attribute that is provably referenced by no shipped CSS,
+component, behavior, or doc may skip that window and be removed with a BREAKING
+entry plus migration note; there is no working call-site to keep alive.
+
 ## Trust Boundary
 
 Behaviors assume trusted application markup. If a delegated root includes

package/docs/theming.md

@@ -223,7 +223,7 @@ you have, so the one-accent discipline holds.
   colorways". (Your _own_ `--accent` re-brand is still your obligation; the
   guarantee covers the shipped palettes and skins.)
 
-## Data-viz palette (`@ponchia/ui/css/dataviz.css`)
+## Data-viz palette
 
 Opt-in Tier-4 chart colours for dashboards — **charts only, never UI chrome**
 (a build gate fails on `var(--chart-*)` in component CSS), and never in the
@@ -275,7 +275,7 @@ semantics — the CSS can't add ARIA for you:
   content use `.ui-popover` + `initPopover()` (collision-aware).
 
 > **Verify a rebrand:** open
-> [`demo/theme-playground.html`](../demo/theme-playground.html) — paste
+> [the theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html) — paste
 > your `--accent`, see the derived family and the computed WCAG ratios
 > for `--accent-text` / `--accent` against the surface, and copy the CSS
 > + DTCG override. This is the instrument for the "verify your hue"

package/docs/usage.md

@@ -191,6 +191,12 @@ destructive action).
 | toast    | transient, out-of-flow, system-initiated. Danger toasts route to an assertive live region; everything else polite. |
 | tooltip  | supplemental, hover/focus, never essential info (it's not announced reliably; don't hide required content in it). |
 
+For dismissible in-flow alerts, mark the host with `data-bronto-dismissible`,
+put `data-bronto-dismiss` on the close button, and wire `dismissible()` from
+`@ponchia/ui/behaviors`. With no attribute value, the button removes the nearest
+dismissible host; with a selector value, it removes the nearest matching
+ancestor and dispatches a cancelable `bronto:dismiss` event first.
+
 The CSS `ui-tooltip` is hover/focus-only and CSS can't wire it to assistive
 tech for you — associate the bubble with its trigger yourself, or it conveys
 nothing to a screen reader: give `.ui-tooltip__bubble` an `id`, point the
@@ -222,6 +228,8 @@ Both are a thin horizontal bar; they mean different things.
   zero bar — so the helper returns just `role="progressbar"` + `aria-busy="true"`
   (no `aria-valuenow`, no `--value`). Pair it with the class:
   `<div class={ui.progress({ indeterminate: true })} {...attrs.progress()}>`.
+  The segmented `.ui-dotbar` uses the same accessibility contract through
+  `attrs.dotbar(value)` or `attrs.dotbar()` for the indeterminate sweep.
 
 Rule of thumb: *something is happening* → progress; *something measures
 this much* → meter.
@@ -589,7 +597,9 @@ one of these a screen reader announces nothing while the user waits.
 carries the native `popover` attribute (never clipped by `overflow`/stacking);
 without it, it falls back to an `is-open` class that a clipping ancestor can cut
 off. Add `popover` to the panel for the robust path — the `is-open` form is a
-fallback, not the default to copy.
+fallback, not the default to copy. Placement flips to the roomier vertical side,
+keeps the panel on-screen, and scrolls tall content inside the available viewport
+space.
 
 It is a **non-modal** dialog by design: the panel gets `role="dialog"` and focus
 moves into it, but there is **no focus trap** and the rest of the page stays
@@ -610,7 +620,7 @@ HTML, print/PDF, and before any hydration:
 
 | Component | How it works without JS |
 | --- | --- |
-| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` (+ anchor positioning where supported) |
+| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` for short local labels |
 | Accordion | native `<details>` / `<summary>` |
 | Segmented control (`ui-segmented`) | `:has(input:checked)` over a radio group |
 | Scroll-reveal (`ui-scroll-reveal`) | scroll-driven animation, zero JS |
@@ -622,6 +632,7 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 
 | Component | Behavior | With the behavior absent |
 | --- | --- | --- |
+| Disclosure trigger (`[data-bronto-disclosure]`) | `initDisclosure` | a button with stale `aria-expanded`; the controlled panel never toggles |
 | Tabs (`ui-tabs`) | `initTabs` | **author panels visible** — ship `hidden` panels and if `initTabs` never runs the content is unreachable |
 | Combobox (`ui-combobox`) | `initCombobox` | a plain text input beside an unfiltered list |
 | Command palette (`ui-command`) | `initCommand` | a static, unfiltered list |
@@ -631,12 +642,15 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 | Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
 | Controlled modal (`ui-modal.is-open`) | `initModal` | open skin only — no inert trap, focus-return, or Escape close signal |
 | Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
+| Dismissible alert/callout (`data-bronto-dismissible`) | `dismissible` | the close affordance is just a button; nothing is removed |
 | Toast | `toast()` | nothing — it is imperative-only |
 
 One cross-cutting guard, not tied to a single component:
 
 | Concern | Behavior | With the behavior absent |
 | --- | --- | --- |
+| Theme persistence before first paint | `applyStoredTheme` | the token layer follows OS preference until client code sets `data-theme`, so a stored preference can flash |
+| Theme toggle controls | `initThemeToggle` | the button is inert and does not persist `data-theme` |
 | `aria-disabled="true"` controls | `initDisabledGuard` | dimmed + pointer-inert via CSS, but still **keyboard**-activatable on Enter/Space (native `disabled` is already fully inert) |
 
 Rule of thumb: if a component needs ARIA-state sync, focus management, a keyboard

package/docs/vega.md

@@ -137,7 +137,7 @@ one chromatic default (series 1 / the lone mark), never the chrome:
 | `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
 
 The palette is the same CVD-safe, pattern-paired set documented in
-[theming](./theming.md#data-viz) — colour is never the sole channel. When a
+[theming](./theming.md#data-viz-palette) — colour is never the sole channel. When a
 series needs the redundant second channel, drive the mark's fill from the
 `--chart-pattern-*` tokens or pair a [legend](./legends.md) swatch.
 
@@ -237,8 +237,8 @@ contract**, so pin your Vega version and key off the data, not generated ids.
 
 bronto owns the theme config — gated structurally by `check:vega` (every colour
 slot resolves, both themes, no `var()` leaks, every `range.*` ramp populated),
-and separately a dev-only render-probe (`npm test`, via the `vega`/`vega-lite`
-dev deps) asserts the colours actually land on a rendered chart — and the
-annotation geometry. It does not own Vega's grammar, its rendering, or its internal SVG —
+and by the unit suite (`check:unit`, via the `vega`/`vega-lite` dev deps) which
+asserts the colours actually land on a rendered chart — and the annotation
+geometry. It does not own Vega's grammar, its rendering, or its internal SVG —
 those stay Vega's, and the chart is a documented composition, not a shipped
 runtime binding.