@ponchia/ui 0.6.8 → 0.6.9

package/css/primitives.css

@@ -74,7 +74,7 @@
 /* Intrinsic aspect-ratio box; the media child fills it. The contract is ONE
    child (a single <img>/<video>/<iframe>). Scope the fill to :first-child rather
    than every child: a second child would otherwise be forced to 100%/100% +
-   object-fit and stack on top, silently breaking the ratio. (audit C34.) */
+   object-fit and stack on top, silently breaking the ratio. */
 .ui-ratio {
   aspect-ratio: var(--ratio, 16 / 9);
 }
@@ -100,7 +100,7 @@
 /* Logical `max-inline-size`, not physical `max-width`: the container is typed
    `inline-size`, so the inline axis is the one actually tracked — the logical
    query matches it in any writing mode (a physical `width` query silently
-   misses in a vertical WM). (component audit C34.) */
+   misses in a vertical writing mode). */
 @container bronto (max-inline-size: 34rem) {
   .ui-grid {
     --grid-min: 100%;
@@ -193,7 +193,7 @@
   /* These tiles hold IDs / hashes / big numbers — the unbreakable-token case is
      the common one. A grid item defaults to min-inline-size:auto, so a long
      value pushes the whole statgrid track wider; allow the tile to shrink so the
-     value can wrap instead (paired with overflow-wrap on __value). (audit C5.) */
+     value can wrap instead (paired with overflow-wrap on __value). */
   min-inline-size: 0;
   padding: var(--space-md);
 }
@@ -216,7 +216,7 @@
   font-weight: var(--display-weight-strong);
   letter-spacing: 0.02em;
   line-height: 1.05;
-  overflow-wrap: anywhere; /* break an unspaced ID/hash rather than overflow (audit C5) */
+  overflow-wrap: anywhere; /* break an unspaced ID/hash rather than overflow */
 }
 
 .ui-stat__delta,
