@ponchia/ui 0.4.0 → 0.5.0

package/docs/state.md

@@ -0,0 +1,85 @@
+# Lifecycle & system state
+
+`@ponchia/ui/css/state.css` is an opt-in vocabulary for the states real apps
+spend their time in — saving, saved, queued, offline, stale, conflicted, locked,
+reviewed. These are usually improvised per product, so even good apps feel
+inconsistent. This is the canonical set: a labelled state object with a rationed
+tone, plus a page/document sync bar.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/state.css';
+```
+
+Bronto ships the visual states and the canonical wording. The host owns the
+state machine, retry policy, persistence, and announcements. **Persistent state
+deserves persistent UI** — a toast is secondary, not the answer. The tone is a
+second channel; the **label is the state**, so it survives forced-colors and
+screen readers (WCAG 1.4.1).
+
+## `.ui-state`
+
+A leading tone dot, a `__label`, and an optional `__detail`. Add `--busy` to
+pulse the indicator for an in-progress state (reduced-motion-safe).
+
+```html
+<span class="ui-state ui-state--saving ui-state--busy">
+  <span class="ui-state__label">Saving…</span>
+</span>
+
+<span class="ui-state ui-state--saved">
+  <span class="ui-state__label">Saved</span>
+  <span class="ui-state__detail">2m ago</span>
+</span>
+```
+
+## State matrix
+
+Use the canonical label; the modifier bakes in the tone.
+
+| State | Class | Canonical label | Tone | Busy? |
+| --- | --- | --- | --- | --- |
+| Saving | `ui-state--saving` | "Saving…" | accent | yes |
+| Saved | `ui-state--saved` | "Saved" / "All changes saved" | success | — |
+| Queued | `ui-state--queued` | "Queued" / "Pending" | muted | — |
+| Offline | `ui-state--offline` | "Offline" | warning | — |
+| Stale | `ui-state--stale` | "Out of date" | warning | — |
+| Conflict | `ui-state--conflict` | "Conflict" | danger | — |
+| Error | `ui-state--error` | "Failed" / "Couldn't save" | danger | — |
+| Locked | `ui-state--locked` | "Locked" / "Read-only" | muted | — |
+| Reviewed | `ui-state--reviewed` | "Reviewed" | success | — |
+| Needs review | `ui-state--needs-review` | "Needs review" | warning | — |
+
+"Syncing" and "Retrying" are the saving tone with their own label — use
+`ui-state--saving ui-state--busy` and write the word.
+
+## `.ui-syncbar`
+
+A page- or document-level status strip: a state on one side, optional actions on
+the other.
+
+```html
+<div class="ui-syncbar">
+  <span class="ui-state ui-state--saved">
+    <span class="ui-state__label">All changes saved</span>
+    <span class="ui-state__detail">just now</span>
+  </span>
+  <button class="ui-button ui-button--subtle ui-button--sm" type="button">View history</button>
+</div>
+```
+
+## Recipe
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
+ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
+```
+
+## Scope
+
+CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago") or live
+progress text is the host's job; a small optional behavior may come later if a
+real consumer needs it. Background-job progress and conflict-resolution
+affordances are deliberately deferred until then.

package/docs/theming.md

@@ -4,13 +4,15 @@
 This is the **stable, supported surface** for re-branding without forking.
 Anything not listed here is internal and may change between minor versions.
 
-## The one knob: `--accent`
+## The brand knob: `--accent`
 
-The whole accent family derives from `--accent` via `color-mix()`:
+The accent family derives from `--accent` via `color-mix()` and the
+theme-owned neutral ramp endpoint:
 
 | Token                 | Derivation (light / dark)                    | Role |
 | --------------------- | -------------------------------------------- | ---- |
 | `--accent-strong`     | `--accent` mixed 83% with black / 84% white  | darker/lighter accent for hover, emphasis |
