@ponchia/ui 0.6.10 → 0.6.12

package/docs/mermaid.md

@@ -71,8 +71,10 @@ below):
 > an `http(s)` origin the `import`/`fetch` forms both work.
 
 The result is monochrome surfaces and lines with the rationed accent reserved
-for notes — a diagram that looks like the rest of a bronto surface and
-**re-skins for free** when you change `--accent`, exactly like the chart palette.
+for notes — a diagram that looks like the rest of a bronto surface. The accent is
+**resolved into the theme map** you pass to `initialize`, not read live from
+`--accent`: to change it you re-`initialize` with the new palette and re-render;
+an already-drawn diagram does not live-reskin (see below).
 
 ### Why resolved colours, not `var(--x)`
 
@@ -90,7 +92,7 @@ switch, re-`initialize` with the other palette and re-render.
 - **Chart-like** diagrams carry a categorical series palette — **pie**
   (`pie1`…`pie12`), **git** (`git0`…`git7`), and **user-journey**
   (`fillType0`…`fillType7`) are wired to the CVD-safe
-  [charts palette](./legends.md) (series 1 = the live accent).
+  [charts palette](./legends.md) (series 1 = the resolved accent).
 - **Structural** diagrams — flowchart, sequence, class, ER, state — use the
   monochrome node/edge/cluster grammar and spend the accent only on notes.
 - **Not themed: `gantt` and `timeline`.** Their colours come from

package/docs/package-contract.md

@@ -25,7 +25,7 @@ semantic versioning contract for the surfaces listed here.
 
 | Export | Target | Group | Stability | Contract |
 | --- | --- | --- | --- | --- |
-| `.` | style: `./dist/bronto.css`<br>default: `./dist/bronto.css` | CSS root bundle | Stable | CSS-only package root. Supported as a CSS side-effect import in CSS-aware bundlers; not a Node/runtime JS entrypoint. |
+| `.` | types: `./index.d.ts`<br>style: `./dist/bronto.css`<br>default: `./dist/bronto.css` | CSS root bundle | Stable | CSS-only package root. Supported as a CSS side-effect import in CSS-aware bundlers; not a Node/runtime JS entrypoint. |
 | `./dist/bronto.css` | `./dist/bronto.css` | Flattened CSS bundle | Stable path | The prebuilt default stylesheet. Generated from css/core.css and byte-checked by check:dist. |
 | `./tailwind` | `./tailwind.css` | Tailwind CSS bridge | Stable additive | CSS-only Tailwind v4 theme/variant bridge. It maps Bronto tokens into Tailwind namespaces; it does not import component CSS. |
 | `./tailwind.css` | `./tailwind.css` | Tailwind CSS bridge | Stable additive | CSS-only Tailwind v4 theme/variant bridge. It maps Bronto tokens into Tailwind namespaces; it does not import component CSS. |
@@ -180,6 +180,28 @@ semantic versioning contract for the surfaces listed here.
 | `./classes` | types: `./classes/index.d.ts`<br>default: `./classes/index.js` | Class recipes JS | Stable | ESM class registry, recipes, attrs helpers, and cx joiner. The emitted class vocabulary is public. |
 | `./classes.json` | `./classes/classes.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./behaviors` | types: `./behaviors/index.d.ts`<br>default: `./behaviors/index.js` | Vanilla behavior JS | Stable | ESM, SSR-safe, cleanup-returning behavior initializers. Behavior internals are not public. |