@@ -237,7 +237,7 @@
 
 /* A direction arrow is the non-colour channel — colour alone (success/danger)
    fails WCAG 1.4.1, so the tile carries the same ▲/▼ glyph as `.ui-delta`
-   (C13). Marked aria-hidden-equivalent by being generated content; the sign is
+   as a second signal. Marked aria-hidden-equivalent by being generated content; the sign is
    still in the author's text ("+12%"). */
 .ui-stat__delta.is-pos::before,
 .ui-app-metric__delta.is-pos::before {
@@ -259,7 +259,7 @@
 .ui-num {
   /* inline-block so `text-align: end` actually applies: on a bare inline element
      it computes but never paints (the box is shrink-wrapped), so an author who
-     followed the docs to right-align an inline figure saw no effect. (audit C17.) */
+     followed the docs to right-align an inline figure saw no effect. */
   display: inline-block;
   font-variant-numeric: tabular-nums;
   text-align: end;
@@ -436,8 +436,8 @@
    this looks-dead state is NOT keyboard-inert: for that, prefer native
    `<button disabled>`, run `initDisabledGuard()` (it intercepts Enter/Space on
    aria-disabled controls), or add `tabindex="-1"` (and drop `href` on a link).
-   See docs/usage.md "Disabled vs aria-disabled". (a11y review C3 / audit C4;
-   native :disabled already inert.) */
+   See docs/usage.md "Disabled vs aria-disabled"; native :disabled is already
+   inert. */
 .ui-button[aria-disabled='true'],
 .ui-link[aria-disabled='true'] {
   pointer-events: none;
@@ -445,7 +445,7 @@
 
 /* The button family dims + shows not-allowed via its `:disabled` rule above, but
    a disabled LINK got only pointer-events:none — it looked fully live. Give it
-   the same visual disabled cue. (component audit C30.) */
+   the same visual disabled cue. */
 .ui-link[aria-disabled='true'] {
   cursor: not-allowed;
   opacity: 0.45;
@@ -480,7 +480,7 @@
      !important `animation-duration`, so the old non-important `1.4s` slow-spin
      here was dead code AND left a broken, transparent-topped ring looking like a
      rendering bug. Drop the dead rule; show a STATIC complete ring instead — a
-     still busy cue with no implied motion. (component audit C15.) */
+     still busy cue with no implied motion. */
   .ui-button[aria-busy='true']::before {
     border-block-start-color: currentcolor;
   }
@@ -530,8 +530,7 @@
 
 /* RTL: the logical borders flip sides, but a fixed `rotate(45deg)` then points
    the chevron UP rather than toward the inline-end (the reading-forward way).
-   Mirror the rotation so the resting affordance points forward in RTL too.
-   (component audit C14.) */
+   Mirror the rotation so the resting affordance points forward in RTL too. */
 [dir='rtl'] .ui-link--arrow::after,
 [dir='rtl'] .ui-link--cta::after {
   transform: rotate(-45deg);
@@ -540,8 +539,7 @@
 /* Standalone CTA links are tap targets, not inline prose links: on a coarse
    pointer float them to the WCAG 2.5.8 AA 24px floor (the 2.5.8 inline-link
    exception doesn't cover a block-level call-to-action, which is what these
-   are). Buttons already auto-grow to ~44px on coarse pointers. (component
-   audit C14.) */
+   are). Buttons already auto-grow to ~44px on coarse pointers. */
 @media (pointer: coarse) {
   .ui-link--arrow,
   .ui-link--cta {
@@ -600,7 +598,7 @@
 
   /* Accent mixes 45% (vs 40% for the status tones below) on purpose: the brand
      hue is lower-chroma here than the status hues, so it needs a touch more to
-     read at the same border weight. Intentional, not a copy-paste slip. (Q15.) */
+     read at the same border weight. Intentional, not a copy-paste slip. */
   border-color: color-mix(in srgb, var(--accent) 45%, var(--line));
 }
 
@@ -694,7 +692,7 @@
   font-family: var(--mono);
   margin: 0;
   min-inline-size: 0;
-  overflow-wrap: anywhere; /* IDs/hashes/paths are the common value — break, don't overflow (audit C5) */
+  overflow-wrap: anywhere; /* IDs/hashes/paths are the common value — break, don't overflow */
 }
 
 /* --- Hover (pointer only) --- */

package/css/sidenote.css

@@ -41,7 +41,7 @@
 /* The inline superscript that anchors a numbered sidenote. Use --accent-text,
    not raw --accent: this is readable text and must clear WCAG AA 4.5:1 even
    after a one-knob re-brand to a paler --accent (raw --accent drops to ~1.5:1).
-   Same accent-as-text contract as .ui-eyebrow / .ui-link--cta. (audit C6.) */
+   Same accent-as-text contract as .ui-eyebrow / .ui-link--cta. */
 .ui-sidenote__ref {
   color: var(--accent-text);
   counter-increment: ui-sidenote;
@@ -54,7 +54,7 @@
 }
 
 /* The note repeats its number (display only — the ref already incremented).
-   --accent-text for the same WCAG-AA reason as the ref above. (audit C6.) */
+   --accent-text for the same WCAG-AA reason as the ref above. */
 .ui-sidenote::before {
   color: var(--accent-text);
   content: counter(ui-sidenote) '. ';

package/css/table.css

@@ -39,7 +39,7 @@
 
   /* Keep the sticky header above body cells — cheap insurance for the
      sticky-header + pinned/positioned-column combo, where an un-z-indexed th
-     scrolls under a positioned cell. (audit C30.) */
+     scrolls under a positioned cell. */
   z-index: 1;
 }
 
@@ -171,7 +171,7 @@
 
 /* --- Loading state: set aria-busy + .ui-table-wrap--loading on the wrap. The
    modifier is named for the element it goes ON (the wrap), not `.ui-table`, so
-   the BEM host matches the documented placement. (component audit C19.) --- */
+   the BEM host matches the documented placement. --- */
 .ui-table-wrap--loading {
   opacity: 0.6;
   pointer-events: none;

package/docs/annotations.md

@@ -13,6 +13,15 @@ points away from it, and a **note** carries the visible explanation.
 Use it with any SVG renderer. Bronto supplies classes and tiny geometry helpers;
 it does not own chart scales, mutate the DOM, or provide draggable edit mode.
 
+For new annotation-engine work, use the sibling `@ponchia/annotations` package:
+it owns placement, collision handling, SVG/React renderers, editable layers, and
+Mermaid/D2/Vega/React Flow adapters. This `@ponchia/ui/annotations` subpath
+stays a dependency-free compatibility surface for static Bronto SVG helpers, so
+installing the UI package never pulls in the annotation engine and public
+declarations never type-reference it. Combine the two by using Bronto's
+`css/annotations.css` for the visual grammar, or the annotation package's Bronto
+CSS bridge when the engine emits its own layer.
+
 ```js
 import {
   annotationParts,

package/docs/architecture.md

@@ -76,6 +76,13 @@ on top of the CSS, none of which require a framework commitment**:
   `index.js` is a barrel; each behavior lives in its own module
   (`dialog.js`, `combobox.js`, …) over a shared `internal.js` of DOM helpers,
   so the public import surface is unchanged.
+- **connectors/** and **annotations/** — dependency-free SVG geometry helpers
+  for report and analytical figures. `@ponchia/ui/annotations` intentionally
+  stays a small static-helper compatibility layer for the Bronto subject /
+  connector / note grammar. The richer annotation engine - placement,
+  collision handling, SVG/React renderers, editing, and diagram/chart adapters
+  - lives in the sibling `@ponchia/annotations` package and must not be pulled
+  in as a runtime or public type dependency of `@ponchia/ui`.
 - **glyphs/** — static bitmap data and SSR-safe render helpers. The
   256-cell DOM renderers are for display and solid inline icons; the `.ui-icon`
   mask renderer is for dense icon-at-scale use.
@@ -102,6 +109,26 @@ on top of the CSS, none of which require a framework commitment**:
   `/svelte`, `/vue`, `/skins`, `/charts`, `/mermaid`, `/d2`, `/vega`). This is
   a permanent, intentional contract.
 
+### Surface admission rule
+
+The default bundle is the shared app/service identity, not the complete Bronto
+catalog. A new public surface must choose one lane before it ships:
+
+- **core identity** — universal application chrome or accessibility/platform
+  glue that belongs in `dist/bronto.css`;
+- **opt-in toolbox** — report, analytical, provenance, generated-content,
+  renderer, workbench, or command vocabulary that ships as an explicit CSS/JS
+  subpath;
+- **recipe/docs only** — a pattern that can be taught without creating a new
+  class, token, behavior, export, or package path.
+
+When the answer is unclear, choose recipe/docs first. Promote to an opt-in leaf
+only after a real consumer repeats the pattern; promote to core only when it is
+clearly shared application identity. Bronto owns visual grammar, token handoff,
+pure geometry, and delegated accessibility behavior. It does not own chart
+scales, data fetching, persistence, routing, workflow execution, action
+registries, virtualized grids, or framework component APIs.
+
 ## Repository layout
 
 The repo root mixes five kinds of directory that look alike but follow very
@@ -162,6 +189,7 @@ are copied into consumer reports.
 | published tarball == intended `files` only      | `check-pack.mjs`    |
 | packed core JS/JSON public subpaths import without optional framework peers, packed JS named exports exactly match source modules, peer-backed adapters import after peers are linked, concrete CSS/doc/font subpaths resolve, and packed behavior initializers/toast no-op in a clean consumer with no DOM globals | `check-consumer-surface.mjs` |
 | packed typed public subpaths compile through package exports in a clean TypeScript consumer | `check-consumer-types.mjs` |
+| function-level cyclomatic complexity stays ≤12 and function NLOC stays within budget, with no per-function exception list | `check-complexity.mjs` |
 | GitHub Actions workflow syntax and embedded shell snippets lint | `check:workflows` (`github-actionlint`) |
 | every shipped CSS leaf is classified as foundation or has explicit docs/demo/e2e ownership | `check-component-matrix.mjs` |
 | every public behavior export has explicit docs, unit-test, and browser-test ownership | `check-behavior-matrix.mjs` |

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/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. |

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.8/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/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.8/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/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
@@ -879,7 +879,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/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`, `attrs`, recipe names, ARIA attribute helper 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 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,13 +88,26 @@ 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` / `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

package/glyphs/glyphs.js

@@ -1518,17 +1518,34 @@ export function renderGlyph(name, options = {}) {
   if (!rows) return '';
   const { grid = true, solid = false, anim, label, dot, gap, render, size } = options;
 
+  if (render === 'mask') return renderMaskGlyph(rows, { label, size });
+
+  const cells = glyphCells(name);
+  const style = dotmatrixStyle({ solid, dot, gap });
+  const cls = dotmatrixClass(anim);
+  const stagger = anim === 'reveal';
+  const showPanel = grid && !solid;
+  const inner = cells
+    .map((cell, index) => renderGlyphCell(cell, index, { showPanel, stagger }))
+    .join('');
+
+  // A `<span>` (not `<div>`): it's phrasing content, so the glyph is valid
+  // inline and inside a `<button>` (its content model is phrasing-only) — the
+  // inline-icon use. `.ui-dotmatrix`'s `display: grid` works on a span.
+  return `<span class="${cls}" style="${style.join(';')}" ${a11yAttrs(label)}>${inner}</span>`;
+}
+
+function renderMaskGlyph(rows, { label, size }) {
   // One-node icon: a single `.ui-icon` span masked by the glyph's bitmap, so
   // it scales to any font-size and inherits `currentColor` — for icon-at-scale
   // (e.g. one in every table row) where the GLYPH_SIZE²-cell path is too heavy.
-  if (render === 'mask') {
-    const a11yM = label ? `role="img" aria-label="${esc(label)}"` : 'aria-hidden="true"';
-    const sz = size && cssLen(size) ? `--icon-size:${cssLen(size)};` : '';
-    return `<span class="ui-icon" style="${sz}--icon-mask:${maskUrl(rows)}" ${a11yM}></span>`;
-  }
-
-  const cells = glyphCells(name);
+  const iconSize = size && cssLen(size) ? `--icon-size:${cssLen(size)};` : '';
+  return `<span class="ui-icon" style="${iconSize}--icon-mask:${maskUrl(rows)}" ${a11yAttrs(
+    label,
+  )}></span>`;
+}
 
+function dotmatrixStyle({ solid, dot, gap }) {
   const style = [`--dotmatrix-cols:${GLYPH_SIZE}`];
   const dotLen = dot && cssLen(dot);
   const gapLen = gap && cssLen(gap);
@@ -1537,42 +1554,35 @@ export function renderGlyph(name, options = {}) {
   // `minmax(0, 1fr)` and the 16×16 matrix balloons to fill its container
   // (full-bleed, ~1250px) — the string API would then render an icon-intent call
   // very differently from the DOM `initDotGlyph` path, which already defaults to
-  // 0.08em. Mirror that default here so both paths render the same icon. (C7.)
+  // 0.08em. Mirror that default here so both paths render the same icon.
   style.push(`--dotmatrix-dot:${dotLen || '0.08em'}`);
   // Solid mode fuses the dots into a crisp pixel glyph: square cells, no gap.
   if (solid) style.push('--dotmatrix-dot-radius:0', '--dotmatrix-gap:0');
   else if (gapLen) style.push(`--dotmatrix-gap:${gapLen}`);
+  return style;
+}
 
-  const cls =
-    anim === 'reveal'
-      ? 'ui-dotmatrix ui-dotmatrix--reveal'
-      : anim === 'pulse'
-        ? 'ui-dotmatrix ui-dotmatrix--pulse'
-        : 'ui-dotmatrix';
-  // `reveal` staggers each cell by its row-major index via `--i`.
-  const stagger = anim === 'reveal';
-
-  const a11y = label ? `role="img" aria-label="${esc(label)}"` : 'aria-hidden="true"';
+function dotmatrixClass(anim) {
+  if (anim === 'reveal') return 'ui-dotmatrix ui-dotmatrix--reveal';
+  if (anim === 'pulse') return 'ui-dotmatrix ui-dotmatrix--pulse';
+  return 'ui-dotmatrix';
+}
 
+function renderGlyphCell(cell, index, { showPanel, stagger }) {
+  const cl = cell.on ? cellClass(cell) : 'ui-dotmatrix__cell';
+  const cellStyle = [];
   // Off cells keep the cell class (so they hold their grid track and 1:1
   // aspect-ratio); `grid: false` (implied by `solid`) only drops their lit
   // background, for the glyph-only look, without collapsing all-off rows.
-  const showPanel = grid && !solid;
-  const inner = cells
-    .map((c, i) => {
-      const cl = c.on ? cellClass(c) : 'ui-dotmatrix__cell';
-      const cellStyle = [];
-      if (!c.on && !showPanel) cellStyle.push('background:transparent');
-      if (stagger) cellStyle.push(`--i:${i}`);
-      const s = cellStyle.length ? ` style="${cellStyle.join(';')}"` : '';
-      return `<span class="${cl}"${s}></span>`;
-    })
-    .join('');
+  if (!cell.on && !showPanel) cellStyle.push('background:transparent');
+  // `reveal` staggers each cell by its row-major index via `--i`.
+  if (stagger) cellStyle.push(`--i:${index}`);
+  const style = cellStyle.length ? ` style="${cellStyle.join(';')}"` : '';
+  return `<span class="${cl}"${style}></span>`;
+}
 
-  // A `<span>` (not `<div>`): it's phrasing content, so the glyph is valid
-  // inline and inside a `<button>` (its content model is phrasing-only) — the
-  // inline-icon use. `.ui-dotmatrix`'s `display: grid` works on a span.
-  return `<span class="${cls}" style="${style.join(';')}" ${a11y}>${inner}</span>`;
+function a11yAttrs(label) {
+  return label ? `role="img" aria-label="${esc(label)}"` : 'aria-hidden="true"';
 }
 
 // Character → glyph name for renderReadout. Punctuation reuses the readout face