+| `--accent-ramp-end`   | white / black                                | neutral endpoint for the low-chroma OKLCH ramp |
 | `--accent-text`       | `var(--accent-strong)` (alias)               | **accent used as foreground text** — the on-surface, AA-safe one |
 | `--accent-soft`       | `--accent` at 10% / 14% over transparent     | tinted fills |
 | `--bg-accent`         | `--accent` at 6% / 8%                         | faint accent backgrounds |
@@ -49,6 +51,14 @@ fills — follows automatically, in both light and dark.
 - **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
   preset: `data-density="compact"` / `data-density="comfortable"` on any
   element (defaults to the middle scale).
+- **Dark surface** — the dark theme's base is a deliberately *elevated*
+  near-black (`--bg: #121212`) for readability: pure black + bright text
+  causes halation, and near-black-on-black surface steps are imperceptible.
+  For OLED power-saving or the original true-black "Nothing" look, opt in with
+  `data-surface="oled"` on `:root` (a root-level attribute like `data-theme`).
+  It only affects the dark theme and is a CSS-only preset (not in the JS token
+  model), so it never blacks out the light theme. See
+  [ADR-0003](adr/0003-theme-model.md) for the theme-model rationale.
 - **Radius** — `--radius-sm … --radius-xl`, `--radius-pill`. The Nothing
   default is near-sharp; raise these for a softer brand.
 - **Type** — `--display` (dot-matrix face), `--mono`, `--sans`. Override