+| `./behaviors/carousel` | types: `./behaviors/carousel.d.ts`<br>default: `./behaviors/carousel.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/combobox` | types: `./behaviors/combobox.d.ts`<br>default: `./behaviors/combobox.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/command` | types: `./behaviors/command.d.ts`<br>default: `./behaviors/command.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/connectors` | types: `./behaviors/connectors.d.ts`<br>default: `./behaviors/connectors.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/crosshair` | types: `./behaviors/crosshair.d.ts`<br>default: `./behaviors/crosshair.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/dialog` | types: `./behaviors/dialog.d.ts`<br>default: `./behaviors/dialog.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/disclosure` | types: `./behaviors/disclosure.d.ts`<br>default: `./behaviors/disclosure.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/dismissible` | types: `./behaviors/dismissible.d.ts`<br>default: `./behaviors/dismissible.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/forms` | types: `./behaviors/forms.d.ts`<br>default: `./behaviors/forms.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/glyph` | types: `./behaviors/glyph.d.ts`<br>default: `./behaviors/glyph.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/inert` | types: `./behaviors/inert.d.ts`<br>default: `./behaviors/inert.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/legend` | types: `./behaviors/legend.d.ts`<br>default: `./behaviors/legend.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/menu` | types: `./behaviors/menu.d.ts`<br>default: `./behaviors/menu.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/modal` | types: `./behaviors/modal.d.ts`<br>default: `./behaviors/modal.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/popover` | types: `./behaviors/popover.d.ts`<br>default: `./behaviors/popover.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/sources` | types: `./behaviors/sources.d.ts`<br>default: `./behaviors/sources.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/splitter` | types: `./behaviors/splitter.d.ts`<br>default: `./behaviors/splitter.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/spotlight` | types: `./behaviors/spotlight.d.ts`<br>default: `./behaviors/spotlight.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/table` | types: `./behaviors/table.d.ts`<br>default: `./behaviors/table.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/tabs` | types: `./behaviors/tabs.d.ts`<br>default: `./behaviors/tabs.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/theme` | types: `./behaviors/theme.d.ts`<br>default: `./behaviors/theme.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
+| `./behaviors/toast` | types: `./behaviors/toast.d.ts`<br>default: `./behaviors/toast.js` | Package subpath | Public | Exported package subpath. See docs/stability.md for semantic stability. |
 | `./glyphs` | types: `./glyphs/glyphs.d.ts`<br>default: `./glyphs/glyphs.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./annotations` | types: `./annotations/index.d.ts`<br>default: `./annotations/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./connectors` | types: `./connectors/index.d.ts`<br>default: `./connectors/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
@@ -210,6 +232,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `css` | Source CSS directory | Public source leaves. Mostly hand-authored; generated exceptions are called out in the provenance table. |
 | `dist` | Generated CSS directory | Prebuilt layered bundle and leaves. Never hand-edit. |
 | `tailwind.css` | Tailwind CSS bridge | CSS-only Tailwind v4 theme/variant bridge; hand-authored and not part of the default Bronto bundle. |
+| `index.d.ts` | Package file | Included in the npm files allowlist. |
 | `fonts` | Vendored assets | Doto woff2 files plus OFL license. |
 | `tokens` | Mixed source/generated data | Token source plus generated JSON, declarations, and renderer theme data. |
 | `classes` | Mixed source/generated data | Class recipe source plus generated JSON/declarations/custom-data. |

package/docs/reference.md

