@ponchia/ui 0.6.6 → 0.6.8

package/docs/architecture.md

@@ -39,9 +39,12 @@ on top of the CSS, none of which require a framework commitment**:
 ├── connectors/  pure SVG leader-line geometry kernel (no DOM)        [optional]
 ├── annotations/ pure SVG callout geometry (builds on connectors)     [optional]
 ├── glyphs/      dot-matrix glyph registry/renderers                 [optional]
+├── schemas/     declarative JSON contracts for report/tooling data   [optional]
 ├── react/       thin React hooks over behaviors                     [optional peer]
 ├── solid/       thin Solid primitives over behaviors                [optional peer]
-└── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+├── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+├── svelte/      thin Svelte actions over behaviors                  [optional]
+└── vue/         thin Vue directives over behaviors                  [optional]
 ```
 
 ### Consequences of each layer
@@ -57,12 +60,12 @@ on top of the CSS, none of which require a framework commitment**:
 - **tokens/** — `index.js` (`cssVars`) is the single source of truth for token
   values. The four `:root` palette blocks of `css/tokens.css` are **generated**
   from it (`scripts/gen-tokens-css.mjs`), as are the JSON artifacts (`index.json`,
-  `tokens.dtcg.json`, `resolved.json`). So the dark palette is authored once,
-  not in three places (the two CSS dark blocks are now identical by
-  construction), resolving the duplication ADR-0003 flagged. The CSS-only
-  presets (density / contrast / OLED) stay hand-authored below a marker and are
-  preserved across regeneration. `scripts/check-fresh.mjs` fails CI if
-  `css/tokens.css` drifts from the model.
+  `tokens.dtcg.json`, `resolved.json`, `figma.variables.json`). So the dark
+  palette is authored once, not in three places (the two CSS dark blocks are now
+  identical by construction), resolving the duplication ADR-0003 flagged. The
+  CSS-only presets (density / contrast / OLED) stay hand-authored below a marker
+  and are preserved across regeneration. `scripts/check-fresh.mjs` fails CI if a
+  generated mirror drifts from the model.
 - **classes/** — `cls` is the flat registry; recipes only emit from it;
   `scripts/check-classes.mjs` enforces a bidirectional match with the
   stylesheet's `.ui-*` selectors. The class contract cannot silently rot.
@@ -76,24 +79,28 @@ on top of the CSS, none of which require a framework commitment**:
 - **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.
-- **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
-  They do not define markup, own state, or fork behavior logic; they only run
-  the vanilla initializers on mount and cleanup on unmount/dispose.
+- **react/** / **solid/** / **qwik/** / **svelte/** / **vue/** — optional lifecycle
+  adapters over `behaviors/`. They do not define markup, own state, or fork
+  behavior logic; they only run the vanilla initializers on mount and cleanup
+  on unmount/dispose. The Svelte and Vue adapters are plain action/directive
+  objects, so they do not add runtime dependencies to the package.
 - **`css/analytical.css` — the analytical roll-up.** This convenience file
-  `@import`s exactly **seven** analytical-figure leaves: `annotations`,
-  `legend`, `marks`, `connectors`, `spotlight`, `crosshair`, and `selection`.
-  The adjacent opt-in leaves — `sources`, `state`, `generated`, `workbench`,
-  and `command` — are report/tooling/trust surfaces that are intentionally
-  **not** part of the analytical roll-up and must be imported individually.
-  Importing `analytical.css` does not pull in any of those five.
+  `@import`s exactly **nine** analytical figure/evidence leaves: `figure`,
+  `annotations`, `legend`, `marks`, `connectors`, `spotlight`, `crosshair`,
+  `selection`, and `highlights`. The adjacent opt-in leaves — `sources`,
+  `interval`, `clamp`, `state`, `generated`, `workbench`, and `command` — are
+  report/tooling/trust surfaces that are intentionally **not** part of the
+  analytical roll-up and must be imported individually. Importing
+  `analytical.css` does not pull in any of those seven.
 - **Root export (`.`) is CSS-only.** `exports["."]` resolves to the CSS
   bundle (`dist/bronto.css`). It is a CSS side-effect import for CSS-aware
   bundlers (`@import '@ponchia/ui'` in CSS, or a side-effect
   `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
   the package root — Node/runtime JS imports of `.` are not supported. All JS
   entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
