@ponchia/ui 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,9 +1,234 @@
 # Changelog
 
-> **Versioning:** pre-1.0, breaking changes ship in the _minor_. Pin
-> `~0.x`; `^0.x` does **not** protect you. See README → Versioning, and
+> **Versioning:** pre-1.0, breaking changes ship in the _minor_. Pin to the
+> minor — `~0.4.0` (equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`; a bare
+> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 > the deprecation policy in CONTRIBUTING.md.
 
+## 0.5.0 — 2026-06-02
+
+A **minor** that builds out the "analytical & generated-report UI" identity: a
+full suite of opt-in **communication primitives** — SVG annotations, legends,
+text/evidence marks, leader-line connectors, a guided-focus spotlight, a
+crosshair/readout, a selection-state vocabulary, label declutter + direct labels
+(`declutterLabels`/`directLabels`), and a source/citation/provenance **trust
+layer** — plus a consolidation pass over them. Each owns its visual grammar and
+pure geometry and refuses to own scales/state/hit-testing (no chart engine).
+
+Per the project's versioning policy, breaking changes ship in the minor. This
+release carries three: the opt-in report kit's chart data key moved into the new
+legend layer (`.ui-chart__legend`/`__swatch` removed — see Changed and
+[`MIGRATIONS.json`](MIGRATIONS.json)), annotation arrowheads now render via
+the shared connectors geometry kernel (a small path-shape change), and the
+opt-in marks' rationed-accent tone was renamed `evidence`→`accent` to match the
+rest of the analytical tone vocabulary. Everything else is additive and opt-in,
+save for the tiny `.ui-shortcut` keyboard-hint primitive that joins the core
+layer; the rest of the default `dist/bronto.css` is unchanged. Also folds in the
+0.4.x maintenance hardening that had not yet been released.
+
+### Added
+
+- **SVG annotations** (`@ponchia/ui/css/annotations.css`,
+  `@ponchia/ui/annotations`, `.ui-annotation*`, `ui.annotation()`): an opt-in
+  annotation layer for charts, reports, and analytical figures, following the
+  d3-annotation grammar (a **subject** marks the thing, a **connector** points
+  away, a **note** carries the text). Ships a class grammar (variants for
+  label/callout/elbow/curve/circle/rect/threshold/badge/bracket/band/slope/
+  compare/cluster/axis/timeline/evidence, six tones, and opt-in
+  `draw`/`reveal`/`pulse`/`focus` motion that respects `prefers-reduced-motion`)
+  plus tiny geometry helpers that return SVG strings only — they own no chart
+  scales, mutate no DOM, and provide no edit mode. Documented in
+  [`docs/annotations.md`](docs/annotations.md) and gated by `check:report`.
+- **Legends / data keys** (`@ponchia/ui/css/legend.css`, `.ui-legend*`,
+  `ui.legend()`/`ui.legendItem()`/`ui.legendSwatch()`, `initLegend`): an opt-in,
+  standalone data-key layer that reads the `--chart-*` palette tokens.
+  Categorical, continuous gradient (sequential + `--diverging`), threshold, and
+  pattern keys; swatch colour set inline (`--chart-color`) or via
+  `.ui-legend__swatch--1..8` index helpers; vertical/compact/with-values
+  layouts. WCAG 1.4.1 by construction (the text label is the non-colour
+  channel), with `forced-colors` and print care. Optional interactive
+  (series-toggling) entries are `<button aria-pressed>` controls: `initLegend`
+  flips `aria-pressed`/`.is-inactive` and emits `bronto:legend:toggle`
+  (`{ series, active }`) — the host owns hiding the series and any `aria-live`
+  announcement (it is never a chart engine). Optional `useLegend` hook in the
+  React/Solid/Qwik bindings. New `check:legend` gate proves swatch colours are a
+  subset of `tokens/charts.js` and never a raw hex. Documented in
+  [`docs/legends.md`](docs/legends.md).
+- **Text marks / evidence** (`@ponchia/ui/css/marks.css`, `.ui-mark*`,
+  `.ui-bracket-note*`, `ui.mark()`/`ui.bracketNote()`): an opt-in layer of
+  sober, report-grade emphasis for running prose — the counterpart to SVG
+  annotations (annotations call out a figure, marks call out a sentence). Inline
+  `.ui-mark` (highlight/underline/box/strike; `--accent` + status
+  tones; `--draw` reduced-motion-safe sweep) for use on `<mark>`, and
+  `.ui-bracket-note` for bracketing a whole passage. Pure CSS on semantic
+  tokens, monochrome by default, with `forced-colors` care. Documented in
+  [`docs/marks.md`](docs/marks.md).
+- **Connectors / leader lines** (`@ponchia/ui/css/connectors.css`,
+  `@ponchia/ui/connectors`, `.ui-connector*`, `initConnectors`, `ui.connector()`):
+  an opt-in layer that draws a line between two DOM elements (the
+  page-coordinate cousin of annotations). Pure geometry helpers
+  (`connectRects`/`connectorPath`/`arrowHead`/…) that return SVG strings and own
+  no DOM, an `.ui-connector` overlay grammar (straight/elbow/curve, arrow/dot
+  ends, tones, dashed, `--draw`), and an optional `initConnectors` behavior that
+  draws + tracks on resize/scroll. `useConnectors` in the bindings. Documented in
+  [`docs/connectors.md`](docs/connectors.md).
+- **Spotlight / guided focus** (`@ponchia/ui/css/spotlight.css`, `.ui-spotlight*`,
+  `.ui-tour-note*`, `initSpotlight`, `ui.spotlight()`): an opt-in guided-focus
+  overlay — a box-shadow cutout over a target element, optional ring, and a
+  callout note. `initSpotlight` positions the cutout (`--spot-x/y/w/h`) and
+  re-places on resize/scroll and when `data-target` changes. Deliberately **not**
+  a tour engine — the host owns step order/advancing/visibility. `useSpotlight`
+  in the bindings. Documented in [`docs/spotlight.md`](docs/spotlight.md).
+- **Crosshair / readout** (`@ponchia/ui/css/crosshair.css`, `.ui-crosshair*`,
+  `.ui-readout`, `initCrosshair`, `ui.crosshair()`): an opt-in plot ruler +
+  pinned readout. `initCrosshair` tracks the pointer over a
+  `[data-bronto-crosshair]` plot, sets `--crosshair-x/y`, and dispatches
+  `bronto:crosshair:move` with px + 0–1 fractions — it reports position only and
+  never maps pixels to data (that needs the host's scales). `useCrosshair` in the
+  bindings. Documented in [`docs/crosshair.md`](docs/crosshair.md).
+- **Selection states** (`@ponchia/ui/css/selection.css`, `.ui-sel*`,
+  `ui.sel()`): a tiny cross-cutting selection-emphasis vocabulary
+  (`--on`/`--off`/`--maybe`) reusable on chart marks, table rows, list items, or
+  map regions. The carve-out from brush/lasso — Bronto styles the states; the
+  host owns the selection/hit-test logic. Documented in
+  [`docs/selection.md`](docs/selection.md).
+- **Sources, citations & provenance** (`@ponchia/ui/css/sources.css`,
+  `.ui-citation`/`.ui-source-card`/`.ui-source-list`/`.ui-provenance`,
+  `ui.citation()`/`ui.source()`/`ui.provenance()`): an opt-in, CSS-only **trust
+  layer** for generated reports and AI output — the grammar for "where did this
+  come from?". A cross-cutting `.ui-src--*` state (verified/reviewed/generated/
+  unverified/stale/conflict) sets a rationed tone, always paired with an
+  author-written label (never colour alone). Bronto owns the grammar + states;
+  the host owns fetching, citation numbering, and trust. The first
+  frontier-primitive beyond the analytical suite. Documented in
+  [`docs/sources.md`](docs/sources.md).
+- **Keyboard-shortcut hint** (`.ui-shortcut` + `.ui-shortcut__sep`, core): a tiny
+  universal-chrome primitive that lays out one or more `.ui-kbd` keys as a chord
+  (`⌘`+`K`) or sequence (`G` then `I`) with a dim connective. The command tier's
+  smallest piece, broadly useful outside a palette (menu items, buttons,
+  tooltips). Class-only, like `.ui-kbd`.
+- **Lifecycle / system state** (`@ponchia/ui/css/state.css`, `.ui-state`
+  (+`__label`/`__detail`/`--busy`) with canonical state modifiers
+  (saving/saved/queued/offline/stale/conflict/error/locked/reviewed/
+  needs-review), `.ui-syncbar`, `ui.state()`): an opt-in, CSS-only vocabulary for
+  the states apps actually live in — a labelled state object with a rationed tone
+  and a page/document sync bar. The label is the state (never colour alone);
+  `--busy` pulses the indicator (reduced-motion-safe). Bronto ships the visual
+  states + canonical wording; the host owns the state machine, retry, and
+  persistence. Frontier candidate #2. Documented in [`docs/state.md`](docs/state.md).
+- **Generated content & AI trust** (`@ponchia/ui/css/generated.css`,
+  `.ui-generated`/`.ui-origin-label`/`.ui-reasoning`/`.ui-tool-log`/`.ui-tool-call`,
+  `ui.originLabel()`): an opt-in, CSS-only set of **trust surfaces** for AI /
+  system-generated content — a marked region, an origin label, and quiet
+  native-`<details>` reasoning + tool-call logs. Not a chat kit; no
+  fabricated-confidence widget. Bronto styles disclosure/origin/trace, the host
+  owns model metadata, redaction, and safety. Pairs with the source layer.
+  Documented in [`docs/generated.md`](docs/generated.md).
+- **Workbench** (`@ponchia/ui/css/workbench.css`, `.ui-inspector`/`.ui-property`/
+  `.ui-selectionbar`): an opt-in, CSS-only core for tool UIs — a selected-object
+  inspector panel, denser property rows, and a raised selection action bar.
+  Layout + affordances only; resizable split panes and drag handles are
+  deferred. Documented in [`docs/workbench.md`](docs/workbench.md).
+- **Command palette** (`@ponchia/ui/css/command.css`, `.ui-command` (+
+  `__input`/`__list`/`__group`/`__item`/`__shortcut`/`__meta`/`__empty`),
+  `initCommand`, `useCommand`): an opt-in CSS shell + behavior — filter +
+  keyboard-navigate a DOM-authored command list (roving focus, group hiding,
+  full keyboard), emitting `bronto:command:select` ({ value, label }) and
+  `bronto:command:close`. Bronto navigates; the host owns the action registry,
+  routing, and execution. No global Cmd/Ctrl+K. Completes the command tier
+  (frontier #3) atop the shipped `ui-shortcut`. Documented in
+  [`docs/command.md`](docs/command.md).
+- **Label declutter** (`@ponchia/ui/annotations` `declutterLabels`): a
+  deterministic, order-preserving **1-D** label de-overlap helper (sort, push
+  apart by `size + gap`, slide to fit `max`) — pure, no DOM/scales. Not a 2-D
+  collision solver. Documented in [`docs/annotations.md`](docs/annotations.md).
+- **Direct labels** (`@ponchia/ui/annotations` `directLabels`): the
+  direct-labeling companion to `declutterLabels` — it declutters labels along an
+  axis **and** draws the leader from each anchor to its placed label, reusing the
+  connectors geometry kernel. Returns `[{ x, y, anchor, key, d }]` (the `d` feeds
+  a `ui-annotation__connector`). Deterministic and pure: no scales, no DOM, no
+  2-D placement (the 1-D core of Labella, completed with leaders). Documented in
+  [`docs/annotations.md`](docs/annotations.md).
+- **Connectors** (`@ponchia/ui/connectors`, `@ponchia/ui/css/connectors.css`,
+  `initConnectors`, `useConnectors`, `ui.connector()`) and **Spotlight**
+  (`css/spotlight.css`, `initSpotlight`, `ui.spotlight()`) — leader lines between
+  DOM elements and a guided-focus overlay; both opt-in, geometry/visual only
+  (the host owns layout/tour state).
+- **Crosshair / readout** (`css/crosshair.css`, `initCrosshair`,
+  `ui.crosshair()`) and **selection states** (`css/selection.css`, `ui.sel()`) —
+  a plot ruler that reports pointer position (not data), and a cross-cutting
+  `.ui-sel--on/off/maybe` emphasis vocabulary (the host owns brush/hit-test).
+- **`@ponchia/ui/css/analytical.css`** — a convenience roll-up that bundles the
+  seven analytical leaves (annotations, legend, marks, connectors, spotlight,
+  crosshair, selection) into one import. Add `dataviz.css`/`report.css`
+  separately as needed.
+
+### Fixed
+
+- The optional Qwik binding (`@ponchia/ui/qwik`) is now built from the packed
+  tarball in CI **and** release, alongside React/Solid — closing a coverage gap
+  (it was documented as optimizer-proven but no job actually built it). Also
+  covered by `check:pack`, the size report, and the dead-code config.
+
+### Changed
+
+- **Breaking (opt-in report kit):** the chart data key moved out of
+  `css/report.css` into the standalone `css/legend.css`. `.ui-chart__legend` →
+  `.ui-legend` (now with `.ui-legend__item`/`.ui-legend__label` rows) and
+  `.ui-chart__swatch` → `.ui-legend__swatch`. Import `@ponchia/ui/css/legend.css`
+  beside the report kit; see [`MIGRATIONS.json`](MIGRATIONS.json) and
+  [`docs/legends.md`](docs/legends.md). The `--chart-color`/`--chart-pattern`
+  swatch contract is unchanged, so the rename is mechanical.
+- **Breaking (opt-in marks):** the rationed-accent **tone** on `.ui-mark` and
+  `.ui-bracket-note` was renamed `evidence` → `accent` (`ui-mark--evidence` →
+  `ui-mark--accent`, `ui-bracket-note--evidence` → `ui-bracket-note--accent`;
+  `ui.mark({ tone: 'accent' })` / `ui.bracketNote({ tone: 'accent' })`) so the
+  accent tone reads the same across every analytical primitive (it already was
+  `accent` on `ui.connector`/`ui.annotation`). `.ui-annotation--evidence` is
+  **unchanged** — it is a marker _variant_ (a proof/source shape), not a tone.
+  Mechanical whole-token rename; see [`MIGRATIONS.json`](MIGRATIONS.json).
+- **Consolidation:** the SVG geometry is single-sourced in the `connectors`
+  kernel — `@ponchia/ui/annotations` now builds its connectors on it, so a
+  line/curve/arrow/dot is drawn one way across both. `connectorLine`/`Curve`/
+  `EndDot` output is byte-identical; **`connectorEndArrow` is the one
+  (minor-breaking) shape change** — the arrowhead now matches the connectors
+  arrowhead. New `check:helpers-dts` gate keeps the hand-maintained
+  `annotations`/`connectors` `.d.ts` in parity with their runtime exports.
+- The Doto webfont now ships as **woff2 only** (Brotli) instead of uncompressed
+  TTF: ~5.7 kB per weight vs ~137 kB, cutting the six-weight payload from ~823 kB
+  to ~35 kB (the dot-matrix glyphs compress ~96%) and shrinking the unpacked
+  tarball by roughly the same. No TTF fallback is carried — woff2 is supported by
+  the entire browser floor (ADR-0002: Chrome 125 / Safari 18 / Firefox 129).
+  `@font-face` is internal, so this is transparent to consumers; only self-hosts
+  that referenced `fonts/doto-*.ttf` directly need to point at `*.woff2`.
+- `docs/architecture.md` now ships in the package, so the offline rationale the
+  shipped ADRs link to resolves inside the tarball.
+- `docs/stability.md` clarifies that `data-surface`/`data-density`/
+  `data-contrast` are **convenience presets**, not part of the stability
+  contract; `data-theme` (light/dark) remains the contractual base.
+
+### Internal
+
+- Token values are single-sourced in `tokens/index.js` (`cssVars`); the
+  `css/tokens.css` palette is generated from it, so the dark palette is authored
+  once instead of in three places (the shipped CSS is byte-identical).
+- `behaviors/index.js` is split into per-behavior modules behind the same public
+  barrel (no surface change).
+- Drift-gate consolidation (`assertFresh`), a Qwik type smoke + stronger
+  class-recipe wiring test, the APCA advisory widened to the accent text across
+  the core palette and every colorway (still advisory; WCAG 2.1 AA stays the
+  hard gate), an OLED computed-style smoke test, and several doc reconciliations.
+- New `demos.spec` e2e sweep runs the console-error / uncaught-exception /
+  failed-response guards **and** an axe scan over every per-feature demo page
+  (annotations, legends, marks, connectors, spotlight, crosshair, selection,
+  report) in both themes and cross-browser — previously only `/demo/` was
+  guarded, so a throw or 404 on those SVG-heavy pages could not fail CI.
+- The `check:dist` payload ceiling was raised to 80 kB raw / 14.5 kB gzip (from
+  78 kB / 13.5 kB). The default bundle was sitting ~21 bytes under the old gzip
+  gate — the analytical primitives are opt-in leaves and stay out of it, so this
+  is residual prior growth; the bump restores a real ~3% raw / ~7% gzip margin
+  so an ordinary token addition no longer trips an unrelated PR.
+
 ## 0.4.1 — 2026-06-01
 
 Patch hardening for the public framework surface, plus the first step of the
@@ -79,6 +304,9 @@ modern-platform motion direction (see [ADR-0002](docs/adr/0002-scope-and-2026-ba
 - **[ADR-0003](docs/adr/0003-theme-model.md)** records the theme model: a binary
   light/dark base × one-knob derivation × orthogonal axes (colorway, surface,
   contrast, density), and why a flat named-theme catalog is rejected.
+- React and Solid Vite examples, CI/release matrix coverage for those examples,
+  runtime binding tests, public API stability docs, a release runbook, and
+  `npm run size:report`.
 
 ### Changed
 
@@ -117,12 +345,6 @@ modern-platform motion direction (see [ADR-0002](docs/adr/0002-scope-and-2026-ba
   and the OKLCH accent ramp uses an explicit white/black neutral endpoint for
   cross-engine browser parity.
 
-### Added
-
-- React and Solid Vite examples, CI/release matrix coverage for those examples,
-  runtime binding tests, public API stability docs, a release runbook, and
-  `npm run size:report`.
-
 ## 0.4.0 — 2026-05-31
 
 The color-system release — [ADR-0001](docs/adr/0001-color-system.md) steps 1–8.

package/MIGRATIONS.json

@@ -0,0 +1,92 @@
+{
+  "$comment": "Machine-readable rename/removal map for @ponchia/ui upgrades (classes, attributes, and tokens). Generated-by-hand from CHANGELOG BREAKING sections; consumed by docs/migrations/*.md and any codemod/sed recipe. 'safe' rules are mechanically rewritable (whole-token, no semantic change); 'manual' rules need human judgement (concept moved or removed, not a 1:1 rename).",
+  "migrations": [
+    {
+      "from": "0.2",
+      "to": "0.3",
+      "summary": "Entire non-ui-* legacy vocabulary removed; everything is now under the .ui-* contract and the check-classes drift gate.",
+      "safe": [
+        { "old": "skip-link", "new": "ui-skiplink" },
+        { "old": "site-nav", "new": "ui-sitenav" },
+        { "old": "site-menu", "new": "ui-sitemenu" },
+        { "old": "theme-toggle", "new": "ui-themetoggle", "prefix": true },
+        { "old": "app-shell", "new": "ui-app-shell", "prefix": true },
+        { "old": "app-rail", "new": "ui-app-rail", "prefix": true },
+        { "old": "app-topbar", "new": "ui-app-topbar", "prefix": true },
+        { "old": "app-toolbar", "new": "ui-app-toolbar", "prefix": true },
+        { "old": "app-nav", "new": "ui-app-nav", "prefix": true },
+        { "old": "app-panel", "new": "ui-app-panel", "prefix": true },
+        { "old": "app-content", "new": "ui-app-content", "prefix": true },
+        { "old": "app-main", "new": "ui-app-main", "prefix": true },
+        { "old": "app-metrics", "new": "ui-app-metrics", "prefix": true },
+        { "old": "app-metric", "new": "ui-app-metric", "prefix": true },
+        { "old": "app-empty-state", "new": "ui-app-empty-state", "prefix": true }
+      ],
+      "manual": [
+        {
+          "old": "hero / project-* / post-card / essay-* / page-* / home-* / signal-panel / worklog-summary",
+          "new": "the ui-* content layer",
+          "note": "Long-form content: .ui-prose / .ui-quote. Cards: .ui-card. Layout: .ui-grid / .ui-stack. Site chrome: the ui-site* shell. No 1:1 mapping — re-compose with the content primitives."
+        },
+        {
+          "old": "callout",
+          "new": "ui-alert",
+          "note": "Tone modifiers differ (.ui-alert--info/-success/-warning/-danger); re-pick the tone."
+        },
+        {
+          "old": "metric-tile",
+          "new": "ui-app-metric",
+          "note": "Now scoped to the admin shell vocabulary; standalone stat usage should wrap in .ui-app-metrics."
+        },
+        {
+          "old": "tag-list / tag",
+          "new": "ui-tags / ui-tag",
+          "note": "Compact variant .tag-list--compact → .ui-tags--compact; verify accent-on-accent contrast (see CHANGELOG 0.3.0 a11y fix)."
+        }
+      ],
+      "codemod": "See docs/migrations/0.2-to-0.3.md for a ready-to-run ripgrep+sed recipe covering the 'safe' rules."
+    },
+    {
+      "from": "0.3",
+      "to": "0.4",
+      "summary": "Additive colour-system release (ADR-0001); the default dist/bronto.css renders identically. No class or attribute renames. One orphan token pair removed.",
+      "safe": [],
+      "manual": [
+        {
+          "old": "--orange / --orange-soft",
+          "new": "(removed — re-declare in a consumer :root override if referenced)",
+          "note": "Orphan token pair: defined in the token mirrors but referenced by no shipped component and documented nowhere, and untiered under the new colour model. Removed under the CONTRIBUTING 'provably-unreferenced surface' exception. If you used it: :root { --orange: #a85f32; --orange-soft: rgb(168 95 50 / 0.13); }"
+        }
+      ],
+      "codemod": "No class codemod needed (no renames). See docs/migrations/0.3-to-0.4.md; audit usage with: rg -- '--orange' ."
+    },
+    {
+      "from": "0.4",
+      "to": "0.5",
+      "summary": "Adds the analytical-primitives suite (annotations, legend, marks, connectors, spotlight, crosshair, selection + the analytical.css roll-up); all additive/opt-in. Three breaking changes: the chart data key moved out of the report kit into the standalone Legends layer (`.ui-chart__legend`/`.ui-chart__swatch` removed); annotation arrowheads now render via the shared connectors geometry kernel (a small visual path change, no API change); and the marks/bracket-note rationed-accent tone was renamed `evidence`→`accent` to match the annotation/connector tone vocabulary (`.ui-annotation--evidence` stays — it's a marker variant, not a tone).",
+      "safe": [
+        { "old": "ui-chart__swatch", "new": "ui-legend__swatch" },
+        { "old": "ui-mark--evidence", "new": "ui-mark--accent" },
+        { "old": "ui-bracket-note--evidence", "new": "ui-bracket-note--accent" }
+      ],
+      "manual": [
+        {
+          "old": "ui.mark({ tone: 'evidence' }) / ui.bracketNote({ tone: 'evidence' })",
+          "new": "tone: 'accent'",
+          "note": "The rationed-accent tone option on the mark/bracket-note recipes is now 'accent' (was 'evidence'), matching ui.connector/ui.annotation. Do NOT rewrite ui.annotation({ variant: 'evidence' }) or the 'evidence' subject marker — those are a marker shape, not a tone, and are unchanged."
+        },
+        {
+          "old": "ui-chart__legend",
+          "new": "ui-legend",
+          "note": "Also import '@ponchia/ui/css/legend.css' beside report.css, and wrap each entry's content as <li class=\"ui-legend__item\"> … <span class=\"ui-legend__label\">…</span>. The swatch's --chart-color/--chart-pattern inline contract is unchanged; the categorical --chart-N colour is also available via .ui-legend__swatch--N. See docs/legends.md."
+        },
+        {
+          "old": "connectorEndArrow (annotations)",
+          "new": "connectorEndArrow (unchanged API)",
+          "note": "No code change needed. The function signature is identical; only the rendered arrowhead path differs slightly now that it shares the connectors geometry kernel. Re-baseline any exact-path SVG snapshot tests of annotation arrowheads."
+        }
+      ],
+      "codemod": "rg -l 'ui-chart__legend|ui-chart__swatch' then s/ui-chart__swatch/ui-legend__swatch/g and rework the ul.ui-chart__legend wrapper into ul.ui-legend with li.ui-legend__item rows. See docs/legends.md."
+    }
+  ]
+}

package/README.md

@@ -3,12 +3,12 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~75kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~76kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first, framework-agnostic UI framework built on token-driven restraint — monochrome by default, one rationed accent, dot-matrix display type, hairline borders. Color is _tiered_: we don't decorate with it, we signal with it. The "Nothing"-inspired look is the default skin, not the architecture — opt-in colorways (amber CRT · phosphor green · e-ink), a dot-matrix icon set, and a colourblind-safe data-viz palette prove the one knob is real. Zero runtime dependencies; re-brand the whole thing with one CSS variable.**
+**A CSS-first design system for interfaces that explain themselves.** Works in plain HTML, every modern framework, and print/PDF — there's no component runtime to adopt. The look is a deliberate stance: a neutral monochrome canvas with **one _rationed_ accent** (colour _signals_, it never decorates), dot-matrix display type and hairline borders, re-skinnable from a single `--accent` knob (opt-in amber-CRT · phosphor-green · e-ink colorways). And beyond the standard component set it ships an opt-in **analytical & report layer** — SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text marks, a colourblind-safe data-viz palette and a static/PDF report grammar — for dashboards and LLM-authored reports. Zero runtime dependencies; re-brand the whole thing with one CSS variable.
 
 ### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
@@ -20,6 +20,8 @@ The demo is the kitchen sink — every component, light/dark, RTL, live theming.
 
 `@ponchia/ui` ships its design as **CSS**, not components. You drop in one stylesheet and style with semantic `ui-*` classes; an optional thin layer of typed class-name recipes and SSR-safe vanilla behaviors sits on top for the few things that genuinely need JS (theme persistence, dialogs, toasts, disclosure). The guiding principle is **color is rationed, structure carries meaning** — layout, type weight and the hairline do the work before a hue does, and the accent is a spotlight, not a paint bucket. Because everything lives in a single `@layer bronto`, your own un-layered CSS overrides the framework with no specificity fight and no `!important`.
 
+It ships a complete, accessible **standard component set** — but that's not where it competes. Its differentiator is an opt-in **analytical & communication layer** for interfaces that make complex work legible: annotations, legends, connectors, marks, a guided-focus spotlight, lifecycle/system-state and source-provenance vocabularies, and a static/PDF report grammar. Each owns only its visual grammar and pure geometry — no chart engine, no state, no hit-testing. See **[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)** for the thesis.
+
 ## Install
 
 ```bash
@@ -34,7 +36,7 @@ Or drop it in with no build step, straight from a CDN:
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~75 kB raw / ~13 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~76 kB raw / ~13 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -100,6 +102,7 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
 - **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
 - **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, sections, findings, evidence, figures, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
 - **Glyphs** — `@ponchia/ui/glyphs`, a 48-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
@@ -117,7 +120,7 @@ Everything accent-colored derives from a single `--accent` variable via `color-m
 .promo  { --accent: #16a34a; }   /* …or just this section green */
 ```
 
-Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the "Nothing" look is the **default skin, not the architecture**.
+Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the default monochrome look is **one skin, not the architecture**.
 
 **One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
 
@@ -165,7 +168,7 @@ Recent-evergreen, by design. The framework targets the modern web platform — c
 
 ## Versioning
 
-Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.4.0` (and equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
+Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.5.0` (and equivalently `^0.5.0`) resolves to `>=0.5.0 <0.6.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
 
 Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the full public-surface matrix.
 
@@ -181,4 +184,4 @@ Release candidates publish to the `next` dist-tag, never to `latest` — opt in
 
 [MIT](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE) © Ponchia.
 
-The bundled **Doto** font (`fonts/*.ttf`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.
+The bundled **Doto** font (`fonts/*.woff2`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.