@@ -1678,7 +1678,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--display` | `var(--dot-font)` |
 | `--display-weight` | `700` |
 | `--display-weight-strong` | `800` |
-| `--text-2xs` | `0.68rem` |
+| `--text-2xs` | `0.72rem` |
 | `--text-xs` | `0.76rem` |
 | `--text-sm` | `0.86rem` |
 | `--text-base` | `0.95rem` |

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.10/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/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.10/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -879,7 +879,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/selection.md

@@ -34,7 +34,16 @@ logic — Bronto only styles them. `--off` uses `opacity` (which survives
 forced-colors), and `--on` falls back to the system `Highlight` color in
 forced-colors so the selection stays visible.
 
+Pair the visual classes with host-owned selection semantics, such as
+`aria-selected`, native checked state, or a visible selected-count label.
+
 > **Why no brush behavior?** A rectangular brush or lasso must translate a
 > dragged region into a data domain (or test points against a polygon), which
 > requires owning the chart's scales/geometry — across Bronto's line. Bring your
 > own selection logic; use these classes to render the result.
+
+## Related
+
+`selection.css` is part of
+[`analytical.css`](./reporting.md#the-analytical-toolbox-in-a-report). Use
+[reference.md](./reference.md) for the generated class catalog.

package/docs/sources.md

@@ -167,3 +167,8 @@ ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"
   `CanvasText`, so the label remains the channel.
 - Tone dots and the card's tone border carry `print-color-adjust: exact`, so
   they survive printing; expand citation URLs in print where it helps the reader.
+
+## Related
+
+- [Usage](usage.md#static-reports) shows where citations fit in reports.
+- [Reference](reference.md) lists the generated source and citation classes.

package/docs/stability.md

@@ -1,4 +1,4 @@
-# Public API Stability
+# Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
 patches are non-breaking. In practical terms: **PATCH releases (`0.6.x`) are
@@ -11,7 +11,7 @@ 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
+## 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:
@@ -36,7 +36,7 @@ ready for 1.0 when the existing public contract is boring to upgrade:
   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
+### 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
@@ -51,6 +51,31 @@ enough.
 | 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. |
 
+### Adoption evidence for 1.0
+
+This snapshot records product evidence as of 2026-07-10. Use three evidence
+classes:
+
+- **Downstream-proven:** A non-example app, site, report generator, or tool
+  imports the published surface and passes its own build or checks.
+- **Package-proven:** Packed examples, unit tests, browser tests, and type tests
+  prove compatibility, but no inspected non-example consumer imports the
+  surface.
+- **Speculative:** Neither downstream use nor a package-level executable proof
+  justifies freezing the surface into 1.0.
+
+Package-proven is necessary but does not establish demand. During the catalog
+freeze, do not expand package-only surfaces. Recheck this table against real
+consumer upgrades before the 1.0 release candidate.
+
+| Surface family | Current evidence | 1.0 disposition |
+| --- | --- | --- |
+| Core CSS, class recipes, vanilla behaviors, tokens, and Tailwind bridge | Downstream-proven across five inspected non-example app, site, and service consumers. | Stabilize names and behavior contracts. Use consumer upgrades as the release-candidate proof. |
+| Report, provenance, analytical CSS, annotations, glyphs, skins, workbench CSS, chart data, and Vega theme | Downstream-proven across four inspected report, site, dashboard, and tool consumers. | Keep opt-in. Stabilize the consumed paths; do not broaden the catalog during the freeze. |
+| Controlled non-`<dialog>` modal | Package-proven by stack, portal, late-node, focus, and cleanup regressions. No inspected non-example consumer initializes `initModal`. | Keep compatible through 0.6.x, but require a real consumer before declaring this alternative to native `<dialog>` stable in 1.0. |
+| React, Solid, Qwik, Svelte, and Vue lifecycle adapters | Package-proven by packed examples, types, and lifecycle tests. No inspected non-example consumer imports an adapter entrypoint. | Pre-1.0 candidate only. Freeze the adapter set and require downstream adoption before declaring all five stable in 1.0. |
+| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.6.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
+
 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.
 
@@ -104,13 +129,13 @@ current public-surface matrix and the release policy above still applies.
 | 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. |
+| 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, stack-aware `inert` ownership, focus-return, late-background trapping, owned portaled-popover admission, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; closing a parent suspends still-open controlled descendants until the parent reopens. The native `<dialog>` path (`initDialog`) remains the default. |
 | 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). |
 | 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
+## Deprecation policy
 
 Public surface (`.ui-*` classes, `data-bronto-*` attributes, `cls`/token keys,
 behavior signatures, and exported schema values) is removed on a
@@ -126,7 +151,7 @@ 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
+## Trust boundary
 
 Behaviors assume trusted application markup. If a delegated root includes
 untrusted CMS or user HTML, sanitize it first or do not initialize behaviors on

package/docs/state.md

@@ -140,3 +140,9 @@ CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago"), live
 progress text, polling, cancellation, retry, and conflict-resolution affordances
 are the host's job. A small optional behavior may come later if a real consumer
 needs it.
+
+## Related
+
+Use the [reporting toolbox](./reporting.md#the-analytical-toolbox-in-a-report)
+to place `state.css` in report surfaces, and use
+[reference.md](./reference.md) for the generated class catalog.

package/docs/textref.md

@@ -3,10 +3,11 @@
 `@ponchia/ui/css/textref.css` is an opt-in **deep-link-to-the-cited-sentence**
 provenance primitive. A citation whose `href` is a URL [Text
 Fragment](https://developer.mozilla.org/en-US/docs/Web/Text_fragments)
-(`#…:~:text=`): the browser scrolls to the exact quoted text and highlights it,
-and Bronto owns the on-brand `::target-text` paint. It is the inline counterpart
-to the static `ui-src` / `ui-citation` trust layer (`sources.css`), which can
-label a source but cannot point *inside* it.
+(`#section:~:text=`): supporting browsers scroll to the exact quoted text and
+highlight it, while the leading `#section` gives older engines a stable landing.
+Bronto owns the on-brand `::target-text` paint. It is the inline counterpart to
+the static `ui-src` / `ui-citation` trust layer (`sources.css`), which can label
+a source but cannot point *inside* it.
 
 ```css
 @import '@ponchia/ui';
@@ -15,12 +16,13 @@ label a source but cannot point *inside* it.
 
 ## How it behaves
 
-- The link navigates to the document and the browser scrolls to + highlights the
-  first match of the quoted text — no script, no anchors to pre-place.
+- In Chrome/Edge 80+, Safari 16.1+, and Firefox 131+, the browser scrolls to
+  and highlights the first match of the quoted text — no script.
 - Bronto repaints that browser highlight (`::target-text`) in the rationed
   accent wash so it matches the rest of the trust layer.
-- On engines without Text Fragments the link still navigates to the page (or its
-  `#section` anchor); the highlight is purely additive, so nothing breaks.
+- On engines without Text Fragments, the `:~:text=` directive is ignored. Use a
+  real `#section:~:text=...` URL when you own the target page; a bare `#section`
+  can land only at the section, not at the quoted sentence.
 
 ## Wiring — the host builds the fragment URL
 