-  `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, `/charts`). This is a
-  permanent, intentional contract.
+  `/glyphs`, `/annotations`, `/connectors`, `/react`, `/solid`, `/qwik`,
+  `/svelte`, `/vue`, `/skins`, `/charts`, `/mermaid`, `/d2`, `/vega`). This is
+  a permanent, intentional contract.
 
 ## Repository layout
 
@@ -108,9 +115,10 @@ generator overwrites them and a drift gate fails CI).
 | --- | --- | --- | --- |
 | `css/` | source | yes | The framework. Hand-authored `@layer bronto` CSS. (`css/tokens.css` palette blocks and `css/generated.css` are generated — see below.) |
 | `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
-| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `svelte/`, `vue/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `schemas/*.schema.json` | source · published schema files (path-frozen) | yes — but **do not move exported files** | Declarative JSON Schema contracts for sidecars/tooling data. Each exported schema file path is public; the directory itself is not a wildcard import. No validator runtime ships. |
 | `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
-| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
+| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/figma.variables.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
 | `fonts/` | vendored | — | The Doto webfont (woff2) + its OFL license. |
 | `scripts/` | tooling | yes | `gen-*` regenerate artifacts, `check-*` are the drift/contract gates wired into `npm run check`, plus `build-dist`, `serve`, `size-report`. |
 | `docs/` | source (mostly) | yes | Hand-authored docs + ADRs; the curated subset in `package.json` `files` ships in the tarball. `docs/reference.md` is generated. |
@@ -127,24 +135,47 @@ the result.
 
 ## Drift control
 
-Every data mirror is backed by a check wired into `npm run check`, run by CI
-on every push/PR and again by `release.yml` before publish (see "Release
-gating" below), so a version that fails any invariant never reaches npm.
+Every data mirror and public documentation contract is backed by a check wired
+into `npm run check`, run by CI on every push/PR and again by `release.yml`
+before publish (see "Release gating" below), so a version that fails any
+invariant never reaches npm. Public authoring docs are treated as public surface
+too: `check:doc-links` fails stale local paths/anchors across shipped docs,
+GitHub-only docs, and the docs viewer route list, while shipped-doc links must
+also point at files present in the npm tarball. `check:contract` verifies
+documented named imports, `check:doc-recipes` fails copy-paste CDN recipes that
+silently no-op, and `check:report` validates fenced HTML snippets before they
+are copied into consumer reports.
 
 | Invariant                                       | Enforced by         |
 | ----------------------------------------------- | ------------------- |
-| exports / import graph / `files` consistent     | `check-exports.mjs` |
-| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
+| exports / import graph / source CSS `layer(bronto)` imports / layered-vs-unlayered CSS target map / `files` consistent | `check-exports.mjs` |
+| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `figma.variables.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
 | `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
-| `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
+| `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
 | legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
 | color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
 | `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
 | every shipped colorway accent meets its WCAG floor | `check-contrast.mjs` |
 | `dataviz.css`/`charts.json`/`charts.d.ts` ⇄ `tokens/charts.js` · CVD-distinguishable · opt-in | `check-charts.mjs` |
 | `shiki/nothing.json` valid + on rationed palette | `check-shiki.mjs`  |
-| `dist/*.css` == fresh build of `css/` + budget  | `check-dist.mjs`    |
+| `dist/*.css` == fresh single-`@layer bronto` build of `css/` + budget | `check-dist.mjs`    |
 | 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` |
+| 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` |
+| every public helper export in `classes`/`annotations`/`connectors`/`glyphs` has explicit docs, unit-test, and type-test ownership | `check-helper-matrix.mjs` |
+| every delegated behavior has React/Solid/Qwik hook, Svelte action, Vue directive, docs, example, unit, and type ownership | `check-binding-matrix.mjs` |
+| `@playwright/test` version ⇄ pinned Playwright container image ⇄ visual workflows/docs/local runner | `check-playwright-container.mjs` |
+| every shipped JSON schema is exported, documented, validates its public cookbook example, and rejects malformed sidecars | `check-schemas.mjs` |
+| packed public text contains no private terms, local paths, or secret-looking assignments | `check-public-hygiene.mjs` |
+| CSS custom-property references resolve or carry an explicit fallback/host boundary | `check-variables.mjs` |
+| `MIGRATIONS.json` edges have structured rules and matching docs | `check-migrations.mjs` |
+| example inventory ⇄ CI matrix ⇄ browser-smoke list ⇄ README rows ⇄ preview ports | `check-examples.mjs` |
+| demo visual snapshot declarations ⇄ committed Chromium baseline inventory | `check-visual-baselines.mjs` |
+| public authoring docs keep valid local paths/anchors; shipped-doc links resolve inside the tarball; docs viewer routes resolve | `check-doc-links.mjs` |
+| report/docs snippets use valid `ui-*` classes and public authoring snippets keep intact local id/ARIA/behavior references | `check-report.mjs` |
 | published `.d.ts` compile + reject typos        | `tsc` (`check:types`) |
 | CSS style/correctness                           | Stylelint           |
 | non-CSS source style                            | Prettier (`check:format`) |
@@ -160,32 +191,50 @@ payload contract, raised only intentionally with a CHANGELOG note.
 if the generated literal `cls`/token types stopped rejecting typos —
 so the *value* of the generated `.d.ts` is itself gated, not just their
 freshness (`check-fresh`).
+`check:consumer-types` then installs the packed tarball in a clean temp
+project and compiles package-subpath imports, so `exports.types` and
+internal declaration references are proven through consumer resolution.
 
 ## Release gating
 
-`release.yml` (on a pushed `v*` tag) is a five-job DAG, serialized by a
+`release.yml` (on a pushed `v*` tag) is a six-job DAG, serialized by a
 `concurrency: release-publish` group so two tags can't race the dist-tag
 pointer:
 
-- `validate` — read-only: `npm run check` + tag↔version match. `check`
-  includes `check:release`; for a prerelease tag the base version's
-  CHANGELOG section need only exist (`## Unreleased — x.y.z` is fine) —
-  only a stable release must carry a dated heading.
-- `e2e` — Playwright (visual + axe a11y, both themes, cross-engine) in
-  the pinned `mcr.microsoft.com/playwright` container.
+- `validate` — read-only: verifies the tag commit is reachable from `main`,
+  then runs `npm run check` and the tag↔version match. `check`
+  includes the node:test unit and contract suite, plus `check:release`;
+  for a prerelease tag the base version's CHANGELOG
+  section need only exist (`## Unreleased — x.y.z` is fine) — only a stable
+  release must carry a dated heading.
+- `e2e` — `needs: validate`: Playwright (visual + axe a11y, both themes,
+  demo structural integrity, both themes, cross-engine) in the pinned
+  `mcr.microsoft.com/playwright` container. Local cross-engine reproduction
+  without screenshot rasterisation is
+  `npm run test:e2e:nonpixel`; use `npm run test:e2e` or
+  `npm run test:e2e:chromium` only in the pinned container when the pixel
+  baseline gate itself is in scope. With Docker running,
+  `npm run test:e2e:visual:container` is the local shortcut for the same
+  Chromium screenshot environment.
 - `examples` — `needs: validate`: builds the downstream example
   apps against the **packed tarball**, mirroring CI. Catches a broken
   published surface (exports map / missing file / unresolved subpath)
   that `check:pack`'s file-allowlist inspection cannot — so the release
   path runs the same consumer smoke as merge-to-main.
-- `publish-npm` — `needs: [validate, e2e, examples]`: `npm publish` with
-  provenance. Runs in the `npm-publish` **Environment** (required-reviewer
-  protection), so after the gates pass the run pauses for a manual approval
-  in the Actions UI before anything reaches npm — a guard against an
-  accidental tag push publishing. Dist-tag is derived from the tag: stable
-  (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any hyphenated
-  identifier) → `next`, so the default `npm i @ponchia/ui` never moves onto
-  an unstable build (opt in with `@ponchia/ui@next`).
+- `publish-preflight` — `needs: [validate, e2e, examples]`: installs with
+  lifecycle scripts disabled, runs `npm pack --dry-run --ignore-scripts`, and
+  writes the pack manifest + size report to the job summary for review before
+  the protected publish approval.
+- `publish-npm` — `needs: publish-preflight`: `npm publish --ignore-scripts`
+  with provenance. Runs in the `npm-publish` **Environment**
+  (required-reviewer protection), so after the gates and preflight pass the run
+  pauses for a manual approval in the Actions UI before anything reaches npm —
+  a guard against an accidental tag push publishing. Dist-tag is derived from
+  the tag: stable (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any
+  hyphenated identifier) → `next`, so the default `npm i @ponchia/ui` never
+  moves onto an unstable build (opt in with `@ponchia/ui@next`). Post-publish
+  `npm view` registry observation is best-effort only: a registry read flake must
+  not fail the job after the immutable publish already succeeded.
 - `release-notes` — `needs: publish-npm`: a GitHub Release for visibility
   (transitively gated on a successful publish, hence on the gates above);
   prerelease tags are flagged so they aren't surfaced as "Latest". The Release
@@ -194,7 +243,7 @@ pointer:
   source of truth, surfaced where readers look.
 
 Because the documented install path is the npm package, **the npm publish
-is a real gate**: if `validate`, `e2e`, *or* `examples` fails,
+is a real gate**: if `validate`, `e2e`, `examples`, or `publish-preflight` fails,
 `publish-npm` never runs, the version never reaches the registry, and
 consumers never resolve it.
 (Corollary: a flaky `e2e` blocks releases — that is deliberate; fix the
@@ -210,9 +259,9 @@ Process still applies: bump `package.json`, land on `main`, go green, tag.
 ## Decision — distribution: npm public `@ponchia/ui`
 
 Decided 2026-05-15. The framework is consumed by a growing set of
-heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, vanilla),
-several deploying via third-party CI. The only option where onboarding a new
-frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
+heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, Vue,
+Tailwind, vanilla), several deploying via third-party CI. The only option where
+onboarding a new frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
 public**, and it uniquely also closes the release-gating gap (publish *is*
 the gate). GitHub Packages was rejected: it requires auth to install even
 public packages, i.e. an `.npmrc` + token on every frontend and CI runner —
@@ -237,8 +286,16 @@ explained, not surprising.
   provenance.
 - Run `npm pack --dry-run --json` locally or from CI logs and confirm the
   intended file count/payload.
-- Build the packed examples matrix (vanilla, Astro, SvelteKit, React, Solid, Qwik)
-  from the tarball, not a workspace link.
+- Build the packed examples matrix from the tarball, not a workspace link:
+  `npm run test:examples` covers vanilla, Astro, SvelteKit, Vue, React, Solid,
+  Qwik, Tailwind, and report-static, with Chromium browser smokes for runtime
+  examples. For a deeper consumer pass, `npm run test:examples:cross-browser`
+  runs the same packed smokes in Chromium, Firefox, and WebKit; manual CI
+  dispatches pass the same cross-browser flag to the reusable examples workflow.
+  `npm run test:examples:visual` adds local-safe desktop + mobile
+  screenshot/layout health smokes for packed examples; it detects blank,
+  under-painted, or horizontally overflowing output but intentionally does not
+  author OS-sensitive committed PNG baselines.
 - Confirm the GitHub Release body matches the curated changelog section.
 - If a bad package is published, deprecate that exact version on npm, publish a
   patched version, and link the deprecation note to the changelog/security

package/docs/clamp.md

@@ -0,0 +1,49 @@
+# Clamp
+
+`@ponchia/ui/css/clamp.css` is an opt-in bounded excerpt primitive for source
+excerpts, claim basis, caveats, and evidence text that should scan compactly but
+remain reachable.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/clamp.css';
+```
+
+## Bounded excerpt
+
+```html
+<div class="ui-clamp" style="--clamp-lines: 3">
+  <input class="ui-clamp__toggle" id="source-excerpt" type="checkbox" />
+  <p class="ui-clamp__body">
+    The source excerpt remains real text in the DOM. The visible block is
+    clamped for scanning, but the full passage is available through the reveal
+    control and is expanded for print.
+  </p>
+  <label class="ui-clamp__control" for="source-excerpt">
+    <span class="ui-clamp__more">Show more</span>
+    <span class="ui-clamp__less">Show less</span>
+  </label>
+</div>
+```
+
+If the host should not offer expansion, omit the toggle and control and keep
+only `ui-clamp` plus `ui-clamp__body`.
+
+## Contract
+
+| Class | Role |
+| --- | --- |
+| `.ui-clamp` | Wrapper and `--clamp-lines` host. |
+| `.ui-clamp__body` | The clamped text block. |
+| `.ui-clamp__toggle` | Optional checkbox state for CSS-only reveal. |
+| `.ui-clamp__control` | Optional visible reveal control. |
+| `.ui-clamp__more` / `.ui-clamp__less` | Explicit labels for closed/open state. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--clamp-lines` | `.ui-clamp` | Number of lines before the excerpt is clamped. Default `4`. |
+
+## Print
+
+Print expands the body and hides the toggle/control. Do not use `ui-clamp` to
+hide information from archived or PDF output.

package/docs/command.md

@@ -84,7 +84,10 @@ document.querySelector('[data-bronto-command]').addEventListener('bronto:command
 );
 ```
 
-Framework hook: `useCommand()` in `@ponchia/ui/react` · `/solid` · `/qwik`.
+Framework adapters: `useCommand()` in `@ponchia/ui/react`, `/solid`, and
+`/qwik`; the `command` / `useCommand` action in `@ponchia/ui/svelte`; and
+`vCommand` (or the `v-bronto-command` directive from `brontoVue`) in
+`@ponchia/ui/vue`.
 
 ## Accessibility
 

package/docs/connectors.md

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

package/docs/contrast.md

@@ -15,7 +15,8 @@ model (`tokens/resolved.json`) so it cannot drift from the palette, and
 
 - **Body / UI text** pairings are guaranteed **WCAG 2.1 AA — 4.5:1**
   (1.4.3). This covers `--text`, `--text-soft`, `--text-dim`,
-  `--accent-text`, and the primary-button label.
+  `--accent-text`, neutral text on soft accent-tint components, and the
+  primary-button label.
 - **Non-text UI** (focus ring, accent fill, status colour) is guaranteed
   **3:1** (1.4.11 non-text contrast / the large-text bar). These are
   deliberately *not* held to 4.5:1 — a focus
@@ -32,7 +33,8 @@ model (`tokens/resolved.json`) so it cannot drift from the palette, and
   further but is out of scope for this gated baseline.
 
 Translucent foregrounds (soft fills) are alpha-flattened over their
-background before measuring — the ratio the eye actually gets.
+background before measuring. When a translucent background is a component
+tint, the table names the neutral base it is composited over.
 
 Overall: **all contractual pairings meet their floor ✅**.
 
@@ -51,6 +53,7 @@ Overall: **all contractual pairings meet their floor ✅**.
 | `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 66.7 | ✅ pass |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75.4 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82.1 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.88:1 | Lc 77.0 | ✅ pass |
 | `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.91:1 | Lc 71.0 | ℹ️ not gated |
 | `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.31:1 | Lc 75.3 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
@@ -77,10 +80,11 @@ Overall: **all contractual pairings meet their floor ✅**.
 | `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50.3 | ✅ pass |
 | `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49.3 | ✅ pass |
 | `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48.1 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 44.9 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 43.9 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.53:1 | Lc 43.8 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.75:1 | Lc 49.1 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.42:1 | Lc 46.6 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.84:1 | Lc 45.6 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.05:1 | Lc 68.4 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.42:1 | Lc 42.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.63:1 | Lc 47.4 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
@@ -109,8 +113,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.75:1 | Lc 78.9 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 85.6 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.31:1 | Lc 74.5 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.74:1 | Lc 78.8 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 9.13:1 | Lc 78.7 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.48:1 | Lc 76.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.85:1 | Lc 79.9 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
@@ -121,10 +126,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 74.8 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 73.8 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.34:1 | Lc 15.1 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.3 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.84:1 | Lc 76.1 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.77:1 | Lc 75.1 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.83:1 | Lc 65.5 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.51:1 | Lc 23.2 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
@@ -137,8 +143,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93.3 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 99.9 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.43:1 | Lc 88.8 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.22:1 | Lc 93.2 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.78:1 | Lc 76.3 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.31:1 | Lc 88.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.15:1 | Lc 92.8 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
@@ -149,10 +156,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79.1 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78.1 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.25:1 | Lc 11.0 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.35:1 | Lc 16.3 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.72:1 | Lc 80.3 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.57:1 | Lc 79.3 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.66:1 | Lc 65.0 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.38:1 | Lc 18.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.42:1 | Lc 19.9 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
@@ -165,8 +173,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 76.6 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83.3 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.81:1 | Lc 72.2 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.21:1 | Lc 76.5 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 9.16:1 | Lc 78.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.98:1 | Lc 74.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.32:1 | Lc 77.7 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
@@ -177,10 +186,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 81.8 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 80.8 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.20:1 | Lc 8.4 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.30:1 | Lc 13.7 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 13.18:1 | Lc 82.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.99:1 | Lc 81.8 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.66:1 | Lc 65.0 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.33:1 | Lc 15.3 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.37:1 | Lc 17.3 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |

package/docs/crosshair.md

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

package/docs/d2.md

@@ -153,6 +153,43 @@ paste the resolved hex from [`tokens/resolved.json`](./architecture.md) for a
 For anything larger or graph-laid-out, run D2 with the theme map and freeze its
 output — don't hand-lay a complex graph.
 
+### Tokenize D2 output — one inline SVG that re-skins live
+
+A frozen D2 SVG carries **resolved hex**, so a dynamic (screen-only) report
+would need a light SVG and a dark SVG and JS/CSS to swap them — and the hidden
+twin is dead weight. Instead, post-process the rendered SVG's colours back into
+tokens, and ONE inline SVG re-skins live when `data-theme` flips (this is the
+inverse of the resolved-hex rule above: it only works for **inline** SVG in a
+themed page, never for `file://`/PDF artifacts or `<img>` embeds):
+
+1. Render **light only** with the theme map (`brontoD2Vars()` prepended).
+2. D2 emits each colour twice: as inline `fill="#hex"`/`stroke="#hex"` AND as
+   class rules in an embedded `<style>` block — **not just `.fill-*` /
+   `.stroke-*`: there are also `.color-*` and `.background-color-*` rules**
+   (they carry the same hex and trip any raw-colour gate). **The style rules
+   win over the inline attributes**, so strip ALL hex-bearing rules from the
+   `<style>` first — only then do attribute rewrites take effect.
+3. Rewrite the inline hex → `var(--token)` using the slot table above
+   (`N1`→`--text`, `N4`/`B1`→`--line-strong`, `N6`/`B4`→`--panel-soft`,
+   `B6`→`--panel`, accent class fill→`--accent`, its ink→`--on-accent`, …).
+4. Leave `<mask>` `fill="black"`/`"white"` keywords alone — that is a
+   luminance mask, not a colour.
+5. Make the outer `<svg>` fluid (drop `width`/`height`, keep `viewBox`) and
+   inject `<title>` + `<desc>` with `role="img" aria-labelledby` before
+   inlining.
+
+The result follows the page theme with zero swap machinery, and avoids the
+visual-QA traps of the two-SVG approach (a `display:none` twin is easy to
+flag as a blank figure).
+
+> **Avoid `tooltip:` and `|md` markdown shapes in frozen report SVGs.** Both
+> make D2 embed GitHub-Primer styling that survives tokenization: tooltips
+> render Octicon info-icons and markdown text ships Primer CSS, each full of
+> foreign `var(--color-*)` references and extra hex (`#2e3346`-class values
+> outside the theme map). Fold tooltip text into the node label and use plain
+> labels or `shape: text` instead — or strip the tooltip appendix from the
+> SVG before inlining.
+
 ### Fit to small screens
 
 D2 emits an SVG with explicit `width`/`height` from its layout, so on a narrow

package/docs/dots.md

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