@@ -115,7 +125,7 @@ is not. The values above are *measured* (white label on `#a8431a` =
 the same check. Don't set one global `--accent` and hope — that is why
 this example is split per theme.
 
-## Token tiers (0.3.1)
+## Token tiers
 
 Three additive, non-breaking tiers sit on top of the primitives. The
 short legacy names (`--panel`, `--line`, `--accent`, …) keep working
@@ -131,9 +141,11 @@ coarser-grained handles.
   primitives, so light/dark still Just Works.
 - **Accent ramp — `--accent-1 … --accent-6`.** A stepped family
   (subtle → bold) derived from the single `--accent` knob via
-  `color-mix` against the theme background. Re-brands and theme-adapts
-  automatically. This is the palette for charts / data-viz / multi-state
-  surfaces (the use case the JS token export advertises).
+  `color-mix(in oklch, …)` against a per-theme white/black endpoint
+  (`--accent-ramp-end`). Re-brands and theme-adapts automatically. Steps
+  1–4 are subtle surfaces; steps 5–6 are the accent and strong accent.
+  Exact hex outputs are visual tuning, but the token names and roles are
+  stable.
 - **Neutral ramp — `--surface-1 … --surface-6`** (low → high contrast
   against `--bg`) for layered surfaces without hand-picking greys.
 - **Stacking scale — `--z-base / -raised / -sticky / -overlay /

package/docs/usage.md

@@ -60,6 +60,22 @@ Rule of thumb: state → dot, classification → badge, user-controlled value
   `.ui-card` itself, so card padding/border stays the card's and prose
   rhythm stays the content's. One responsibility per element.
 
+## Static reports
+
+Use the opt-in `@ponchia/ui/css/report.css` layer for static, PDF-first
+reports. A report composes `ui-report` + existing primitives: `ui-statgrid`
+for KPIs, `ui-alert` for persistent notices, `ui-table` for evidence,
+`ui-timeline` for events, `ui-meter` for measured values, and `ui-prose` only
+for narrative body content you do not fully control.
+
+Do not turn every report block into a card. Use `ui-report__summary`,
+`ui-report__finding`, and `ui-report__evidence` for document structure; use
+`ui-card` only when the block is genuinely a repeated card item. Charts use
+the report `ui-chart*` wrappers plus the opt-in data-viz tokens; simple static
+bar charts can use `ui-chart__plot`, `ui-chart__bar`, and `ui-chart__fill`.
+Always include a caption and fallback data. Full LLM/static report cookbook:
+[reporting.md](reporting.md).
+
 ## Buttons: variant and size
 
 - **primary** — the single most important action in a view. Aim for one.
@@ -148,12 +164,14 @@ infinite-clone track). It's a gallery: the user drives it.
 
 ## Display glyphs: when (and when not)
 
-`@ponchia/ui/glyphs` is a 43-glyph dot-matrix icon set — navigation
+`@ponchia/ui/glyphs` is a 48-glyph dot-matrix icon set — navigation
 (`arrow-*`, `chevron-*`), actions (`check`, `close`, `plus`, `minus`,
 `search`, `menu`, `gear`), status (`info`, `warning`, `bell`, `lock`) and
-common marks (`home`, `user`, `heart`, `star`, `spark`) — rendered on the
+common marks (`home`, `user`, `heart`, `star`, `spark`, circle-family marks) — rendered on the
 `.ui-dotmatrix` primitive, so they re-skin with the same `--field-dot*`
-tokens as every other dot surface (no SVG, no icon font).
+tokens as every other dot surface. The default and `solid` renderers emit
+dot-matrix DOM, not an icon font; the dense `.ui-icon` renderer uses an
+internal SVG data URL as a CSS mask so it can stay one DOM node.
 
 **Two rendering modes — pick by size.** The dots need physical room to
 read, so the default _dot_ look is for **display** sizes (~40px up: hero
@@ -245,6 +263,28 @@ dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
   Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
   "Data-viz palette".
 
+## SVG annotations: subject, connector, note
+
+`@ponchia/ui/css/annotations.css` (opt-in) adds Bronto-styled SVG annotations
+for reports and chart figures. It is a visual grammar, not a charting or
+authoring engine.
+
+- Compose each callout from `ui-annotation` plus a subject
+  (`ui-annotation__subject`), connector (`ui-annotation__connector`), and note
+  (`ui-annotation__note`, `ui-annotation__title`, `ui-annotation__label`).
+- Use `ui.annotation({ variant, tone, motion })` when building class strings in
+  JS. The default is a callout in the accent tone; motion is always opt-in.
+- Use `@ponchia/ui/annotations` when you want deterministic SVG path strings
+  for circle, rect, threshold, bracket, band, slope, comparison, cluster, axis,
+  timeline, line, elbow, or curve annotations. Use `notePlacement()` for a
+  single bounded note when you need a conservative first placement pass.
+- Status tones are only for status-bearing callouts; otherwise use `accent` for
+  the main insight and `muted` for secondary labels.
+- Keep annotated charts sparse. Dense figures need a scrollable SVG, a
+  simplified mobile SVG, or complete caption/fallback text.
+- Annotation text must be visible or represented in the figure caption, SVG
+  `<desc>`, or fallback table. Full detail in [annotations.md](annotations.md).
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*

package/docs/workbench.md

@@ -0,0 +1,72 @@
+# Workbench — inspector, properties, selection bar
+
+`@ponchia/ui/css/workbench.css` is an opt-in set of primitives for **real
+tools**: an inspector panel, property rows for a selected object, and a bar of
+actions on the current selection. Generic kits stop at cards/tables/forms, so
+every app builds its own half-consistent workbench. This is the low-risk CSS
+core — layout and affordances only.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/workbench.css';
+```
+
+Resizable split panes (a focusable ARIA window-splitter behavior) and drag
+handles are deliberately deferred until a consumer needs them. Not in the core
+bundle.
+
+## Inspector — `.ui-inspector`
+
+A panel of details for the selected object: a `__header` (title + actions) over
+a `__body` of property rows.
+
+```html
+<aside class="ui-inspector">
+  <div class="ui-inspector__header">
+    <h2 class="ui-eyebrow">Rectangle</h2>
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Reset</button>
+  </div>
+  <div class="ui-inspector__body">
+    <!-- property rows -->
+  </div>
+</aside>
+```
+
+## Property row — `.ui-property`
+
+A label/value pair, denser than `ui-key-value` and tuned for an inspector. The
+`__value` can hold a static read-out or an input.
+
+```html
+<div class="ui-property">
+  <span class="ui-property__label">Width</span>
+  <span class="ui-property__value">240 px</span>
+</div>
+<div class="ui-property">
+  <span class="ui-property__label">Fill</span>
+  <span class="ui-property__value"><input class="ui-input" value="#121212" /></span>
+</div>
+```
+
+## Selection bar — `.ui-selectionbar`
+
+A raised bar of actions on the current selection: a `__count` on one side,
+`__actions` on the other. The host owns what is selected and what the actions do.
+
+```html
+<div class="ui-selectionbar">
+  <span class="ui-selectionbar__count">3 selected</span>
+  <span class="ui-selectionbar__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Group</button>
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Align</button>
+    <button class="ui-button ui-button--danger ui-button--sm" type="button">Delete</button>
+  </span>
+</div>
+```
+
+## Scope
+
+CSS only, no recipes — these are structural containers and rows; apply the
+classes directly (or read them from `cls.inspector`, `cls.property`, …). Pair
+the selection bar with the cross-cutting [`ui-sel`](./selection.md) states on the
+selected items themselves; Bronto styles both, the host owns the hit-testing.

package/llms.txt

@@ -16,10 +16,16 @@
 CSS (pick one; do not import both):
 
 ```css
-@import '@ponchia/ui';        /* dist/bronto.css — flattened, minified, one file (recommended) */
-@import '@ponchia/ui/css';    /* css/core.css — @import fan-out, needs a bundler */
+@import '@ponchia/ui'; /* dist/bronto.css — flattened, minified, one file (recommended) */
+@import '@ponchia/ui/css'; /* css/core.css — @import fan-out, needs a bundler */
 ```
 
+`import '@ponchia/ui'` is supported only as a CSS side-effect import in a
+CSS-aware bundler. Do not import the package root from Node/runtime JS; use the
+explicit JS subpaths below.
+
+JS subpaths are ESM-only. In CommonJS, use dynamic `import()`.
+
 Everything lands in `@layer bronto`. Consumer styles in no layer (or a
 later layer) always win over framework styles regardless of selector
 specificity — this is the intended override mechanism; do not fight it
@@ -46,11 +52,13 @@ Optional vanilla behaviors (theme toggle, etc. — SSR-safe, tree-shakeable):
 import { applyStoredTheme } from '@ponchia/ui/behaviors';
 ```
 
-For React/Solid, optional thin hook bindings over those behaviors (peer deps
-`react` / `solid-js`, optional — core stays zero-dep):
+For React/Solid/Qwik, optional thin hook bindings over those behaviors (peer
+deps `react` / `solid-js` / `@builder.io/qwik`, optional — core stays zero-dep):
 
 ```js
-import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid'
+import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid' or '@ponchia/ui/qwik'
+// React: scope with { root: reactRef } or a resolver, not { root: ref.current } during render.
+// Qwik: hooks run in useVisibleTask$; scope with a Qwik signal — useDialog({ root: useSignal() }).
 ```
 
 Optional display glyphs — dot-matrix bitmaps on the `.ui-dotmatrix` primitive
@@ -66,7 +74,7 @@ like `data-theme` (the derived accent family only recomputes at `:root`):
 
 ```html
 <link rel="stylesheet" href="@ponchia/ui/css/skins.css" />
-<html data-bronto-skin="amber-crt | phosphor-green | e-ink">
+<html data-bronto-skin="amber-crt | phosphor-green | e-ink"></html>
 ```
 
 Each re-points the one `--accent` (OKLCH, per-theme, contrast-gated); status
@@ -89,6 +97,265 @@ simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
 (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
 
+Building analytical / generated-report UI? Import the roll-up
+`@ponchia/ui/css/analytical.css` (bundles annotations + legend + marks +
+connectors + spotlight + crosshair + selection) instead of the seven leaves;
+add `css/dataviz.css` for chart colours and `css/report.css` for the document
+grammar. The individual layers (each opt-in, none in the default bundle):
+
+Optional SVG annotations for charts/reports — opt-in, never in the default
+bundle. This is Bronto's subject / connector / note grammar inspired by
+d3-annotation, not an authoring engine:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/annotations.css" />
+```
+
+```js
+import { annotationParts, connectorLine, circleSubjectPath } from '@ponchia/ui/annotations';
+```
+
+Use `ui-annotation` groups inside SVG with `ui-annotation__subject`,
+`ui-annotation__connector`, `ui-annotation__note`, `ui-annotation__title`, and
+`ui-annotation__label`. `ui.annotation({ variant, tone, motion })` builds the
+base class string. Variants cover labels, callouts, elbow/curve connectors,
+circle/rect/threshold subjects, badges, brackets, bands, slopes, comparisons,
+clusters, axis marks, timeline pins, and evidence markers. Motion is opt-in
+(`draw`, `reveal`, `pulse`, `focus`) and respects reduced-motion preferences.
+Use `notePlacement()` for one-note bounded placement, but do not treat it as a
+whole-chart collision solver. `declutterLabels(items,{gap,min,max})` is a
+deterministic 1-D declutter; `directLabels(items,{axis,cross,gap,min,max,shape})`
+adds the leader line (it declutters labels along an axis and returns each placed
+point plus a leader path `d` for `ui-annotation__connector`) — neither owns
+scales, DOM, or 2-D placement. Status tones are only for status-bearing callouts.
+Keep charts sparse; dense mobile figures need horizontal scrolling, a simplified
+SVG, or complete caption/fallback text. Details: `docs/annotations.md`.
+
+Optional legends / data keys for charts and figures — opt-in, never in the
+default bundle. Reads the `--chart-*` tokens, so a key never drifts from its
+series:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/legend.css" />
+```
+
+Use a `ui-legend` container with `ui-legend__item` rows, each holding a
+`ui-legend__swatch` (decorative, `aria-hidden`) and a `ui-legend__label` (the
+required non-colour channel — WCAG 1.4.1; colour alone never carries meaning).
+Set the swatch colour inline (`style="--chart-color: var(--chart-3)"`, plus
+`--chart-pattern` to match a patterned mark) or with a `ui-legend__swatch--1..8`
+index helper. Variants: `ui-legend--vertical`/`--compact`/`--with-values`,
+`ui-legend--gradient` (+`--diverging`, with `ui-legend__track`/`__ticks`/`__tick`),
+and `ui-legend--threshold`. `ui.legend()`/`ui.legendItem()`/`ui.legendSwatch()`
+build the class strings. Interactive (series-toggling) legends are opt-in:
+author entries as `<button aria-pressed>` under `[data-bronto-legend]`, run
+`initLegend()` (or `useLegend()`), and listen for `bronto:legend:toggle`
+(`{ series, active }`) — Bronto flips the control state; you hide the series and
+own the `aria-live` announcement. Details: `docs/legends.md`.
+
+Optional text marks / evidence emphasis for running prose — opt-in, never in
+the default bundle. The prose counterpart to annotations (annotations call out a
+figure; marks call out a sentence):
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/marks.css" />
+```
+
+Put `ui-mark` on a `<mark>` for inline emphasis (semantic, not just visual).
+Styles: default highlight, `ui-mark--underline`, `ui-mark--box`,
+`ui-mark--strike`. Tones: `ui-mark--accent` (the rationed accent),
+`--success`/`--warning`/`--danger`/`--info` (status-bearing only), `--muted`.
+`ui-mark--draw` sweeps the highlight in (reduced-motion-safe). `ui-bracket-note`
+(+ `ui-bracket-note__label`, tones `--accent`/`--warning`/`--danger`/`--info`)
+brackets a whole passage — the prose analogue of `ui-annotation--bracket`.
+`ui.mark({ style, tone, motion })` / `ui.bracketNote({ tone })` build the class
+strings. A mark is visual only; if the emphasis carries meaning the words don't,
+state it in the text (WCAG 1.4.1). Details: `docs/marks.md`.
+
+Optional connectors / leader lines between two DOM elements — opt-in, never in
+the default bundle. Pure geometry + an optional draw/track behavior; owns no
+layout:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/connectors.css" />
+```
+
+Place a `ui-connector` SVG (`data-bronto-connector`, `aria-hidden`) as an
+overlay inside a `position: relative` container holding both endpoints; set
+`data-from`/`data-to` (element ids), optional `data-shape`
+(straight|elbow|curve), `data-from-side`/`data-to-side`, and `data-end`
+(arrow|dot|none). `initConnectors()` (or `useConnectors()`) draws the path and
+redraws on resize/scroll. Tones `ui-connector--accent`/`--muted`/status,
+`ui-connector--dashed`, `ui-connector--draw`. Pure helpers from
+`@ponchia/ui/connectors` (`connectRects`, `connectorPath`, `arrowHead`,
+`anchorPoint`, …) return SVG strings for SSR/canvas. Details: `docs/connectors.md`.
+
+Optional spotlight / guided-focus overlay — opt-in, never in the default
+bundle. The visual language of a tour, NOT a tour engine (the host owns step
+order/advancing/visibility):
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/spotlight.css" />
+```
+
+A `ui-spotlight` overlay (`data-bronto-spotlight`, `data-target=<element id>`)
+contains a `ui-spotlight__hole` (the box-shadow cutout) and a `ui-tour-note`
+callout (`__step`/`__title`/`__body`/`__actions`). `initSpotlight()` (or
+`useSpotlight()`) measures the target and sets `--spot-x/y/w/h`, re-placing on
+resize/scroll and when `data-target` changes — so advance a tour by updating
+`data-target`. `ui-spotlight--ring` adds a ring. The overlay is non-blocking by
+design; put the real guidance text in the focusable `ui-tour-note`. Details:
+`docs/spotlight.md`.
+
+Optional crosshair / readout for reading a value off a plot — opt-in, never in
+the default bundle. Reports the pointer position; the host maps it to data:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/crosshair.css" />
+```
+
+Mark the plot `[data-bronto-crosshair]` (position: relative) and put a
+`ui-crosshair` overlay inside it with `ui-crosshair__line ui-crosshair__line--x`
+and/or `--y`, optional `ui-crosshair__badge`, and a `ui-readout` chip.
+`initCrosshair()` (or `useCrosshair()`) sets `--crosshair-x/y` (px) on pointer
+move, toggles `is-active`, and dispatches `bronto:crosshair:move`
+({ x, y, fx, fy } — px + 0..1 fractions) / `bronto:crosshair:leave`. It does NOT
+find the nearest datum or map pixels→data (that needs your scales). `ui.crosshair({ muted })`.
+Details: `docs/crosshair.md`.
+
+Optional selection-state vocabulary — opt-in, cross-cutting, CSS only. The carve
+from brush/lasso: Bronto does not do region selection/hit-testing; it ships only
+the states an item can be in:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/selection.css" />
+```
+
+Apply `ui-sel` + `ui-sel--on` (selected), `ui-sel--off` (excluded), or
+`ui-sel--maybe` (live-brush candidate) to any data element (chart mark, table
+row, list item, map region) from YOUR selection/brush logic — Bronto only styles
+them. `ui.sel({ state: 'on'|'off'|'maybe' })`. Details: `docs/selection.md`.
+
+Optional source/citation/provenance trust layer — opt-in, CSS only, never in
+the default bundle. The grammar for "where did this come from?" in generated
+reports/AI output:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/sources.css" />
+```
+
+`ui-citation` (inline ref on a real `<a>`/`<button>`; `--chip` = named-source
+pill), `ui-source-card` (+`__title`/`__origin`/`__time`/`__excerpt`/`__actions`),
+`ui-source-list` (+`__item`), and `ui-provenance` (+`__item`). A cross-cutting
+trust state sets the tone: `ui-src--verified`/`--reviewed`/`--generated`/
+`--unverified`/`--stale`/`--conflict` — always paired with an author-written
+label (never colour alone). Bronto styles + states; the host owns fetching,
+numbering, and trust. `ui.citation({chip,state})` / `ui.source({state})` /
+`ui.provenance({state})`. Details: `docs/sources.md`.
+
+Optional lifecycle/system-state vocabulary — opt-in, CSS only, never in the
+default bundle. The states apps live in (saving/saved/queued/offline/stale/
+conflict/error/locked/reviewed/needs-review):
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/state.css" />
+```
+
+`ui-state` (+`__label`/`__detail`) carries a tone dot + the canonical label;
+the `ui-state--saving`/`--saved`/… modifier bakes the tone, `ui-state--busy`
+pulses the indicator for
+in-progress states (reduced-motion-safe). `ui-syncbar` is a page/document
+save-status strip. The label IS the state (never colour alone); the host owns
+the state machine, retry, and persistence — persistent state gets persistent UI,
+not a toast. `ui.state({ state, busy })`. Details: `docs/state.md`.
+
+Optional generated-content / AI-trust surfaces — opt-in, CSS only, never in the
+default bundle. NOT a chat kit; the trust surfaces around generated content:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/generated.css" />
+```
+
+`ui-generated` (+`__label`) marks a machine-authored region; `ui-origin-label`
+(+`--ai`) tags origin ("AI generated" / "Human reviewed"); `ui-reasoning`
+(+`__body`) and `ui-tool-log` / `ui-tool-call` (+`__name`/`__status`/`__body`)
+are quiet native-`<details>` collapsibles for reasoning + tool traces. Bronto
+styles disclosure/origin/trace; the host owns model metadata, redaction, and
+safety. No confidence/verdict widget (don't fabricate precision). `ui.originLabel({ ai })`.
+Details: `docs/generated.md`.
+
+Optional workbench primitives for tool UIs — opt-in, CSS only, never in the
+default bundle:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/workbench.css" />
+```
+
+`ui-inspector` (+`__header`/`__body`) is a selected-object detail panel;
+`ui-property` (+`__label`/`__value`) is a denser key/value row for it;
+`ui-selectionbar` (+`__count`/`__actions`) is a raised action bar for the current
+selection (pair with `ui-sel` states on the items). Layout/affordances only —
+resizable split panes and drag handles are deferred. Class-only. Details:
+`docs/workbench.md`.
+
+Optional command palette — opt-in CSS shell (`css/command.css`) + `initCommand`
+behavior. Filter + keyboard-navigate a DOM-authored command list:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/command.css" />
+```
+
+`ui-command` (+`__input`/`__list`/`__group`/`__item`/`__shortcut`/`__meta`/
+`__empty`); `initCommand()` owns filtering, roving focus (Down/Up/Home/End),
+Enter→`bronto:command:select` ({value,label}) and Escape→`bronto:command:close`.
+The HOST owns the action registry + execution; NO global Cmd/Ctrl+K (open it
+yourself, e.g. a <dialog> via initDialog). Pairs with `ui-shortcut`. Binding:
+`useCommand()` (react/solid/qwik). Details: `docs/command.md`.
+
+Optional static report layer for LLM-authored HTML reports — opt-in, never in
+the default bundle. Pair it with the normal bundle, and add data-viz only when
+the report contains charts. For standalone browser HTML, use real URLs; package
+specifiers only work after a bundler rewrites them:
+
+```html
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
+```
+
+In Vite/webpack/etc., import `@ponchia/ui`, `@ponchia/ui/css/report.css`, and
+`@ponchia/ui/css/dataviz.css` instead.
+
+Canonical report skeleton:
+
+```html
+<main class="ui-report ui-report--numbered">
+  <header class="ui-report__cover">
+    <p class="ui-eyebrow">Report</p>
+    <h1 class="ui-report__title">System review</h1>
+    <p class="ui-report__subtitle">Static HTML, Chromium PDF-ready.</p>
+    <ol class="ui-report__meta">
+      <li>2026-06-01</li>
+      <li>Generated</li>
+    </ol>
+  </header>
+  <section class="ui-report__section">
+    <h2 class="ui-report__section-head">Executive summary</h2>
+    <div class="ui-report__summary">
+      <div class="ui-prose"><p>Use prose only for narrative body content.</p></div>
+    </div>
+  </section>
+</main>
+```
+
+Report rules for agents: static output by default; do not initialize behaviors
+over untrusted generated content; sanitize arbitrary LLM/CMS/user HTML before
+rendering; use semantic headings; give tables captions and header cells; give
+charts captions, legends/direct labels, and fallback data; use
+`ui-chart__plot`/`ui-chart__bar`/`ui-chart__fill` for simple static bar charts;
+use `ui-report__section--unnumbered` for appendices in numbered reports; never
+use raw chromatic inline colors. Full cookbook: `docs/reporting.md`.
+
 ## Authoritative offline references (shipped in this package)
 
 Read these from `node_modules/@ponchia/ui/` — no network needed:
@@ -101,9 +368,16 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   the same source as the types and CI-drift-checked.
 - `docs/theming.md` — the token contract: which tokens to override, the
   light/dark model, and the rationed-accent rule.
+- `docs/stability.md` — the public API matrix: stable vs internal surfaces,
+  root-import contract, behavior trust boundary, and glyph-mask CSP note.
 - `docs/usage.md` — the decision guide: badge vs chip vs dot, default
   density, prose-in-card, when to add a behavior. Read this before
   re-implementing UI the framework already has an opinion about.
+- `docs/reporting.md` — static/PDF-first report cookbook for LLM-authored
+  reports, including report skeletons, chart rules, print utilities, and safety
+  boundaries.
+- `docs/annotations.md` — SVG annotation recipes and helper guidance for
+  analytical figures.
 - `docs/contrast.md` — the published, CI-gated WCAG 2.1 contrast matrix
   for every contractual token pairing, per theme. Generated from the
   resolved palette; the build fails below the declared floor.
@@ -117,13 +391,15 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `glyphs/glyphs.d.ts` — the `GlyphName` literal union plus `renderGlyph` /
   `glyphCells` signatures for the display glyphs. (The DOM form,
   `initDotGlyph`, is declared in `behaviors/index.d.ts`.)
+- `annotations/index.d.ts` — no-dependency SVG path helpers for Bronto
+  annotation geometry.
 - `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
 
 ## Human-browsable references (not shipped in the npm tarball, by design)
 
 - Live kitchen-sink demo (every component, light/dark, RTL): https://ponchia.github.io/bronto-ui/
 - Architecture & the CSS-first decision: https://github.com/Ponchia/bronto-ui/blob/main/docs/architecture.md
-- Framework integration guides (Astro / SvelteKit / React-Solid / vanilla):
+- Framework integration guides (Astro / SvelteKit / React-Solid-Qwik / vanilla):
   https://github.com/Ponchia/bronto-ui/tree/main/docs/getting-started
 
 ## Rules an agent should respect
@@ -131,6 +407,10 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - Never invent `ui-*` class names. Every valid class is a member of
   `cls` in `classes/index.d.ts`; if it is not there, it does not exist.
 - Prefer the `ui.*()` recipes over hand-concatenating modifier strings.
+  Report/layout classes added in 0.4.1 are the exception: use `cls.report*`,
+  `cls.chart*`, `cls.printOnly`, or literal documented class names because
+  there are no `ui.report()` / `ui.chart()` recipes yet. Annotations do have a
+  `ui.annotation()` recipe for variant/tone selection.
 - Override framework styles by writing your own rules outside
   `@layer bronto` — not with higher specificity or `!important`.
 - Color is tiered (ADR-0001): neutral canvas · one rationed accent · locked
@@ -138,4 +418,4 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   tokens — re-point `--accent` (or a `data-bronto-skin` colorway), use status
   tokens for status, and `--chart-*` (from `css/dataviz.css`) for charts only.
   Don't add raw hues to components; `check:color-policy` enforces this.
-- Pre-1.0 SemVer: breaking changes ship in the *minor*. Pin `~0.x`.
+- Pre-1.0 SemVer: breaking changes ship in the _minor_. Pin `~0.x`.