@@ -30,11 +32,12 @@ runtime for it. Build the `href` with a three-line pure helper and drop it on th
 
 ```js
 // Encode a quote as a URL Text Fragment directive.
-// encodeTextFragment('p95 latency fell 38%') -> '#:~:text=p95%20latency%20fell%2038%25'
-export function encodeTextFragment(quote, { prefix } = {}) {
+// encodeTextFragment('p95 latency fell 38%', { section: 'incident-summary' })
+// -> '#incident-summary:~:text=p95%20latency%20fell%2038%25'
+export function encodeTextFragment(quote, { prefix, section } = {}) {
   const enc = (s) => encodeURIComponent(s).replace(/-/g, '%2D');
   const text = prefix ? `${enc(prefix)}-,${enc(quote)}` : enc(quote);
-  return `#:~:text=${text}`;
+  return `${section ? `#${encodeURIComponent(section)}` : '#'}:~:text=${text}`;
 }
 ```
 
@@ -43,7 +46,7 @@ export function encodeTextFragment(quote, { prefix } = {}) {
   The migration cut p95 latency by 38%
   <a
     class="ui-textref"
-    href="https://example.com/incident-review#:~:text=p95%20latency%20fell%2038%25"
+    href="https://example.com/incident-review#incident-summary:~:text=p95%20latency%20fell%2038%25"
     >jump to the source</a
   >.
 </p>
@@ -56,12 +59,14 @@ Notes for an autonomous author:
 - Keep the quote short and verbatim; a fuzzy or paraphrased quote won't match.
 - Use the optional `prefix` (a `prefix-,` directive) to disambiguate a quote that
   appears more than once on the target page.
+- Firefox support starts at 131. The project floor includes Firefox 129, so make
+  the leading section fallback meaningful when exact quote landing matters.
 
 ## Class reference
 
 | Class         | Role                                                                |
 | ------------- | ------------------------------------------------------------------- |
-| `.ui-textref` | A citation link whose `href` is a `#:~:text=` fragment; dotted underline + quote-jump cue. |
+| `.ui-textref` | A citation link whose `href` is a `#section:~:text=` fragment; dotted underline + quote-jump cue. |
 
 | Custom property        | On            | Meaning                                                                   |
 | ---------------------- | ------------- | ------------------------------------------------------------------------- |

package/docs/theming.md

