@ponchia/ui 0.5.0 → 0.6.3

package/docs/reporting.md

@@ -15,10 +15,17 @@ rewrites them:
 @import '@ponchia/ui/css/legend.css';
 ```
 
+**`dist/bronto.css` is the standard component set only — it does NOT contain
+the report, chart, annotation, or legend layers.** Those are opt-in leaves
+under `dist/css/`; a report links the default bundle *and* each leaf it uses.
+Forgetting them is the most common way an LLM-emitted report renders unstyled.
+
 For standalone browser HTML, use real stylesheet URLs. Package specifiers like
-`@ponchia/ui/css/report.css` do not resolve in a saved `.html` file:
+`@ponchia/ui/css/report.css` do not resolve in a saved `.html` file — and note
+the path is `dist/css/`, the built leaf, not the source `css/`:
 
 ```html
+<!-- installed locally -->
 <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" />
@@ -26,16 +33,51 @@ For standalone browser HTML, use real stylesheet URLs. Package specifiers like
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/legend.css" />
 ```
 
-If you copy the built CSS next to the report, keep the same relationship between
-`dist/bronto.css`, `dist/css/report.css`, `dist/css/dataviz.css`,
-`dist/css/annotations.css`, `dist/css/legend.css`, and `fonts/` so font URLs
-continue to resolve.
+No install? Link the same files from a CDN. Pin the version — pre-1.0, breaking
+changes ship in the minor (see [stability.md](./stability.md)):
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/legend.css" />
+```
+
+The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
+with no extra setup. If instead you copy the built CSS next to the report, keep
+the same relationship between `dist/bronto.css`, the `dist/css/*` leaves, and
+`fonts/` so the relative font URLs continue to resolve.
 
 The report layer is static and PDF-first. It does not initialize behaviors and
 does not sanitize content. If a report includes arbitrary LLM, CMS, or user HTML,
 sanitize that content before rendering it and do not initialize
 `data-bronto-*` behaviors on the generated region.
 
