@ponchia/ui 0.6.8 → 0.6.10

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/docs/workbench.md

@@ -1,10 +1,11 @@
-# Workbench — split panes, inspector, properties, selection bar
+# Workbench — split panes, toolstrips, inspector, properties, selection bar
 
 `@ponchia/ui/css/workbench.css` is an opt-in set of primitives for **real
-tools**: resizable split panes, an inspector panel, property rows for a selected
-object, and a bar of actions on the current selection. Generic kits stop at
-cards/tables/forms, so every app builds its own half-consistent workbench. This
-is the low-risk core — layout, resize affordance, and ARIA value sync.
+tools**: resizable split panes, compact toolstrips, button-mode segmented
+controls, an inspector panel, property rows for a selected object, and a bar of
+actions on the current selection. Generic kits stop at cards/tables/forms, so
+every app builds its own half-consistent workbench. This is the low-risk core —
+layout, dense controls, resize affordance, and ARIA value sync.
 
 ```css
 @import '@ponchia/ui';
@@ -20,6 +21,51 @@ initSplitter();
 Not in the core bundle. Import the CSS leaf where the workbench appears and run
 `initSplitter()` only if the page includes `[data-bronto-splitter]`.
 
+## Toolstrip — `.ui-toolstrip`
+
+A compact row of controls for a tool surface or viewport. Use
+`.ui-toolstrip--floating` when the strip sits over a canvas, chart, map, media
+stage, or preview. The CSS owns density, wrapping, grouping, and raised/floating
+treatment; the host owns commands, search behavior, active mode, responsive
+hiding, and placement.
+
+```html
+<header class="ui-toolstrip ui-toolstrip--floating" aria-label="View controls">
+  <div class="ui-toolstrip__brand">
+    <strong>Repository</strong>
+    <span class="ui-toolstrip__context">main branch</span>
+  </div>
+  <div class="ui-toolstrip__group" aria-label="Mode">
+    <button class="ui-segmented-buttons__button" type="button" aria-pressed="true">Map</button>
+    <button class="ui-segmented-buttons__button" type="button" aria-pressed="false">Flow</button>
+    <button class="ui-segmented-buttons__button" type="button" aria-pressed="false">Risk</button>
+  </div>
+  <label class="ui-toolstrip__search">
+    <span class="ui-visually-hidden">Filter items</span>
+    <input class="ui-input" type="search" placeholder="Filter by path, owner, or tag" />
+  </label>
+  <div class="ui-toolstrip__actions" aria-label="Viewport actions">
+    <button class="ui-button ui-button--ghost ui-button--icon ui-button--sm" type="button">
+      Fit
+    </button>
+  </div>
+</header>
+```
+
+## Button segmented control — `.ui-segmented-buttons`
+
+Use `.ui-segmented-buttons` when each option is a real command button and the
+current mode is exposed with `aria-pressed`. For form values submitted with the
+page, keep using the core `.ui-segmented` radio-input pattern.
+
+```html
+<div class="ui-segmented-buttons" aria-label="Density">
+  <button class="ui-segmented-buttons__button" type="button" aria-pressed="true">Dense</button>
+  <button class="ui-segmented-buttons__button" type="button" aria-pressed="false">Comfort</button>
+  <button class="ui-segmented-buttons__button" type="button" aria-pressed="false">Wide</button>
+</div>
+```
+
 ## Splitter — `.ui-splitter`
 
 Two panes separated by a focusable ARIA separator handle. The CSS owns the grid
@@ -113,7 +159,8 @@ A raised bar of actions on the current selection: a `__count` on one side,
 ## Scope
 
 No recipes — these are structural containers and rows; apply the classes
-directly (or read them from `cls.splitter`, `cls.inspector`, `cls.property`, …).
-Pair the selection bar with the cross-cutting [`ui-sel`](./selection.md) states
-on the selected items themselves. Bronto styles both and wires the splitter
-affordance; the host owns hit-testing, persistence, pane contents, and commands.
+directly (or read them from `cls.toolstrip`, `cls.splitter`, `cls.inspector`,
+`cls.property`, …). Pair the selection bar with the cross-cutting
+[`ui-sel`](./selection.md) states on the selected items themselves. Bronto styles
+the chrome and wires the splitter affordance; the host owns hit-testing,
+persistence, pane contents, viewport semantics, and commands.

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

package/llms.txt

@@ -44,7 +44,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.10/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand
@@ -244,7 +244,10 @@ chart rendering, overlay content, and accessibility text. Details:
 
 Optional SVG annotations for charts/reports — opt-in, never in the default
 bundle. This is Bronto's subject / connector / note grammar inspired by
-d3-annotation, not an authoring engine:
+d3-annotation, not an authoring engine. For placement, collision handling,
+renderers, editing, and chart/diagram adapters, use the sibling
+`@ponchia/annotations` package; `@ponchia/ui/annotations` stays a
+dependency-free Bronto static-helper compatibility surface:
 
 ```html
 <link rel="stylesheet" href="@ponchia/ui/css/annotations.css" />