@@ -26,8 +26,15 @@ So a full re-brand is one declaration **at `:root` (or a theme root)**:
 :root[data-theme='dark'] { --accent: #6ea8ff; } /* per-theme tuning */
 ```
 
-Everything — buttons, focus rings, dot motifs, accent borders, soft
-fills — follows automatically, in both light and dark.
+Core DOM accent surfaces — buttons, focus rings, dot motifs, accent borders,
+soft fills — follow automatically, in both light and dark.
+
+That scope matters. `--accent` is the core action/emphasis hue, not the whole
+color system. Status colors (`--success`, `--warning`, `--danger`, `--info`),
+neutral surface tiers, display-expression tokens, and the opt-in data-viz
+palette stay separate governed tiers. Mermaid, D2, and Vega bridges emit
+resolved renderer theme data; a rendered SVG or canvas does not live-reskin when
+you change CSS `--accent` later.
 
 > **Re-branding a subtree (not `:root`) is only a *partial* re-brand.**
 > The derived family (`--accent-soft`, `--accent-strong`, `--accent-text`,
@@ -53,6 +60,8 @@ fills — follows automatically, in both light and dark.
 > When in doubt, re-brand at `:root`/`[data-theme]` — that path re-derives
 > the whole family for you.
 
+### Re-brand obligations
+
 > **Two contrast obligations when you change `--accent`:**
 >
 > 1. **Buttons** — pick an `--accent` with ≥ 4.5:1 against `--button-text`
@@ -106,7 +115,7 @@ fills — follows automatically, in both light and dark.
   set `accent-color` yourself on them — this is the one accent surface
   the framework can't tune for you.
 
-## Beyond accent: a full re-skin (the knob really works)
+## Beyond accent: full re-skins
 
 The "Nothing" look is the **default skin, not the architecture**. It is
 a handful of token declarations deep — no selector hardcodes the
@@ -142,11 +151,12 @@ no fork:
 ```
 
 That changes buttons, cards, inputs, badges, focus rings, the display
-type and the dot motif together, because every component consumes those
-tokens — not because there is a per-component theme file. This is the
-difference between a *system* and a *skin*: the skin is swappable, the
-system (rationed colour, density, classless prose, minimal JS) is what
-you are actually adopting.
+type and the dot motif together, because those surfaces consume the token
+contract — not because there is a per-component theme file. It does not
+rewrite status semantics or chart palettes; those are governed by their own
+tiers. This is the difference between a *system* and a *skin*: the skin is
+swappable, the system (rationed colour, density, classless prose, minimal JS)
+is what you are actually adopting.
 
 Caveat, restated: a custom `--accent` is **your** contrast obligation —
 the shipped palettes are CI-gated ([contrast.md](contrast.md)), a re-skin

package/docs/toc.md

@@ -81,3 +81,9 @@ for (const id of links.keys()) {
   navigation landmark.
 - Without the optional observer the rail is a normal anchored list — every link
   still jumps to its section.
+
+## Related
+
+Use the [reporting toolbox](./reporting.md#the-analytical-toolbox-in-a-report)
+to place `toc.css` in report surfaces, and use
+[reference.md](./reference.md) for the generated class catalog.

package/docs/tree.md

@@ -38,8 +38,9 @@ open/close animation come from the platform. This leaf is the hierarchy *layer*
 ```
 
 Add `name="…"` to sibling `<details class="ui-tree__branch">` to make them an
-exclusive-accordion group (only one open at a time) — a platform behaviour, no
-script.
+exclusive-accordion group (only one open at a time) — a platform behaviour in
+Chrome 120+, Safari 17.2+, and Firefox 130+. If Firefox 129 must enforce
+exclusivity, add a host-owned JS fallback or leave the branches independent.
 
 ## A11y honesty — disclosure group, not an ARIA tree
 
@@ -72,3 +73,9 @@ honest as-is.
   open-branch accent cue is re-asserted with the system highlight.
 - The chevron spin and the auto-height animation both respect
   `prefers-reduced-motion`.
+
+## Related
+
+Use the [reporting toolbox](./reporting.md#the-analytical-toolbox-in-a-report)
+to place `tree.css` in report surfaces, and use
+[reference.md](./reference.md) for the generated class catalog.

package/docs/usage.md

@@ -377,6 +377,16 @@ also gives the overlay `role="dialog"` + `aria-modal="true"` and dev-warns if it
 has no accessible name (add `aria-label`/`aria-labelledby`). A drawer is a modal
 that enters from an edge — same rule.
 
+Controlled modals share one document-level stack. Opening a sibling portal
+modal makes the previous modal inert and keeps only the new top modal
+interactive; closing it restores focus into the previous modal. An
+`initPopover()` trigger inside the top modal may target a panel portaled
+elsewhere in the document: while that panel is open, it joins the live modal
+tree and owns Escape without releasing unrelated background content. Background
+nodes added after the modal opens are trapped too. If a controlled parent modal
+closes while a descendant still carries `is-open`, the descendant is suspended
+with the parent and resumes if the parent reopens.
+
 **Scroll-lock is not automatic on either path.** Neither the native `<dialog>`
 nor the `is-open` path freezes the background — the page behind an open modal can
 still scroll. If that matters, toggle a lock yourself while the modal is open
@@ -404,7 +414,7 @@ infinite-clone track). It's a gallery: the user drives it.
 
 ## Display glyphs: when (and when not)
 
-`@ponchia/ui/glyphs` is a 48-glyph dot-matrix icon set — navigation
+`@ponchia/ui/glyphs` is a 71-glyph dot-matrix icon set — navigation
 (`arrow-*`, `chevron-*`), actions (`check`, `close`, `plus`, `minus`,
 `search`, `menu`, `gear`), status (`info`, `warning`, `bell`, `lock`) and
 common marks (`home`, `user`, `heart`, `star`, `spark`, circle-family marks) — rendered on the
@@ -624,7 +634,6 @@ HTML, print/PDF, and before any hydration:
 | 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 |
-| Modal via native `<dialog>` | the element brings focus-trap + Escape; `initDialog` only adds open-triggers + focus-return |
 
 **Behavior-required — a CSS skin that needs its `init*` to be interactive.**
 These are JS widgets wearing the Bronto look; without the behavior they are inert
@@ -640,6 +649,7 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 | Table sort/select (`[data-bronto-sortable]`) | `initTableSort` | a static table (still readable) |
 | Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
 | Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
+| Native dialog/lightbox (`<dialog>`, `ui-lightbox`) | `initDialog` | closed markup stays closed; `data-bronto-open`/close buttons do nothing. Do not use `open` as a modal fallback: it is non-modal and has no trigger/focus-return path |
 | 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 |

package/docs/vega.md

@@ -143,8 +143,10 @@ series needs the redundant second channel, drive the mark's fill from the
 
 ### Spending the accent
 
-Series 1 of `range.category` **is** the live accent, so a single-series chart and
-the first category re-skin for free with `--accent`. To emphasise one mark in a
+Series 1 of `range.category` resolves to the accent (per theme), so a single-series
+chart and the first category carry the accent automatically — baked into the
+generated `config`, so regenerate the config and re-render to change it (Vega output
+does not live-reskin from `--accent`). To emphasise one mark in a
 multi-series chart, paint just that mark with the accent and leave the rest
 neutral — the same "reserve the accent for the one thing a reader must not miss"
 rule the rest of the system follows. Two small helpers hand you the exact
@@ -169,7 +171,7 @@ const spec = {
 };
 ```
 
-`brontoVegaAccent(theme)` is `range.category[0]` (the live accent) and
+`brontoVegaAccent(theme)` is `range.category[0]` (the resolved accent) and
 `brontoVegaNeutral(theme)` is the last category (the quiet neutral); re-read both
 when the theme toggles. Prefer them over digging the hex out of
 `tokens/resolved.json` — they are guaranteed to match the palette the config

package/glyphs/glyphs.js

@@ -1396,14 +1396,18 @@ export function findGlyphs(query) {
 
 const TONE = { '#': 'hot', '*': 'accent' };
 
+function glyphRows(name) {
+  return Object.hasOwn(GLYPHS, name) ? GLYPHS[name] : undefined;
+}
+
 /** The raw bitmap rows for a glyph, or `undefined` if the name is unknown. */
 export function glyph(name) {
-  return GLYPHS[name];
+  return glyphRows(name);
 }
 
 /** GLYPH_SIZE² cell descriptors (row-major), or `[]` if the name is unknown. */
 export function glyphCells(name) {
-  const rows = GLYPHS[name];
+  const rows = glyphRows(name);
   if (!rows) return [];
   const cells = [];
   for (const row of rows) {
@@ -1425,7 +1429,7 @@ export function glyphCells(name) {
  * @returns {string}
  */
 export function glyphMask(name) {
-  const rows = GLYPHS[name];
+  const rows = glyphRows(name);
   return rows ? maskUrl(rows) : '';
 }
 
@@ -1446,13 +1450,63 @@ function esc(s) {
     .replace(/"/g, '"');
 }
 
+const CSS_LENGTH_UNITS =
+  '(?:px|r?em|ch|ex|cap|ic|lh|rlh|vw|vh|vi|vb|vmin|vmax|' +
+  'svw|svh|svi|svb|svmin|svmax|lvw|lvh|lvi|lvb|lvmin|lvmax|' +
+  'dvw|dvh|dvi|dvb|dvmin|dvmax|cm|mm|q|in|pc|pt|%)';
+const CSS_NUMBER = '[-+]?(?:\\d*\\.\\d+|\\d+)';
+const CSS_LENGTH_RE = new RegExp(`^(?:0|${CSS_NUMBER}${CSS_LENGTH_UNITS})$`, 'i');
+const CSS_CALC_VALUE_RE = new RegExp(`^${CSS_NUMBER}(?:${CSS_LENGTH_UNITS})?`, 'i');
+
+function isCalcLength(expr) {
+  let rest = expr.trim();
+  let depth = 0;
+  let sawLength = false;
+  let expectValue = true;
+
+  while (rest) {
+    if (expectValue) {
+      if (rest[0] === '(') {
+        depth += 1;
+        rest = rest.slice(1).trim();
+        continue;
+      }
+      const token = rest.match(CSS_CALC_VALUE_RE)?.[0];
+      if (!token) return false;
+      if (CSS_LENGTH_RE.test(token)) sawLength = true;
+      rest = rest.slice(token.length).trim();
+      expectValue = false;
+      continue;
+    }
+
+    if (rest[0] === ')') {
+      depth -= 1;
+      if (depth < 0) return false;
+      rest = rest.slice(1).trim();
+      continue;
+    }
+
+    const op = rest.match(/^[+\-*/]/)?.[0];
+    if (!op) return false;
+    rest = rest.slice(op.length).trim();
+    expectValue = true;
+  }
+
+  if (!sawLength) return false;
+  if (expectValue) return false;
+  return depth === 0;
+}
+
 // `dot`, `gap`, and `size` land in an inline-CSS context (`style="…"`), where
 // HTML-escaping a `"` stops attribute breakout but a `;` would still open a
-// second CSS declaration (overlay/clickjacking, selector exfil). So restrict
-// them to length/calc syntax — digits, units, %, whitespace and `()+-*/.,` for
-// calc()/clamp()/var() — and drop anything else rather than emit it.
+// second CSS declaration. Accept only concrete CSS lengths or calc() expressions.
 function cssLen(v) {
-  return /^[\w.%+\-*/()\s,]+$/.test(v) ? v : '';
+  const value = String(v ?? '').trim();
+  if (CSS_LENGTH_RE.test(value)) return value;
+  if (value.toLowerCase().startsWith('calc(') && value.endsWith(')')) {
+    return isCalcLength(value.slice(5, -1)) ? value : '';
+  }
+  return '';
 }
 
 /**
@@ -1514,7 +1568,7 @@ function maskUrl(rows) {
  * Needs `@ponchia/ui/css` (the `.ui-icon` rule).
  */
 export function renderGlyph(name, options = {}) {
-  const rows = GLYPHS[name];
+  const rows = glyphRows(name);
   if (!rows) return '';
   const { grid = true, solid = false, anim, label, dot, gap, render, size } = options;
 

package/index.d.ts

@@ -0,0 +1 @@
+export {};