+## The analytical toolbox in a report
+
+`css/report.css` gives you the document grammar (covers, sections, findings,
+evidence). The _content_ inside those sections is where the rest of the
+analytical layer earns its place. Each one is an opt-in import that stays out of
+the default bundle — add the leaves a given report actually needs, or pull the
+whole set with `@ponchia/ui/css/analytical.css`. Reach for:
+
+| Layer | Import | Reach for it when… |
+| --- | --- | --- |
+| **Marks** (`.ui-mark`, `.ui-bracket-note`) | `css/marks.css` | You want to emphasise a phrase _in prose_ — a highlight on the finding, an underline on a risk, or a bracket around an evidence/caveat passage. The inline counterpart to annotations. See [marks.md](./marks.md). |
+| **Sources / provenance** (`.ui-citation`, `.ui-source-card`, `.ui-source-list`, `.ui-provenance`) | `css/sources.css` | The report makes claims a reader will question — "where did this come from?". A CSS-only trust layer whose cross-cutting state modifier (`.ui-src--verified`, plus reviewed / generated / unverified / stale / conflict) sets a rationed tone, always paired with a written label, never colour alone. See [sources.md](./sources.md). |
+| **Annotations** (`.ui-annotation*`) | `css/annotations.css` | A figure needs an explicit callout — a peak, a limit, a watched region — or a small decorative margin mark. SVG only. See [annotations.md](./annotations.md) and the [off-chart + scaling notes](./annotations.md#using-annotations-off-chart) before you size one. |
+| **Legends / data keys** (`.ui-legend*`) | `css/legend.css` | A chart figure needs a colour key. WCAG 1.4.1 by construction. See [legends.md](./legends.md). |
+| **Mermaid theme** (`@ponchia/ui/mermaid`) | _(JS/JSON, no CSS)_ | The report embeds a [Mermaid](https://mermaid.js.org) diagram (flowchart, sequence, pie…) and you want it on-brand instead of generic. A resolved `base` theme projected from the same tokens as `charts.json`; annotate the rendered SVG with the annotation layer. See [mermaid.md](./mermaid.md). |
+| **D2 theme** (`@ponchia/ui/d2`) | _(JS/JSON, no CSS)_ | The report embeds a [D2](https://d2lang.com) diagram and you want it on-brand. Resolved theme-override slots (monochrome base + one rationed accent) projected from the same tokens; annotate the rendered SVG. See [d2.md](./d2.md). |
+| **Generated-content trust** (`.ui-generated`, `.ui-origin-label`, `.ui-reasoning`, `.ui-tool-log`) | `css/generated.css` | The report (or a section of it) is AI/system-authored and should _say so_ — an origin label plus quiet, collapsible reasoning / tool-call logs. Pairs with the sources layer. See [generated.md](./generated.md). |
+| **Lifecycle / system state** (`.ui-state`, `.ui-syncbar`) | `css/state.css` | A status report needs to show the state a thing is in — saving / queued / stale / conflict / reviewed — as a labelled object, not a bare coloured dot. See [state.md](./state.md). |
+
+These compose with the report-native primitives already called out in
+[Composition rules](#composition-rules): `ui-statgrid`, `ui-alert`, `ui-table`,
+`ui-timeline`, `ui-meter`, and `ui-num`. None of them require behavior JS, so
+they are all safe in the static, PDF-first report path.
+
 ## Canonical skeleton
 
 ```html
@@ -94,7 +136,7 @@ sanitize that content before rendering it and do not initialize
   below, which only shrinks the cover.
 - Use `ui-report__cover` for title, subtitle, author/date, and generation
   metadata. Add `ui-report__cover--compact` for short screen-first reports.
-  Use `ui-report__header` for a compact in-page header instead of a full cover
+  Use `ui-report__head` for a compact in-page header instead of a full cover
   (same role, no tall hero block). Author `ui-report__meta` as a `<ul>` — the
   facts it lists are unordered.
 - Use `ui-report__section` and `ui-report__section-head` for report chapters.
@@ -125,23 +167,198 @@ sanitize that content before rendering it and do not initialize
   inside `ui-prose`; use `.ui-table` for curated evidence tables. If a
   `ui-report__evidence` block contains only a `ui-table-wrap`, the report layer
   removes the inner frame so evidence tables do not look double-boxed.
-- Every `<figure>` should include a `figcaption` using
-  `ui-chart__caption` (chart figures) or `ui-report__caption` (any other
-  report figure); the two are interchangeable in style.
+- Every `<figure>` should include a `figcaption` using `ui-report__caption`.
 - Do not use raw color values. Theme with `--accent`; use status tones for
   status; use chart tokens only in chart figures.
 
+## Numbers and dates
+
+The framework **aligns** figures; it does not **format** them. `.is-num` (table
+cells) and `ui-num` (standalone) give tabular figures and end-alignment so a
+column lines up — but a raw `1240` or `2026-6-1` still reads as machine output.
+Format the values yourself, before they reach the markup:
+
+- **Numbers** — group thousands and fix the precision. In JS,
+  `new Intl.NumberFormat('en-US').format(1240)` → `1,240`;
+  `{ style: 'currency', currency: 'USD' }` → `$1,240.00`;
+  `{ style: 'percent', maximumFractionDigits: 1 }` for rates;
+  `{ notation: 'compact' }` → `1.2M` for headline KPIs. Pick one locale and
+  precision per report and apply it consistently.
+- **Dates** — render a human label but keep the machine value in a
+  `<time datetime="…">` (ISO-8601), as the report skeleton and `ui-timeline`
+  already do. `new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })`
+  → `Jun 1, 2026`.
+- **Signs and units** — write the sign and unit into the text (`+1`, `−3.2%`,
+  `18 h`); never rely on a tone or arrow alone to say "down" (WCAG 1.4.1).
+- Keep a column's precision uniform so the tabular alignment actually reads.
+
+A non-JS host formats with its own locale library (Python `babel`, Go
+`golang.org/x/text/message`, etc.) and emits the finished strings — bronto only
+styles them.
+
+## Trend deltas
+
+For a standalone change indicator (a KPI's movement, a row's quarter-over-quarter
+shift), use `ui-delta`. A direction modifier sets both the arrow glyph — the
+non-colour channel — and the conventional tone:
+
+```html
+<span class="ui-delta ui-delta--up">+12.4%</span>
+<span class="ui-delta ui-delta--down">−3</span>
+<span class="ui-delta ui-delta--flat">0</span>
+```
+
+Direction tone follows the common case (up = good, green; down = bad, red). When
+**up is the bad direction** — latency, error rate, cost, churn — add
+`ui-delta--invert` to swap only the tone; the arrow still reports real direction:
+
+```html
+<span class="ui-delta ui-delta--up ui-delta--invert">+48 ms p95</span>
+```
+
+The arrow is visual; always include the number and unit in the text.
+
+A stat card's own `ui-stat__delta is-pos` / `is-neg` carries **tone** (good vs
+bad, as colour) and auto-prepends a `▲`/`▼` glyph — but that glyph follows the
+**tone**, not the real direction: `is-pos` always renders `▲` and `is-neg`
+always `▼`, regardless of whether the number went up or down. The tone is
+deliberately decoupled from direction (a *dropped* latency is good, so `is-pos`),
+so the auto-arrow can contradict the words: write `is-pos` on a "−48 ms" and it
+prints `▲ −48 ms`. Do **not** add your own direction word/arrow on top, or you
+double it. When the change must read by direction — most printed reports —
+prefer `ui-delta` for the card's delta line, because its `--up`/`--down` arrow is
+a real (author-controlled) non-colour channel; reach for the arrow-free `ui-num`
+if you want neither tone nor glyph:
+
+```html
+<span class="ui-stat__label">p95 latency</span>
+<span class="ui-stat__value">172 ms</span>
+<span class="ui-delta ui-delta--down ui-delta--invert">−48 ms</span>
+```
+
+Here the arrow points **down** (latency fell) while `--invert` keeps the tone
+green (down is good) — both channels stay honest. Reach for `ui-stat__delta` only
+when a bare tonal accent is enough.
+
+## Comparison layout
+
+For an "A vs B" or before/after section, use `ui-compare` — a fluid grid that
+wraps to a single stack on a narrow screen, so two panels never overflow.
+`ui-compare__col` is one side; label it with `ui-compare__head`. Add
+`ui-compare--2up` to pin exactly two equal columns for a hard pairing.
+
+```html
+<div class="ui-compare ui-compare--2up">
+  <div class="ui-compare__col">
+    <p class="ui-compare__head">Before</p>
+    <div class="ui-statgrid">
+      <div class="ui-stat">
+        <span class="ui-stat__label">p95 latency</span>
+        <span class="ui-stat__value">220 ms</span>
+      </div>
+    </div>
+  </div>
+  <div class="ui-compare__col">
+    <p class="ui-compare__head">After</p>
+    <div class="ui-statgrid">
+      <div class="ui-stat">
+        <span class="ui-stat__label">p95 latency</span>
+        <span class="ui-stat__value">172 ms</span>
+        <span class="ui-stat__delta is-pos">−48 ms</span>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
 ## Chart figure recipe
 
-The report layer supplies chart containers and a small static bar pattern, not a
-chart engine. The data key is the standalone, portable `.ui-legend`
-(`@ponchia/ui/css/legend.css`) — see [legends.md](./legends.md). For
-CSS/HTML/SVG charts, pair each chart color with a direct label, a pattern, or a
-fallback table.
+bronto ships **no chart component** — a chart needs scales and data binding, the
+two things the analytical layer [refuses to own](./architecture.md). It supplies
+the figure frame, the data key, and the colour palette; the chart itself comes
+from one of two routes:
+
+- **Live, interactive, or many-series** — theme [Vega-Lite](./vega.md):
+  `brontoVegaConfig(theme)` (from `@ponchia/ui/vega`) returns an on-brand
+  Vega-Lite `config` you spread into a spec and hand to vega-embed. Vega renders
+  the SVG/canvas; bronto only paints it. See [vega.md](./vega.md) for the full
+  recipe and the resolved `@ponchia/ui/vega.json` for non-JS hosts.
+- **Frozen, print, or zero-JS** — hand-author a token-themed inline `<svg>`,
+  painting marks from the `--chart-N` palette so the figure prints exactly and
+  carries no runtime.
+
+Whichever route, the figure frame is the same: wrap it in `ui-report__figure`,
+caption it with `ui-report__caption`, give it the standalone, portable
+`.ui-legend` data key (`@ponchia/ui/css/legend.css` — see
+[legends.md](./legends.md)), and pair every colour with a direct label, a
+pattern, **and** a fallback `ui-table` so the figure survives mono print and
+colour-vision deficiency.
+
+A Vega-Lite figure. The live mount is **`ui-screen-only`** and the fallback
+`ui-table` carries the data into print — a live chart bakes the on-screen theme
+into its SVG/canvas at render time, so printing it would emit a dark-baked chart
+on white paper. Print the table; keep the chart for screen:
+
+```html
+<figure class="ui-report__figure" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-report__caption">
+    Fig 1 - Weekly focus split
+  </figcaption>
+  <div id="focus-chart" class="ui-screen-only" style="min-block-size: 240px">
+    <noscript>Chart needs JavaScript — the data is in the table below.</noscript>
+  </div>
+  <div class="ui-table-wrap">
+    <table class="ui-table ui-table--dense">
+      <caption>Chart source data</caption>
+      <thead>
+        <tr><th>Series</th><th class="is-num">Hours</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Research</td><td class="is-num">18</td></tr>
+        <tr><td>Delivery</td><td class="is-num">11</td></tr>
+      </tbody>
+    </table>
+  </div>
+</figure>
+<script type="module">
+  import vegaEmbed from 'vega-embed';
+  import { brontoVegaConfig } from '@ponchia/ui/vega';
+  const theme = document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light';
+  vegaEmbed('#focus-chart', {
+    data: { values: [
+      { series: 'Research', hours: 18 },
+      { series: 'Delivery', hours: 11 },
+    ] },
+    mark: 'bar',
+    encoding: {
+      x: { field: 'series', type: 'nominal' },
+      y: { field: 'hours', type: 'quantitative' },
+    },
+  }, { config: brontoVegaConfig(theme), renderer: 'svg', actions: false });
+</script>
+```
+
+Give the mount a `min-block-size` so the figure is not a collapsed blank band
+before the chart paints (or while JS is blocked), and pass **`renderer: 'svg'`**
+(vega-embed defaults to `canvas`, which doesn't theme-inspect and prints as a
+raster).
+
+> The bare-specifier `import`s above assume a **build step** (or an import map),
+> and even then `import`/`fetch` of the config only works over an `http(s)`
+> origin. A static report **opened from disk (`file://`) cannot import the module
+> nor fetch `vega.json`** (CORS) — load Vega + Vega-Lite + vega-embed from pinned
+> `/build/*.min.js` CDN tags and **inline the resolved `config` object**
+> (generate it with `npm run emit:theme vega light`), the file://-safe recipe in
+> [vega.md](./vega.md#from-a-cdn-no-bundler). For a report
+> you intend to **print/PDF**, prefer the frozen inline `<svg>` below — it has no
+> runtime, prints exactly, and sidesteps all of this.
+
+A frozen, token-themed inline `<svg>` for the same data — no runtime, prints
+exactly, with a `.ui-legend` key and the fallback table:
 
 ```html
-<figure class="ui-report__figure ui-chart ui-print-exact" role="group" aria-labelledby="chart-title">
-  <figcaption id="chart-title" class="ui-chart__caption">
+<figure class="ui-report__figure ui-print-exact" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-report__caption">
     Fig 1 - Weekly focus split
   </figcaption>
   <ul class="ui-legend" aria-label="Series">
@@ -162,42 +379,43 @@ fallback table.
       <span class="ui-legend__label">Delivery</span>
     </li>
   </ul>
-  <div class="ui-chart__plot" aria-hidden="true">
-    <div
-      class="ui-chart__bar"
-      style="--chart-value: 72%; --chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
-    >
-      <div class="ui-chart__label"><span>Research</span><span>18 h</span></div>
-      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
-    </div>
-    <div
-      class="ui-chart__bar"
-      style="--chart-value: 44%; --chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
-    >
-      <div class="ui-chart__label"><span>Delivery</span><span>11 h</span></div>
-      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
-    </div>
-  </div>
-  <div class="ui-chart__fallback">
-    <div class="ui-table-wrap">
-      <table class="ui-table ui-table--dense">
-        <caption>Chart source data</caption>
-        <thead>
-          <tr><th>Series</th><th class="is-num">Hours</th></tr>
-        </thead>
-        <tbody>
-          <tr><td>Research</td><td class="is-num">18</td></tr>
-          <tr><td>Delivery</td><td class="is-num">11</td></tr>
-        </tbody>
-      </table>
-    </div>
+  <svg viewBox="0 0 360 160" role="img" aria-labelledby="focus-svg-title">
+    <title id="focus-svg-title">Weekly focus split</title>
+    <line x1="36" y1="132" x2="324" y2="132" stroke="var(--line)" />
+    <rect x="72" y="42" width="96" height="90" fill="var(--chart-1)" />
+    <rect x="200" y="77" width="96" height="55" fill="var(--chart-2)" />
+  </svg>
+  <div class="ui-table-wrap">
+    <table class="ui-table ui-table--dense">
+      <caption>Chart source data</caption>
+      <thead>
+        <tr><th>Series</th><th class="is-num">Hours</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Research</td><td class="is-num">18</td></tr>
+        <tr><td>Delivery</td><td class="is-num">11</td></tr>
+      </tbody>
+    </table>
   </div>
 </figure>
 ```
 
-For canvas or SVG libraries, import resolved series colors from
-`@ponchia/ui/charts.json` and keep the same legend/caption/fallback structure in
-the surrounding HTML.
+For a frozen figure, drive the SVG fills from the `--chart-N` palette tokens
+directly; for a Vega chart, the same colours arrive through
+`brontoVegaConfig`'s `range.*` ramps, projected from `@ponchia/ui/charts.json`.
+
+For a **sequential** figure (a heatmap, a choropleth, a magnitude ramp) fill the
+cells from the single-hue ramp tokens `--chart-seq-1` … `--chart-seq-6`
+(low → high); for a **diverging** figure (−…0…+) use `--chart-div-1` …
+`--chart-div-7` (the middle band is the neutral midpoint). Both ramps live in
+`css/dataviz.css`, and their resolved per-theme hexes are in
+`@ponchia/ui/charts.json` (`sequential` / `diverging`) for a non-JS or `file://`
+host that needs literal values. The same ramps back Vega's
+`range.heatmap`/`ramp`/`diverging`, so a frozen sequential figure and a live Vega
+heatmap read identically — but note the ramp **runs pale→deep in light theme and
+deep→pale in dark** (it flips to stay legible against the background), so don't
+print a colour key that assumes one direction, and don't bake a fixed ink colour
+onto the cells. Pair the figure with a stepped legend and the fallback table.
 
 ## Annotation recipe
 
@@ -246,6 +464,111 @@ style itself.
 </ol>
 ```
 
+## Meters and quotes
+
+Two more report-native primitives. A **meter** shows a measured value as a
+proportion — set the percentage on the `--value` custom property of
+`ui-meter__fill` (a number 0–100, see `classes.json` `customProperties`); a tone
+modifier picks the fill colour, and the readable label is yours to write beside
+it (never rely on the bar alone — WCAG 1.4.1):
+
+```html
+<div class="ui-meter ui-meter--accent">
+  <span class="ui-meter__fill" style="--value: 72"></span>
+</div>
+<span class="ui-num">72% of quota</span>
+```
+
+`--value` is a percentage and the fill **clamps at 100**, so an over-target
+reading (e.g. 112 % of plan) shows a full bar — put the true figure in the
+written label beside it (`ui-num`), which is the data of record anyway.
+
+For a block of meters — SLO burn, error budgets, capacity — lay each out as
+**label | bar | value** with `ui-meter__row`; `ui-meter__label` names it and
+`ui-meter__value` carries the reading (the data of record — never the bar
+alone). The row collapses to a stack on a narrow screen, so you don't hand-roll
+the grid:
+
+```html
+<div class="ui-meter__row">
+  <span class="ui-meter__label">Write availability</span>
+  <div class="ui-meter ui-meter--danger" role="presentation">
+    <span class="ui-meter__fill" style="--value: 90"></span>
+  </div>
+  <span class="ui-meter__value ui-num">90% of budget burned</span>
+</div>
+```
+
+A **pull-quote** lifts a source sentence out of the prose — `ui-quote` is the
+block, `ui-quote__cite` attributes it:
+
+```html
+<blockquote class="ui-quote">
+  <p>The migration paid for itself within the first billing cycle.</p>
+  <cite class="ui-quote__cite">Q2 finance review</cite>
+</blockquote>
+```
+
+## Theming a live report
+
+The report layer is static, but a screen report often offers a light/dark
+**toggle**. The chart palette is the one piece that does not re-skin from CSS
+alone: Vega and Mermaid/D2 bake resolved colours into their SVG at render time
+(they can't read `var()`), so on a theme flip you must **re-render** the foreign
+figures. Set the theme on the root and re-embed:
+
+```html
+<button type="button" class="ui-button ui-button--ghost ui-button--sm" id="theme-toggle">
+  Toggle theme
+</button>
+<script type="module">
+  import { brontoVegaConfig } from '@ponchia/ui/vega'; // http(s) origin only
+  const root = document.documentElement;
+  let view; // the previous Vega view, so we can tear it down before re-embedding
+  const renderChart = async () => {
+    const theme = root.dataset.theme === 'dark' ? 'dark' : 'light';
+    const host = document.querySelector('#focus-chart');
+    view?.finalize(); // 1. finalize the old view first — frees its listeners/RAF (see below)
+    host.replaceChildren(); // 2. clear the host — re-embedding into a non-empty node stacks SVGs
+    const res = await vegaEmbed(host, spec, {
+      config: brontoVegaConfig(theme),
+      renderer: 'svg',
+      actions: false,
+    });
+    view = res.view;
+  };
+  document.querySelector('#theme-toggle').addEventListener('click', () => {
+    root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+    renderChart(); // 2. re-render on every flip — the baked SVG does not follow CSS
+  });
+  renderChart();
+</script>
+```
+
+Four foot-guns, each verified while dogfooding:
+
+- **Finalize the previous view before re-embedding.** `vegaEmbed` resolves to
+  `{ view }`; a Vega view registers event listeners and an animation frame loop
+  that `replaceChildren()` does **not** unwind. Call `view.finalize()` on the
+  prior view before each re-render (as above), or a report that toggles theme
+  repeatedly leaks a view per toggle.
+- **Clear the host before re-embedding.** vega-embed appends; embedding twice
+  into the same node stacks a second chart under the first. `replaceChildren()`
+  (or `host.innerHTML = ''`) first.
+- **Avoid `width: 'container'` if the chart can be re-rendered while hidden.** A
+  container-sized Vega chart measures its parent at embed time; if that parent is
+  `display: none` (a collapsed section, an inactive tab) it measures `0` and
+  renders empty. Give the spec an explicit `width`, or re-embed when the section
+  becomes visible.
+- **Mermaid: don't `innerHTML = svg` over the source.** `mermaid.render()`
+  returns the SVG string — write it to a *separate* mount, not back into the
+  `<pre class="mermaid">` that still holds the diagram source, or a re-theme has
+  nothing to re-render from. Keep the source and the rendered output in different
+  nodes.
+
+For a report you will only ever **print/PDF**, skip all of this: render once in
+the target theme, or use the frozen inline `<svg>` route, which has no runtime.
+
 ## Common templates
 
 - Executive brief: compact cover, one summary block, KPI `ui-statgrid`, short
@@ -259,8 +582,9 @@ style itself.
 
 ## Print and PDF
 
-The supported export target is modern Chromium print/PDF. Two ways to produce
-the file:
+The supported export target is modern Chromium print/PDF. A bronto report is
+static and zero-JS, so producing the PDF is just _load → print_ — you do not
+need a full automatable browser, only a Chromium-class layout+print pass.
 
 - **By hand:** open the report in Chrome/Edge → Print (Cmd/Ctrl+P) → "Save as
   PDF". In **More settings**, enable **Background graphics** (the dialog's
@@ -268,13 +592,45 @@ the file:
   out), and pick the paper size there. Paper size is a browser print setting,
   not a token; the layer only themes the page _margin_ via
   `--report-page-margin`.
-- **Headless (agents/CI):** `await page.pdf({ format: 'A4', printBackground: true })`
-  with Playwright or Puppeteer.
-
-The report prints ink-on-white regardless of the on-screen theme. Older
+- **Headless, lightweight:** use **`chrome-headless-shell`** — the minimal
+  headless-Chromium binary built for exactly this, a fraction of a full
+  browser's weight. Drive it through Playwright/Puppeteer (or raw CDP) and
+  always pass `printBackground: true`, or chart fills and legend swatches drop
+  out:
+
+  ```js
+  import { chromium } from 'playwright'; // or puppeteer
+  const browser = await chromium.launch({ channel: 'chromium-headless-shell' });
+  const page = await browser.newPage();
+  await page.goto('file:///abs/path/report.html', { waitUntil: 'networkidle' });
+  await page.pdf({ path: 'report.pdf', format: 'A4', printBackground: true });
+  await browser.close();
+  ```
+
+  Install the binary with `npx playwright install chromium-headless-shell`
+  (Puppeteer ships its own). The repo's `scripts/render-pdf.mjs` is a working
+  copy of this (`npm run report:pdf -- report.html`); it is a dev/example
+  helper, not part of the published API — bronto does not own rendering.
+- **As a service / from another language:** run Chromium-as-a-service
+  (e.g. **Gotenberg**'s `POST /forms/chromium/convert/html`, or a hosted CDP
+  endpoint) and POST the HTML + the `dist/css/*` assets. A Python/Go/any host
+  then needs no local browser. This is the natural fit for reports generated
+  by an LLM or service in another system.
+
+The report prints ink-on-white regardless of the on-screen theme. The chart
+fills and swatches carry `print-color-adjust: exact`, but the engine still
+needs background printing enabled (`printBackground: true` headless, or
+"Background graphics" by hand). The bare `chrome --headless --print-to-pdf`
+CLI flag does **not** print backgrounds — use the scripted CDP/`page.pdf()`
+path above for any report with charts.
+
+A browserless engine (WeasyPrint, Prince, …) can work for text-and-table
+reports if you feed it the **unlayered** CSS (`@ponchia/ui/css/unlayered/*` —
+no `@layer`) and resolve colours from `tokens/resolved.json`; but `:has()` and
+modern paged-media are not universally supported, so charts and edge cases may
+degrade. For faithful output, stay on a Chromium-class engine. Older
 HTML-to-PDF engines are not part of the browser floor and may not support
-cascade layers, `oklch()`, `color-mix()`, `:has()`, or modern paged-media
-behavior.
+cascade layers, `oklch()`, `color-mix()`, `:has()`, or modern paged-media.
 
 - Use `ui-print-only` for content that should appear only in print.
 - Use `ui-screen-only` for navigation or helper content that should not print.
@@ -296,7 +652,10 @@ fake page numbers with inert markup.
 
 Before returning a report, an LLM should verify:
 
-- All `ui-*` classes exist in `@ponchia/ui/classes`.
+- All `ui-*` classes exist in `@ponchia/ui/classes` (or `classes/classes.json`).
+  The `is-*` state hooks (`is-num`/`is-pos`/`is-neg`/`is-key` in `.ui-table`
+  cells and `.ui-stat` deltas, `is-open`/`is-active`) are valid but live
+  outside `cls` by design — keep them.
 - The document has one `h1`, ordered headings, and a single main report region.
 - Tables have captions and header cells.
 - Charts have captions, direct labels or legends, and fallback data.

package/docs/sidenote.md

@@ -0,0 +1,64 @@
+# Sidenote
+
+`@ponchia/ui/css/sidenote.css` is an opt-in **margin-note** grammar in the Tufte
+tradition — the channel for evidence, caveats, and provenance asides that belong
+*beside* the prose, not interrupting it. `ui-sidenote` is numbered;
+`ui-marginnote` is the unnumbered variant.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sidenote.css';
+```
+
+## How it behaves
+
+- **Wide viewports** (≥ 60rem) float the note into the inline-end margin.
+- **Narrow viewports** collapse it to an indented inline block right after its
+  anchor, so nothing is lost on a phone or in a narrow column.
+- **Numbering** is a CSS counter — no host bookkeeping.
+
+## Wiring — two things the host owns
+
+1. **Where numbering restarts.** Put `counter-reset: ui-sidenote` on the article
+   (or a section) so the count starts at 1 there.
+2. **The margin gutter.** At the same breakpoint, give that container
+   `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))` so the
+   floated note has room. `--sidenote-width` defaults to `12rem`.
+
+```html
+<article style="counter-reset: ui-sidenote">
+  <p>
+    The migration cut p95 latency by 38%<label class="ui-sidenote__ref"></label>.
+    <span class="ui-sidenote">
+      Measured over the first 24h after rollout; see the incident review §4.
+    </span>
+    The error budget held<span class="ui-marginnote">No paging events fired.</span>.
+  </p>
+</article>
+```
+
+The `.ui-sidenote__ref` renders the superscript number and increments the
+counter; place the `.ui-sidenote` immediately after it in the DOM so it reads
+the same number.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-sidenote` | A numbered margin note. |
+| `.ui-marginnote` | An unnumbered margin note (no `__ref`). |
+| `.ui-sidenote__ref` | The inline superscript anchor; increments + prints the number. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--sidenote-width` | `.ui-sidenote` / `.ui-marginnote` | Floated width on wide viewports (default `12rem`). |
+| `--sidenote-gap` | same | Gap between the text column and the note (default `2rem`). |
+
+## Accessibility & robustness
+
+- The note is **real DOM in reading order**, so a screen reader encounters it
+  right after the anchor — no off-screen trickery.
+- On narrow viewports the note is always visible (an indented block with an
+  inline-start rule), so there is no hidden-content trap.
+- Keep the note's meaning in its text; the number is a wayfinding aid, not the
+  content.

package/docs/sources.md

@@ -31,6 +31,29 @@ the only one.
 | Stale | `ui-src--stale` | warning |
 | Conflict | `ui-src--conflict` | danger |
 
+A trust-state class **needs a host element** — on its own a tone class
+(`ui-src--verified` and the rest) only sets a `--src-tone`, it does not draw
+anything. The host is one of the elements below, or the standalone `.ui-src`
+pill.
+
+## Standalone trust pill — `.ui-src`
+
+When you just need a bare labelled chip (a row of provenance tags, an inline
+"verified" badge) with no surrounding card or citation, use `.ui-src` as the
+host and add a tone. It draws a small pill with a leading trust dot:
+
+```html
+<span class="ui-src ui-src--verified">Verified</span>
+<span class="ui-src ui-src--generated">AI-generated</span>
+<span class="ui-src ui-src--stale">Stale · 14d</span>
+```
+
+The base `.ui-src` is required — `<span class="ui-src--verified">` alone
+**validates against `classes.json` but renders nothing**, because the tone class
+only carries the colour for a host to consume. The word inside is the channel
+(WCAG 1.4.1); the dot and tint are reinforcement. Reach for `.ui-citation--chip`
+instead when the pill is a real link/button to the source.
+
 ## Inline citation — `.ui-citation`
 
 A reference marker on a real `<a>` or `<button>` (the visual index is never the
@@ -64,6 +87,10 @@ A single source preview: title, origin, time, excerpt, actions. The
 </article>
 ```
 
+The parts are `__title`, `__origin`, `__time`, `__excerpt` (the body text — not
+`__detail`/`__body`), and `__actions`. A card nests inside a
+`ui-source-list__item` when it sits in a references section (below).
+
 ## Source list — `.ui-source-list`
 
 A references section: a reset list of source cards (or rows).