@ponchia/ui 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,9 +1,556 @@
 # 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.6.0 — 2026-06-03
+
+Accumulates the post-0.5.0 work: a multi-agent audit pass (accessibility
+hardening, a behavior/binding scope-safety fix, codegen/gate tightening) plus a
+**breaking** charting realignment. The local static-bar renderer
+(`.ui-chart*`) is **removed** — a chart needs scales + data binding, which the
+analytical layer refuses to own. In its place, bronto becomes a themeable target
+for **Vega-Lite** (`@ponchia/ui/vega`), the same tokens-as-data path as Mermaid
+and D2. The data-viz **palette** (`--chart-*`, `tokens/charts.json`) and the
+**legend** layer are unchanged. Pin `~0.5` → re-pin `~0.6`; see
+[`MIGRATIONS.json`](./MIGRATIONS.json) (`0.5`→`0.6`).
+
+### Added
+
+- **`@ponchia/ui/vega`** (+ `vega.json`) — an on-brand Vega-Lite / Vega
+  [`config`](https://vega.github.io/vega-lite/docs/config.html) resolved per
+  theme (the idiomatic `vega-themes` shape): monochrome chrome + one rationed
+  accent, `range.category/ordinal/ramp/heatmap/diverging` from the CVD-safe
+  data-viz palette. `brontoVegaConfig(theme)`. Resolved hex (Vega bakes colours
+  into SVG/canvas, can't read `var()`); gated structurally **and** by a headless
+  render-probe that asserts the colours land on a rendered chart. Vega is the
+  consumer's renderer — config only, not a dependency. See `docs/vega.md`.
+- **`ui-delta`** — a standalone trend/change indicator (core primitive): an
+  arrow glyph (the non-colour channel) plus the figure, with
+  `--up`/`--down`/`--flat`, and `--invert` to swap only the tone when "up" is
+  the bad direction (latency, error rate, cost). `ui.delta({ dir, invert })`.
+- **`ui-compare`** — a fluid side-by-side / before-after layout for the report
+  layer (`css/report.css`): `__col`, `__head`, and `--2up`.
+  `ui.compare({ cols })`.
+- **`@ponchia/ui/classes.json`** — the class vocabulary as language-neutral
+  data (`groups`/`classes`/`states`/`customProperties`), so a non-JS/non-TS
+  host or an external linter can validate emitted markup without executing the
+  ESM `cls` map or parsing the `.d.ts`. Generated from `cls`; drift-checked and
+  its `states`/`customProperties` gated against the stylesheet.
+- **`tokens/resolved.json` `scale` block** — the resolved non-colour scales
+  (spacing/radius/type/z/motion, `var()` chains flattened), completing the
+  token contract for non-CSS hosts (previously colour-only).
+- **`--display-weight` / `--display-weight-strong`** (700 / 800) — the weight of
+  the Doto dot-matrix display face, now a token. Themes/skins can re-tune how
+  heavy display text renders in one place.
+- On-brand **Mermaid** (`@ponchia/ui/mermaid`, `mermaid.json`) and **D2**
+  (`@ponchia/ui/d2`, `d2.json`) theme maps — resolved per-theme palettes
+  projected from the same tokens, gated. Diagrams stay the consumer's renderer;
+  these are config only.
+- Annotation geometry options: `connectorElbow({ mid })` (turn position along the
+  dominant axis), `notePlacement({ inset })` (reserve the title stroke-halo so a
+  placement that "fits" doesn't clip), and a `spread` half-angle on both
+  `connectorEndArrow` and the shared `arrowHead` kernel.
+- **`brontoVegaAccent(theme)` / `brontoVegaNeutral(theme)`** (`@ponchia/ui/vega`)
+  — the exact per-theme hexes for `range.category`'s accent (series 1) and
+  neutral (last series), so spending the accent on one emphasised mark needs no
+  palette-index reverse-engineering.
+- **`--on-accent`** token — the readable ink for a label on **any accent fill**
+  (button, badge, themed chart bar, a Vega/D2 node). Resolves to `--button-text`
+  (white on the light accent, black on the dark) and is gated ≥ 4.5:1 in
+  `docs/contrast.md`. Use it instead of `--accent-text`, which is the inverse
+  (accent-coloured text for a *neutral* background, ~1.3:1 on an accent fill).
+- **`.ui-src`** standalone trust pill (`cls.src`, `css/sources.css`) — wears a
+  `.ui-src--*` tone (verified / reviewed / generated / unverified / stale /
+  conflict) on its own, for a bare trust label outside a citation or source card.
+  Previously the `.ui-src--*` modifiers only painted a `--src-tone` with no
+  standalone host, so a lone pill validated against `classes.json` yet rendered
+  nothing.
+
+### Removed
+
+- **BREAKING: the local static bar-chart renderer (`.ui-chart`, `.ui-chart__plot`,
+  `__bar`, `__label`, `__track`, `__fill`, `__fallback`, `__caption`).** A chart
+  needs scales and data binding — out of scope for a CSS-first analytical layer
+  (ADR-0002). Replace with a Vega-Lite chart themed via `@ponchia/ui/vega`, or a
+  hand-authored token-themed inline `<svg>`, inside a `.ui-report__figure` with a
+  `.ui-report__caption` and a `.ui-legend` key. The `--chart-value` inline knob
+  is gone; the `--chart-color`/`--chart-pattern` swatch knobs remain (legend).
+  See `MIGRATIONS.json` (`0.5`→`0.6`) and `docs/vega.md`.
+
+### Changed
+
+- **Annotation connectors are crisper.** `connectorEndArrow` now defaults to a
+  sharper head (half-angle 0.32 ≈ 37°, size 8 vs the former blunt 0.45 / 7).
+  Author-facing geometry only; the `arrowHead` kernel default is unchanged, so
+  node-connector arrowheads don't move.
+
+### Accessibility
+
+- **Coarse-pointer tap-target floors extended to navigation.** The 2.9 rem
+  touch floor (already on primitives/forms/feedback) now also covers
+  `.ui-sitenav a`, `.ui-app-nav a`, `.ui-sitemenu > summary`, and
+  `.ui-themetoggle__button` under `@media (pointer: coarse)` — the primary nav
+  affordances were below the 44 px target on touch.
+- **App shell uses dynamic viewport units.** `100vh` → `100dvh` (shell/body) and
+  the scrolling rail → `100svh`, so the rail and its pinned account/footer no
+  longer fall under the mobile URL bar.
+- **Forced-colors status dots stay distinct.** `.ui-dot--success/--warning/--danger/--info`
+  and `.ui-dotmatrix__cell--hot/--accent` now map to distinct system colors
+  under Windows High Contrast instead of collapsing to one — the only signal
+  these carry is colour.
+- **Keyboard affordance parity.** `.ui-menu__item:focus-visible` gets the same
+  row highlight as hover; the segmented control's focus ring is now inset so the
+  container's `overflow: hidden` no longer clips it.
+- **Reduced-motion skeleton.** `.ui-skeleton` flattens to a solid placeholder
+  under `prefers-reduced-motion` instead of freezing mid-shimmer.
+
+### Fixed
+
+- **Published-type drift (code-quality audit).** `ui.meter({ tone: 'info' })` and
+  `ui.bracketNote({ tone: 'success' })` emit real classes at runtime, but the
+  generated `.d.ts` tone unions (hand-mirrored in `gen-dts.mjs`) omitted them, so
+  a TS consumer got a spurious type error for a value that renders. The unions
+  now match the factory; a new `check:recipe-types` gate cross-checks every
+  factory's string-literal options against its `*Opts` union so this whole class
+  of drift fails CI.
+- **Component-library audit (16-agent dogfood pass) — the validates-but-no-ops
+  cluster.** A whole-surface audit found the meter-style trap (a class/token that
+  validates and paints but silently does nothing without an undocumented
+  precondition) recurring across components. Fixed:
+  - `aria-disabled="true"` on `.ui-button` / `.ui-link` now sets
+    `pointer-events: none` — it looked dead but a real `<a>` still navigated.
+  - Disabled affordance reaches the controls that wrap a native input
+    (`.ui-switch` / `.ui-check` / `.ui-segmented__option` via `:has(input:disabled)`,
+    plus `.ui-range` / `.ui-file`) — they previously looked operable and their
+    label kept `cursor: pointer`.
+  - Bare `[aria-current]` selectors (`.ui-sitenav`, `.ui-breadcrumb__item`) now
+    scope `:not([aria-current='false'])`, so a correctly-authored
+    `aria-current="false"` link is no longer styled as current.
+  - The active-tab forced-colors re-assert moved from `base.css` to
+    `disclosure.css` (after the default rule) — an earlier bundle leaf let the
+    accent default override it, so the selected tab lost its only HC cue.
+  - `.ui-meter__fill` / `.ui-progress__bar` get a system colour under
+    `forced-colors`, so the measured proportion stays visible.
+  - `.ui-search` gains a 2px keyboard focus ring to match every sibling input
+    (it had only a 1px border-colour shift).
+  - `.ui-prose` gets `overflow-wrap: break-word` — long tokens in
+    machine-generated Markdown forced horizontal page scroll.
+  - `.ui-mark--draw` is scoped to fill styles (`:not(--underline, --box, --strike)`)
+    so it no longer looks applied while doing nothing.
+  - `.ui-cq` hardcodes its container-name (the `@container bronto` collapse
+    queries hardcode it, so a `--cq-name` override silently killed the collapse).
+  - `initPopover()` seeds resting ARIA (`aria-haspopup`, `aria-controls`,
+    `aria-expanded`) and syncs `aria-expanded` when the UA closes a native
+    popover; `toast()` validates `tone` (an unknown string rendered an unstyled
+    neutral toast) and warns; the combobox listbox gets an accessible name.
+  - `.ui-error-summary__title` uses the legible sans, not the low-legibility Doto
+    display face. `.ui-input` / `.ui-search` autofill stays on-theme.
+  - `.ui-reveal` hidden state is gated on `scripting: enabled` (genuinely degrades
+    visible with no JS; the prior comment lied) — and `ui-scroll-reveal` is the
+    documented zero-JS path.
+  - Parity modifiers added: `.ui-meter--info`, `.ui-bracket-note--success`.
+- Responsive/mobile hardening across the framework: `rem`-rooted type for WCAG
+  1.4.4, coarse-pointer tap-target floors, combobox/tour-note viewport clamps,
+  and `@media (hover)` gating — with a new responsive e2e sweep.
+- **Faint numbers on stat cards.** `.ui-stat__value` / `.ui-app-metric__value`
+  (and the report cover/section titles, rail brand, panel titles, `.ui-display`,
+  `.ui-quote`) set the Doto display face but no weight, so they rendered at the
+  thinnest cut (400). They now apply `--display-weight(-strong)` — visibly bolder
+  and more legible, on screen and in print.
+- **Painted data surfaces dropped in the PDF.** Headless-Chromium print drops
+  backgrounds by default, silently blanking the data-bearing fills. Dot-matrix
+  cells, the segmented meter, status dots, masked glyphs, highlight marks,
+  connector lines, and progress/meter fills now carry `print-color-adjust: exact`
+  so they survive the A4 print/PDF that the report kit targets.
+- **Dark-theme cards/tables printed dark-on-white.** The dark→ink token remap was
+  scoped to `.ui-report`; it is now lifted to the print `:root` (in the exempt
+  token-definition file), so a bare `.ui-card` / `.ui-statgrid` / `.ui-table` —
+  the markup an external LLM emits — also prints legibly.
+- Inline `ui-citation` no longer dumps its full URL mid-sentence when printed
+  (the reference list carries the URL); `ui-legend--with-values` values are
+  right-aligned for a clean tabular column.
+- **Annotation elbow connector was a 45° chamfer, not a dogleg.**
+  `connectorElbow` turned by `min(|dx|,|dy|)`, drawing a diagonal stub the
+  `stroke-linejoin` bevel never matched. It now delegates to the connectors
+  geometry kernel's right-angle `elbowPath` (H/V/H), so an annotation leader and
+  a node connector draw the same elbow.
+- **Scoped behaviors no longer hijack the whole document on a null root.**
+  `init*({ root })` with an explicitly-provided-but-unready root (a framework
+  ref still `null` at mount, a conditional that hasn't rendered) now no-ops
+  instead of silently widening to document-wide delegation. The react/solid/qwik
+  bindings emit `root: null` for the not-ready case so the distinction survives
+  the boundary; passing no `root` still delegates from `document` exactly as
+  before. Affects every delegated behavior (dialog, menu, combobox, …).
+- **`--report-width` / `--report-padding-block` are now declared defaults** on
+  `.ui-report` — they were read with inline fallbacks but never declared, so the
+  override surface was undiscoverable and `--report-measure` looked like the
+  width knob when it isn't.
+- Carousel's IntersectionObserver is now set up and torn down in lockstep with
+  its event binding, removing a one-tick window where a re-init left two
+  observers on the same slides.
+- **`ui-meter` / `ui-progress` fill painted a 0×0 box.** `.ui-meter__fill` and
+  `.ui-progress__bar` set `block-size`/`inline-size` but no `display`, so on the
+  documented `<span>` fill (an inline box ignores width/height) the bar rendered
+  empty — a "validates-but-renders-nothing" trap the registry and docs both
+  hid. They are now `display: block`. Found by a second multi-agent dogfood
+  pass; guarded going forward by a render-geometry e2e (below).
+
+### Documentation
+
+- LLM-authored static reports: a prominent CSS-loading note (bundler vs
+  `node_modules` vs CDN) and a copy-pasteable CDN report in
+  `docs/reporting.md`; clarified that `dist/bronto.css` does **not** include the
+  opt-in report/chart/legend/annotation layers; number/date formatting
+  guidance; and a standalone, no-build report reference
+  (`demo/report-standalone.html`).
+- Resolved the `is-*` self-contradiction: the framework's own
+  `is-num`/`is-pos`/`is-neg`/`is-key`/`is-open` state hooks are valid even
+  though they deliberately live outside `cls` (documented in
+  `docs/reference.md` and `classes.json`).
+- Clarified two standing contracts in `docs/architecture.md`: `css/analytical.css`
+  is the roll-up of exactly the seven figure leaves (annotations, legend, marks,
+  connectors, spotlight, crosshair, selection) — `sources`/`state`/`generated`/
+  `workbench`/`command` are adjacent leaves imported individually — and the root
+  `.` export is CSS-only (no runtime JS at the root). Pre-1.0 stability/pinning
+  spelled out in `docs/stability.md`. `docs/workbench.md` notes that
+  `.ui-selectionbar` is unrelated to the `.ui-sel--*` selection-emphasis classes.
+- Honest JSDoc limits: combobox/command read options from the DOM at init
+  (re-run after replacing them); popover restores focus on Escape but not on
+  outside-click; the table sorter is locale-naive display-text; mask-mode glyphs
+  are single-tone.
+- **Foreign-renderer recipes hardened after a multi-agent dogfooding pass**
+  (build five real reports across the whole stack, review from every POV). The
+  Vega CDN recipe now pins the `/build/*.min.js` UMD bundles and `renderer:'svg'`
+  (a bare `cdn.jsdelivr.net/npm/vega@6` tag has no `window.vega`, so the previous
+  recipe rendered nothing); the file://-portable path (inline the config — an
+  imported/fetched config is CORS-blocked from disk) is now explicit. New
+  `docs/reporting.md` recipes: "Theming a live report" (the theme-toggle/re-embed
+  foot-guns — clear the host, container-width-while-hidden, Mermaid source vs
+  output), live charts are `ui-screen-only` while the table prints (a kept live
+  chart bakes the on-screen theme), `ui-meter`/`ui-quote` markup, and the
+  sequential/diverging frozen-figure ramp. `docs/d2.md` gains a frozen
+  inline-`<svg>`-from-slots recipe and on-accent-ink guidance; `docs/vega.md`
+  documents the theme-inverting ramp and the OKLCH-vs-d3 gradient-key drift.
+- `docs/annotations.md` states the rule in both directions: a data annotation
+  must stay readable (not `aria-hidden`), a decorative one must be hidden.
+- **A second dogfood pass closed the foreign-renderer/contract gaps it found.**
+  `docs/sources.md` + `llms.txt` now document the standalone `.ui-src` trust
+  pill and state that a `ui-src--*` tone class **needs a host** (a bare
+  `<span class="ui-src--verified">` validates but renders nothing), and name the
+  source-card body part as `__excerpt` (not `__detail`). `docs/mermaid.md`:
+  `gantt`/`timeline` are **not** covered by the base `themeVariables` (they
+  render with Mermaid's own defaults — prefer the native `ui-timeline` for a
+  report). `docs/mermaid.md` + `docs/d2.md` gain the same `file://` CORS caveat
+  Vega carries (inline the map or pre-render). `docs/vega.md`: select the themed
+  ramp with `scale: { range: 'heatmap' }` — **not** `scheme:`, which throws — and
+  the accent/neutral series map to `--chart-1` / `--chart-8`, so a legend keys
+  them with `ui-legend__swatch--1`/`--8` (`docs/legends.md`). `docs/reporting.md`:
+  the live-theme recipe now `finalize()`s the prior Vega view before re-embed
+  (was leaking a view per toggle), and notes `ui-meter --value` clamps at 100
+  (put an over-target figure in the written label). `docs/marks.md`: `ui-mark`
+  is a behind-text highlight (contrast-safe; never needs `--on-accent`).
+
+### Internal
+
+- **New `check:versions` gate** — every `@ponchia/ui@X.Y.Z` literal in a shipped
+  doc (`llms.txt`, `docs/reporting.md`, …) must equal `package.json`, so a stale
+  CDN pin can't ship to LLM/copy-paste consumers on the next bump.
+- **Dev-dependency Vega bumped to the v6 stack** — the render-probe now runs on
+  `vega@^6.2.0` + `vega-lite@^6.4.3` (Vega-Lite 6 peers Vega 6; a Vega-Lite-6 ÷
+  Vega-5 mix is incoherent). The theme `config` is version-independent resolved
+  hex, so the artifacts and the probe assertions are unchanged; the documented
+  CDN recipe is re-pinned to the matching majors (`vega@6.2.0` / `vega-lite@6.4.3`
+  / `vega-embed@7.1.0`, all still shipping a UMD `/build/*.min.js`). Vega remains
+  the consumer's renderer, not a runtime dependency.
+- **New `check:doc-recipes` gate** — a `<script src>` CDN recipe in a shipped doc
+  must pin a jsDelivr `/build/*.min.js` UMD bundle, never a bare
+  `cdn.jsdelivr.net/npm/<pkg>@N` redirect (which serves a module bundle with no
+  global and renders nothing). Docs are otherwise an untested surface; this is
+  the structural guard that closes the broken-recipe class the dogfood pass
+  found. `<link href>` CSS and prose mentions are exempt.
+- **`classes.json` `customProperties` expanded** to cover the load-bearing,
+  no-op-without-it knobs the audit found undocumented: the **required**
+  `--icon-mask` (a bare `.ui-icon` paints a solid square without it) and
+  `--ui-vt-name` (`.ui-vt` is inert without it), plus `--icon-size`. The
+  `states` manifest comment now explicitly names the runtime-managed hooks it
+  deliberately excludes (`is-leaving`/`is-visible`/`is-in`/`is-on`) so the
+  omission reads as intentional, not a gap. `--on-accent` is annotated at its
+  token source as a read-only export for foreign renderers (in-DOM ink is
+  `--button-text`). `contrast.md` now prints APCA `Lc` to one decimal so an
+  advisory shortfall (e.g. `Lc 44.9`) no longer rounds to a passing-looking `45`.
+- Raw bundle budget 81 → 82 kB for the component-audit accessibility/state
+  blocks (gzip held ~14.1 kB — the additions are repetitive media-query and
+  `:has()`/`:not()` rules that compress well).
+- **Code-quality audit (16-agent) — two new gates + targeted dedup, no churn.**
+  A code-health pass (complexity / duplication / AI-slop / missing-best-practice)
+  that deliberately left working, gate-protected code alone. Added:
+  `check:recipe-types` (factory↔`.d.ts` option parity, above) and `check:chain`
+  (every `check:*` script is wired into the aggregate `check` chain — closes the
+  silent-coverage-drop class; it would have caught a forgotten gate). Reconciled
+  a latent bug — `clamp()` had silently diverged between `connectors` and
+  `annotations`; the two now share one scalar/geometry kernel (the guarded form).
+  Dedup that removed real duplication: a shared `collectHosts()` /
+  `scrollIntoViewSafe()` / `wrapIndex()` in `behaviors/internal.js` (~9 behaviors),
+  a `freshnessErrors()` helper reused by 7 drift gates, the shared `CSS_COLOR`
+  regex across the 3 foreign-renderer gates, `check-report`'s opt-in list as a
+  loop, `check-pack`'s shipped-docs derived from `pkg.files`, and a looser
+  `check-classes` recipe-scrape. README hero de-densified; `srcTone` matched to
+  `stateTone`'s idiom; the intentional badge accent-mix (45% vs 40%) documented.
+- **`check:dist` now asserts source-coverage** — every `css/*.css` leaf must be
+  bundled, an opt-in `EXTRA_LEAVES` entry, or a roll-up; an orphaned leaf that
+  would ship nothing now fails loudly (the inverse of the existing stale-dist
+  guard).
+- **`check:dts-emit` now compares `.d.ts.map`** mapping data (volatile `sources`
+  path normalized), closing a drift hole the code comment had acknowledged.
+- DTCG export types `--display-weight*` as the spec `fontWeight` type (was
+  `number`). Corrected stale `check-tokens.mjs` doc references (the real gate is
+  `check:fresh`).
+- Tests: binding hook-surface parity is now **derived** from the modules (the old
+  hard-coded list silently omitted the five analytical hooks); a new
+  `analytical-boundary` test makes the "no scales/state/fetch/global-hotkey"
+  contract executable; a new behavior test pins the null-root no-op.
+- Removed four dead keyframes (`scan`/`growBar`/`drawLine`/`pulseNode`) from
+  `motion.css`. Raw bundle budget 80 → 81 kB for the accessibility blocks (gzip
+  held ~14.0 kB).
+- **`classes.json` `--value` retargeted** to `.ui-meter__fill, .ui-progress__bar`
+  (was the `.ui-meter, .ui-progress` track parent) — the custom property is read
+  on the fill child, so the machine-readable manifest now matches where an author
+  actually sets it.
+- **New render-geometry e2e** (`test/e2e/render-geometry.spec.mjs`) — launches a
+  browser at the demo's real report primitives and asserts the `.ui-meter__fill`
+  / `.ui-progress__bar` fills and the standalone `.ui-src` pill paint a non-zero
+  box (via `getBoundingClientRect`, not the inline-box-lying
+  `getComputedStyle().inlineSize`). Closes the validates-but-renders-nothing
+  category that hid the meter regression. The demo gains a standalone `.ui-src`
+  pill row to exercise it.
+
+## 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 +626,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 +667,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.