@@ -750,7 +753,8 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `schemas/report-claims.v1.schema.json` — declarative JSON Schema for
   `claims.json` sidecars that map report claims to source IDs and relations.
 - `docs/annotations.md` — SVG annotation recipes and helper guidance for
-  analytical figures.
+  analytical figures, plus the boundary with the sibling `@ponchia/annotations`
+  engine package.
 - `docs/mermaid.md` — theme Mermaid diagrams from bronto tokens (resolved
   `base` themeVariables, gated) and annotate the rendered SVG.
 - `docs/d2.md` — theme D2 diagrams from bronto tokens (theme-override slots,
@@ -775,7 +779,9 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   `glyphCells` signatures for the display glyphs. (The DOM form,
   `initDotGlyph`, is declared in `behaviors/index.d.ts`.)
 - `annotations/index.d.ts` — no-dependency SVG path helpers for Bronto
-  annotation geometry.
+  annotation geometry. Do not add placement/collision/renderers/adapters here;
+  that belongs in `@ponchia/annotations`; do not import or type-reference that
+  sibling package from `@ponchia/ui` code or declarations.
 - `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
 
 ## External web references

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "type": "module",
   "description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
   "keywords": [
@@ -102,6 +102,7 @@
     "docs/workbench.md",
     "docs/command.md",
     "docs/interop/tailwind.md",
+    "docs/interop/react-flow.md",
     "docs/migrations/0.2-to-0.3.md",
     "docs/migrations/0.3-to-0.4.md",
     "docs/migrations/0.4-to-0.5.md",
@@ -147,6 +148,7 @@
     "check:classes": "node scripts/check-classes.mjs",
     "check:recipe-types": "node scripts/check-recipe-types.mjs",
     "check:dead": "knip --treat-config-hints-as-errors",
+    "check:complexity": "node scripts/check-complexity.mjs",
     "check:chain": "node scripts/check-chain.mjs",
     "check:dts-emit": "node scripts/check-dts-emit.mjs",
     "check:glyphs": "node scripts/check-glyphs.mjs",
@@ -186,7 +188,7 @@
     "check:publint": "publint --strict",
     "check:attw": "attw --pack --ignore-rules no-resolution cjs-resolves-to-esm",
     "check:workflows": "github-actionlint .github/workflows/*.yml",
-    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:fresh && npm run check:classes && npm run check:recipe-types && npm run check:dead && npm run check:types && npm run check:unit && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:consumer-surface && npm run check:consumer-types && npm run check:component-matrix && npm run check:behavior-matrix && npm run check:helper-matrix && npm run check:binding-matrix && npm run check:examples && npm run check:visual-baselines && npm run check:playwright-container && npm run check:schemas && npm run check:publint && npm run check:attw && npm run check:workflows && npm run check:release && npm run check:versions && npm run check:migrations && npm run check:public-metadata && npm run check:public-hygiene && npm run check:doc-links && npm run check:doc-recipes && npm run check:contract && npm run check:variables && npm run check:contrast && npm run check:dts-emit && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:mermaid && npm run check:d2 && npm run check:vega && npm run check:report && npm run check:legend && npm run check:chain",
+    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:fresh && npm run check:classes && npm run check:recipe-types && npm run check:dead && npm run check:complexity && npm run check:types && npm run check:unit && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:consumer-surface && npm run check:consumer-types && npm run check:component-matrix && npm run check:behavior-matrix && npm run check:helper-matrix && npm run check:binding-matrix && npm run check:examples && npm run check:visual-baselines && npm run check:playwright-container && npm run check:schemas && npm run check:publint && npm run check:attw && npm run check:workflows && npm run check:release && npm run check:versions && npm run check:migrations && npm run check:public-metadata && npm run check:public-hygiene && npm run check:doc-links && npm run check:doc-recipes && npm run check:contract && npm run check:variables && npm run check:contrast && npm run check:dts-emit && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:mermaid && npm run check:d2 && npm run check:vega && npm run check:report && npm run check:legend && npm run check:chain",
     "test": "node --test \"test/*.test.mjs\"",
     "test:e2e": "playwright test",
     "test:e2e:chromium": "playwright test --project=chromium",
@@ -388,6 +390,7 @@
     "./docs/workbench.md": "./docs/workbench.md",
     "./docs/command.md": "./docs/command.md",
     "./docs/interop/tailwind.md": "./docs/interop/tailwind.md",
+    "./docs/interop/react-flow.md": "./docs/interop/react-flow.md",
     "./docs/migrations/0.2-to-0.3.md": "./docs/migrations/0.2-to-0.3.md",
     "./docs/migrations/0.3-to-0.4.md": "./docs/migrations/0.3-to-0.4.md",
     "./docs/migrations/0.4-to-0.5.md": "./docs/migrations/0.4-to-0.5.md",

package/schemas/report-claims.v1.schema.json

@@ -56,7 +56,7 @@
     },
     "hash": {
       "type": "string",
-      "pattern": "^(sha256|sha384|sha512):[A-Fa-f0-9]+$"
+      "pattern": "^(sha256:[A-Fa-f0-9]{64}|sha384:[A-Fa-f0-9]{96}|sha512:[A-Fa-f0-9]{128})$"
     },
     "claimStatus": {
       "enum": ["supported", "partial", "disputed", "unsupported", "unknown"]

package/tokens/index.js

@@ -115,7 +115,7 @@ export const cssVars = {
     // (D2/Mermaid/Vega labels on an accent fill — see tokens/*.json). In-DOM
     // components paint their own on-accent ink from `--button-text`; overriding
     // `--on-accent` in CSS does NOT change a button/chip. To re-ink in-DOM
-    // accent fills, set `--button-text`. (tokens review C7.)
+    // accent fills, set `--button-text`.
     '--on-accent': 'var(--button-text)',
     '--accent-soft': 'color-mix(in srgb, var(--accent) 10%, transparent)',
     '--success': '#2f7d4f',
@@ -156,7 +156,7 @@ export const cssVars = {
     // (D2/Mermaid/Vega labels on an accent fill — see tokens/*.json). In-DOM
     // components paint their own on-accent ink from `--button-text`; overriding
     // `--on-accent` in CSS does NOT change a button/chip. To re-ink in-DOM
-    // accent fills, set `--button-text`. (tokens review C7.)
+    // accent fills, set `--button-text`.
     '--on-accent': 'var(--button-text)',
     '--accent-soft': 'color-mix(in srgb, var(--accent) 14%, transparent)',
     '--success': '#4ec27e',