@ponchia/ui 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -5,6 +5,112 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.6.6 — 2026-06-10
+
+Consolidation pass from the 2026-06-10 multi-agent audit: two real PDF-export
+defects fixed and gated, the reporting hub routed to every shipped leaf, and
+the drift-prone hand lists in the gates derived from registries. No breaking
+changes, no `MIGRATIONS.json` entry.
+
+### Fixed
+
+- **Print overprint (the big one)** — Chromium-class print engines restart
+  grid tracks at each page break, printing new rows over the running content.
+  `css/report.css` `@media print` now demotes the vertical document-flow
+  wrappers (`.ui-report`, `__section`, `__figure`, `__actions`,
+  `.ui-evidence-ledger`) to block flow with margin-emulated gaps; the column
+  grids (`.ui-compare`, `.ui-meter__row`, `.ui-report__decision-item`,
+  `.ui-evidence-grid`) keep their tracks. Gated by a promoted multi-page
+  fixture (`test/e2e/_report-print.fixture.html`) whose PDF is parsed with
+  pdfjs-dist and asserted overlap-free (`test/e2e/report-print.spec.mjs`).
+- **Silent module-figure drop in PDFs** — reports that render figures from
+  relative `<script type="module">` imports lose them over `file://` (CORS).
+  `scripts/render-pdf.mjs` gains `--serve` (loopback HTTP + the report's
+  `data-report-ready` signal), forwards page/console errors to stderr, and
+  warns when a module report is rendered over `file://`.
+- **Demo class drift** — `demo/index.html` still used the renamed
+  `ui-inspector__header` (now `__head`), and `demo/version-history-report.html`
+  carried a never-registered cover-mark class; both were silent no-ops. The
+  generated reference's analytical-leaves note now names `ui-annotation`
+  (singular, the real class).
+- `scripts/smoke-example.mjs` imports Chromium from `@playwright/test` (the
+  installed devDependency) instead of the hoisting-dependent bare
+  `playwright` specifier.
+
+### Added
+
+- **Reporting hub routing** — `docs/reporting.md`'s analytical-toolbox table
+  now routes ALL report-relevant leaves (spark, bullet, diff, code, sidenote,
+  textref, term, glossary, contents rail, tree, dot surfaces) and states
+  precisely what `analytical.css` does and does not bundle. New convention in
+  CONTRIBUTING: a new report-relevant leaf ships in the same PR as its
+  routing row.
+- **`npm run release:prep -- X.Y.Z`** — one-shot release prep: version + lock
+  bump, CHANGELOG heading dating, and re-pinning every `@ponchia/ui@X.Y.Z`
+  literal across the gated shipped docs AND the ungated `demo/*.html` pages
+  (which had already drifted a version behind).
+- **Cross-engine e2e on merge-to-main** — pushes to `main` that touch
+  engine-sensitive surfaces (`css/`, `dist/`, `behaviors/`, `fonts/`,
+  `tokens/`, `test/e2e/`, the Playwright config) now run the firefox/webkit
+  pass too, instead of deferring it to the release tag.
+- **`demo/dots.html`** — the dot data surfaces (waffle, activity, level,
+  dotgauge, readout, spark--dots, halftone, dotfit) get a specimen page,
+  axe/guard coverage in `demos.spec`, and render-geometry boundingBox
+  assertions (their only possible executable gate — they ship no JS).
+- jsdom coverage for `initDisabledGuard` (activation blocking, Tab
+  pass-through, root scoping, cleanup).
+
+### Changed
+
+- `check:report` and `check:pack` derive their scan/entrypoint lists from
+  registries (`package.json` `files`/`exports` via `scripts/lib/css-leaves.mjs`
+  + `lib/shipped-docs.mjs`) instead of hand lists that had drifted behind the
+  post-0.6.0 leaves. The broadened scan immediately caught the demo/reference
+  class defects above. `core.css` imports are now closed over an explicit
+  CORE_BUNDLE allowlist in both directions.
+- `ROADMAP.md` / `docs/frontier-primitives.md` reconciled to 0.6.5: the
+  report/provenance/explanation lane is named the proven core; ui-job,
+  ui-conflict, ui-splitter, the tree roving-focus kernel, and
+  command/workbench follow-ons are explicitly dormant until a real app
+  consumer exists; the 2026-06-09 scout keeps (ui-interval, ui-clamp,
+  ui-highlights) are recorded as report-lane candidates gated behind the
+  routing hub. The adoption stance is stated in ROADMAP.
+
+## 0.6.5 — 2026-06-09
+
+Patch release: the source-backref behavior, the report decision/evidence
+grammar, and package/release hardening. No breaking changes, no
+`MIGRATIONS.json` entry.
+
+### Added
+
+- **`initSources` behavior** — optional citation→source backref focus:
+  inside a `data-bronto-sources` host, a `.ui-citation[href^="#"]` (or an
+  explicit `data-bronto-source-ref`) click scrolls to its source card and
+  marks it `is-source-active`, emitting a cancellable focus event with the
+  `SourceFocusDetail` payload. Progressive enhancement over authored ids —
+  no DOM is generated; framework bindings re-export it.
+- **Report decision/evidence grammar** — adds public, static report primitives
+  for decision blocks, severity-labelled findings, compact evidence packets and
+  follow-up action rows.
+- **Claim and action-register grammar** — adds claim status blocks, structured
+  finding parts, evidence-method parts, evidence ledgers, decision detail rows,
+  and action owner/due/criteria/source parts for more auditable reports.
+- **Package contract doc** — `docs/package-contract.md` pins the published
+  surface (exports map, files allowlist, generated-artifact freshness) that
+  `check:pack`/`check:publint`/`check:attw` enforce.
+
+### Changed
+
+- **Report fixtures and local guardrails** — expands the standalone and full
+  report demos with source/provenance examples, SVG accessibility details and a
+  local-only public-boundary terms gate for `check:report`.
+- **Report shape checks** — `check:report` now parses report demos with a DOM
+  instead of regexes and validates the public claim/action contracts.
+- **Release observability** — the release workflow gains a metadata gate and
+  theme-axis verification; the examples consumer build broadens its smoke
+  coverage.
+
 ## 0.6.4 — 2026-06-08
 
 Patch release for the dot-matrix expansion and static report hardening shipped

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~76kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~87kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
@@ -22,9 +22,16 @@ SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text
 marks, a colourblind-safe data-viz palette, and a static/PDF report grammar — for
 dashboards and LLM-authored reports.
 
-### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
+### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Static report →](https://ponchia.github.io/bronto-ui/demo/report-standalone.html)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
 The demo is the kitchen sink — every component, light/dark, RTL, live theming.
+The static report is the differentiator in one file: a complete, no-build,
+no-JS, Chromium-PDF-ready report built from the report grammar.
+
+<p>
+  <img alt="A research report built with the @ponchia/ui report layer" src="https://raw.githubusercontent.com/Ponchia/bronto-ui/main/demo/_preview-report-research.png" width="49%" />
+  <img alt="The same report grammar printed to PDF" src="https://raw.githubusercontent.com/Ponchia/bronto-ui/main/demo/_preview-report-print.png" width="49%" />
+</p>
 
 ---
 
@@ -57,7 +64,7 @@ Or drop it in with no build step, straight from a CDN:
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~76 kB raw / ~13 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~87 kB raw / ~15 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -102,9 +109,9 @@ initDialog();        // native <dialog> glue: [data-bronto-open] / [data-bronto-
 toast('Saved', { tone: 'success' });   // body-anchored stack, no markup needed
 ```
 
-Behaviors cover theme persistence, disclosure, dropdown menus, native-`<dialog>` modals/drawers, tabs, combobox, form validation, table sort, carousel and toasts — wired by `data-bronto-*` attributes.
+Behaviors cover theme persistence, disclosure, dropdown menus, native-`<dialog>` modals/drawers, tabs, combobox, form validation, table sort, carousel, source backrefs and toasts — wired by `data-bronto-*` attributes.
 
-**5. (Optional) display glyphs — a 48-glyph dot-matrix icon set:**
+**5. (Optional) display glyphs — a 71-glyph dot-matrix icon set:**
 
 ```js
 import { renderGlyph } from '@ponchia/ui/glyphs';
@@ -126,9 +133,9 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
 - **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
-- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, sections, findings, evidence, figures, chart wrappers and print utilities.
+- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, figures, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
-- **Glyphs** — `@ponchia/ui/glyphs`, a 48-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
+- **Glyphs** — `@ponchia/ui/glyphs`, a 71-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
 - **Colorways** _(opt-in)_ — `data-bronto-skin="amber-crt | phosphor-green | e-ink"`: a root-level recolour of the one accent (OKLCH, per-theme, contrast-gated), never in the default bundle.
 - **Data-viz** _(opt-in)_ — a colourblind-safe chart palette (`--chart-*` + dot-matrix pattern fills, resolved hex in `charts.json`), gated under simulated protan/deutan/tritan vision. Charts only, never UI chrome.
 
@@ -173,13 +180,13 @@ Per-framework getting-started guides + runnable example apps live in the repo:
 
 - **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` — concrete hex per theme for canvas/SVG/MapLibre).
 - **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json' with { type: 'json' }` in Node ESM, or the same path through a bundler JSON import (resolved hex per theme; series 1 = your accent) plus the opt-in `@ponchia/ui/css/dataviz.css`.
-- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
+- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure, claim/evidence/action grammar, source-card bindings, and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
 - **Modern-platform motion** — overlays (modal/drawer/popover), toasts and the `<details>` accordion animate **in and out** with zero JS (`@starting-style` + `allow-discrete`, `::details-content` + `interpolate-size`). Progressive-enhancement extras: `.ui-scroll-progress` / `.ui-scroll-reveal` (scroll-driven, no JS) and `.ui-vt` for View Transitions. All degrade to a static end-state and respect `prefers-reduced-motion`. For smooth **cross-document** navigations, add the document-global one-liner to your own top-level (unlayered) CSS: `@view-transition { navigation: auto; }`.
 - **Editor IntelliSense** — point VS Code at the shipped custom-data file so every token autocompletes in `var(--…)`:
   ```json
   { "css.customData": ["node_modules/@ponchia/ui/classes/vscode.css-custom-data.json"] }
   ```
-- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
+- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, `docs/package-contract.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
 
 > The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, and `/charts`.
 > JS subpaths are **ESM-only**. CommonJS consumers should use dynamic
@@ -193,7 +200,7 @@ Recent-evergreen, by design. The framework targets the modern web platform — c
 
 Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.6.0` (and equivalently `^0.6.0`) resolves to `>=0.6.0 <0.7.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
 
-Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the full public-surface matrix.
+Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the semantic public-surface matrix and **[docs/package-contract.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/package-contract.md)** for the generated export/file/provenance inventory.
 
 Release candidates publish to the `next` dist-tag, never to `latest` — opt in with `npm i @ponchia/ui@next` to try an upcoming version early. A plain `npm i @ponchia/ui` only ever resolves a stable release.
 

package/behaviors/index.d.ts

@@ -17,6 +17,7 @@ export { initConnectors } from "./connectors.js";
 export { initSpotlight } from "./spotlight.js";
 export { initCrosshair } from "./crosshair.js";
 export { initCommand } from "./command.js";
+export { initSources } from "./sources.js";
 export type Cleanup = import("./internal.js").Cleanup;
 export type DelegateOpts = import("./internal.js").DelegateOpts;
 export type ThemeStorageOpts = import("./theme.js").ThemeStorageOpts;
@@ -27,5 +28,6 @@ export type ModalCloseDetail = import("./modal.js").ModalCloseDetail;
 export type LegendToggleDetail = import("./legend.js").LegendToggleDetail;
 export type CrosshairMoveDetail = import("./crosshair.js").CrosshairMoveDetail;
 export type CommandSelectDetail = import("./command.js").CommandSelectDetail;
+export type SourceFocusDetail = import("./sources.js").SourceFocusDetail;
 export { applyStoredTheme, initThemeToggle } from "./theme.js";
 //# sourceMappingURL=index.d.ts.map

package/behaviors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;sBAmBa,OAAO,eAAe,EAAE,OAAO;2BAC/B,OAAO,eAAe,EAAE,YAAY;+BACpC,OAAO,YAAY,EAAE,gBAAgB;6BACrC,OAAO,YAAY,EAAE,cAAc;gCACnC,OAAO,YAAY,EAAE,iBAAiB;wBACtC,OAAO,YAAY,EAAE,SAAS;+BAC9B,OAAO,YAAY,EAAE,gBAAgB;iCACrC,OAAO,aAAa,EAAE,kBAAkB;kCACxC,OAAO,gBAAgB,EAAE,mBAAmB;kCAC5C,OAAO,cAAc,EAAE,mBAAmB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;sBAmBa,OAAO,eAAe,EAAE,OAAO;2BAC/B,OAAO,eAAe,EAAE,YAAY;+BACpC,OAAO,YAAY,EAAE,gBAAgB;6BACrC,OAAO,YAAY,EAAE,cAAc;gCACnC,OAAO,YAAY,EAAE,iBAAiB;wBACtC,OAAO,YAAY,EAAE,SAAS;+BAC9B,OAAO,YAAY,EAAE,gBAAgB;iCACrC,OAAO,aAAa,EAAE,kBAAkB;kCACxC,OAAO,gBAAgB,EAAE,mBAAmB;kCAC5C,OAAO,cAAc,EAAE,mBAAmB;gCAC1C,OAAO,cAAc,EAAE,iBAAiB"}

package/behaviors/index.js

@@ -27,6 +27,7 @@
  * @typedef {import('./legend.js').LegendToggleDetail} LegendToggleDetail
  * @typedef {import('./crosshair.js').CrosshairMoveDetail} CrosshairMoveDetail
  * @typedef {import('./command.js').CommandSelectDetail} CommandSelectDetail
+ * @typedef {import('./sources.js').SourceFocusDetail} SourceFocusDetail
  */
 export { applyStoredTheme, initThemeToggle } from './theme.js';
 export { dismissible } from './dismissible.js';
@@ -48,3 +49,4 @@ export { initConnectors } from './connectors.js';
 export { initSpotlight } from './spotlight.js';
 export { initCrosshair } from './crosshair.js';
 export { initCommand } from './command.js';
+export { initSources } from './sources.js';

package/behaviors/sources.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Source/citation affordances for the `sources.css` trust layer. The behavior
+ * is deliberately small: within each `[data-bronto-sources]` island it resolves
+ * `.ui-citation[href^="#"]` and `[data-bronto-source-ref]` controls to source
+ * cards, adds non-visual preview metadata (`title` + `aria-describedby`), and
+ * on activation moves focus to the source card with a temporary
+ * `.is-source-active` highlight. The host still owns fetching, numbering,
+ * trust decisions, and any rich preview UI.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initSources({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type SourceFocusDetail = {
+    /**
+     * The focused source-card id.
+     */
+    id: string;
+    /**
+     * The citation/control that requested the source.
+     */
+    citation: Element;
+    /**
+     * The target source card or source element.
+     */
+    source: Element;
+};
+//# sourceMappingURL=sources.d.ts.map

package/behaviors/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["sources.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;GAWG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAwG3C;;;;;QAjJa,MAAM;;;;cACN,OAAO;;;;YACP,OAAO"}

package/behaviors/sources.js

@@ -0,0 +1,158 @@
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  byIdInHost,
+  collectHosts,
+  scrollIntoViewSafe,
+} from './internal.js';
+
+/**
+ * @typedef {object} SourceFocusDetail
+ * @property {string} id The focused source-card id.
+ * @property {Element} citation The citation/control that requested the source.
+ * @property {Element} source The target source card or source element.
+ */
+
+const REF_SELECTOR = '[data-bronto-source-ref], .ui-citation[href^="#"]';
+const ACTIVE = 'is-source-active';
+
+function sourceId(ref) {
+  const explicit = ref.getAttribute('data-bronto-source-ref');
+  if (explicit) return explicit.replace(/^#/, '');
+  const href = ref.getAttribute('href') || '';
+  if (!href.startsWith('#') || href === '#') return '';
+  try {
+    return decodeURIComponent(href.slice(1));
+  } catch {
+    return href.slice(1);
+  }
+}
+
+function sourcePreview(source) {
+  const text = (selector) =>
+    source.querySelector(selector)?.textContent?.replace(/\s+/g, ' ').trim() || '';
+  const title = text('.ui-source-card__title');
+  const meta = [text('.ui-source-card__origin'), text('.ui-source-card__time')]
+    .filter(Boolean)
+    .join(' · ');
+  const excerpt = text('.ui-source-card__excerpt');
+  return [title, meta, excerpt].filter(Boolean).join(' — ');
+}
+
+/**
+ * Source/citation affordances for the `sources.css` trust layer. The behavior
+ * is deliberately small: within each `[data-bronto-sources]` island it resolves
+ * `.ui-citation[href^="#"]` and `[data-bronto-source-ref]` controls to source
+ * cards, adds non-visual preview metadata (`title` + `aria-describedby`), and
+ * on activation moves focus to the source card with a temporary
+ * `.is-source-active` highlight. The host still owns fetching, numbering,
+ * trust decisions, and any rich preview UI.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initSources({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+
+  const islands = collectHosts(host, '[data-bronto-sources]');
+  const cleanups = [];
+
+  for (const island of islands) {
+    const timers = new Set();
+    const seeded = [];
+
+    const targetFor = (ref) => {
+      const id = sourceId(ref);
+      if (!id) return null;
+      return byIdInHost(island, id);
+    };
+
+    const seed = () => {
+      for (const ref of island.querySelectorAll(REF_SELECTOR)) {
+        const source = targetFor(ref);
+        if (!source?.id) continue;
+
+        const describedBy = ref.getAttribute('aria-describedby') || '';
+        const describedIds = describedBy.split(/\s+/).filter(Boolean);
+        const title = ref.getAttribute('title');
+        const preview = sourcePreview(source);
+        const prior = {
+          ref,
+          describedBy,
+          hadDescribedBy: ref.hasAttribute('aria-describedby'),
+          title,
+          hadTitle: ref.hasAttribute('title'),
+        };
+
+        if (!describedIds.includes(source.id)) {
+          ref.setAttribute('aria-describedby', [...describedIds, source.id].join(' '));
+        }
+        if (!title && preview) ref.setAttribute('title', preview);
+        if (!source.hasAttribute('tabindex')) {
+          prior.source = source;
+          prior.hadTabindex = false;
+          source.setAttribute('tabindex', '-1');
+        }
+        seeded.push(prior);
+      }
+    };
+
+    const focusSource = (ref, source) => {
+      for (const card of island.querySelectorAll(`.${ACTIVE}`)) card.classList.remove(ACTIVE);
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+
+      source.classList.add(ACTIVE);
+      source.focus?.({ preventScroll: true });
+      scrollIntoViewSafe(source);
+
+      const timer = setTimeout(() => {
+        source.classList.remove(ACTIVE);
+        timers.delete(timer);
+      }, 1600);
+      timers.add(timer);
+
+      island.dispatchEvent(
+        new CustomEvent('bronto:source:focus', {
+          detail: { id: source.id, citation: ref, source },
+          bubbles: true,
+        }),
+      );
+    };
+
+    const onClick = (e) => {
+      const ref = e.target.closest?.(REF_SELECTOR);
+      if (!ref || !island.contains(ref)) return;
+      const source = targetFor(ref);
+      if (!source) return;
+      if (!ref.matches('a[href]')) e.preventDefault();
+      focusSource(ref, source);
+    };
+
+    const cleanup = bindOnce(island, 'sources', () => {
+      seed();
+      island.addEventListener('click', onClick);
+      return () => {
+        island.removeEventListener('click', onClick);
+        for (const timer of timers) clearTimeout(timer);
+        timers.clear();
+        for (const item of seeded.splice(0)) {
+          if (item.hadDescribedBy) item.ref.setAttribute('aria-describedby', item.describedBy);
+          else item.ref.removeAttribute('aria-describedby');
+          if (item.hadTitle) item.ref.setAttribute('title', item.title);
+          else item.ref.removeAttribute('title');
+          if (item.source && item.hadTabindex === false) item.source.removeAttribute('tabindex');
+        }
+        for (const card of island.querySelectorAll(`.${ACTIVE}`)) card.classList.remove(ACTIVE);
+      };
+    });
+
+    cleanups.push(cleanup);
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 540,
-    "groups": 167
+    "classes": 593,
+    "groups": 171
   },
   "groups": {
     "ui-accordion": {
@@ -303,6 +303,25 @@
       ],
       "parts": []
     },
+    "ui-claim": {
+      "base": "ui-claim",
+      "modifiers": [
+        "ui-claim--disputed",
+        "ui-claim--partial",
+        "ui-claim--supported",
+        "ui-claim--unknown",
+        "ui-claim--unsupported"
+      ],
+      "parts": [
+        "ui-claim__basis",
+        "ui-claim__caveat",
+        "ui-claim__limits",
+        "ui-claim__refs",
+        "ui-claim__scope",
+        "ui-claim__statement",
+        "ui-claim__status"
+      ]
+    },
     "ui-cluster": {
       "base": "ui-cluster",
       "modifiers": [
@@ -526,6 +545,31 @@
         "ui-error-summary__title"
       ]
     },
+    "ui-evidence-grid": {
+      "base": "ui-evidence-grid",
+      "modifiers": [],
+      "parts": []
+    },
+    "ui-evidence-item": {
+      "base": "ui-evidence-item",
+      "modifiers": [],
+      "parts": [
+        "ui-evidence-item__body",
+        "ui-evidence-item__caveat",
+        "ui-evidence-item__kind",
+        "ui-evidence-item__meta",
+        "ui-evidence-item__method",
+        "ui-evidence-item__source",
+        "ui-evidence-item__title",
+        "ui-evidence-item__value",
+        "ui-evidence-item__window"
+      ]
+    },
+    "ui-evidence-ledger": {
+      "base": "ui-evidence-ledger",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-eyebrow": {
       "base": "ui-eyebrow",
       "modifiers": [
@@ -894,15 +938,43 @@
         "ui-report--compact",
         "ui-report--numbered",
         "ui-report__cover--compact",
+        "ui-report__finding--critical",
+        "ui-report__finding--major",
+        "ui-report__finding--minor",
+        "ui-report__finding--resolved",
         "ui-report__section--unnumbered"
       ],
       "parts": [
+        "ui-report__action",
+        "ui-report__action-criteria",
+        "ui-report__action-due",
+        "ui-report__action-owner",
+        "ui-report__action-priority",
+        "ui-report__action-source",
+        "ui-report__action-status",
+        "ui-report__action-title",
+        "ui-report__actions",
         "ui-report__appendix",
         "ui-report__caption",
         "ui-report__cover",
+        "ui-report__decision",
+        "ui-report__decision-body",
+        "ui-report__decision-grid",
+        "ui-report__decision-item",
+        "ui-report__decision-kicker",
+        "ui-report__decision-label",
+        "ui-report__decision-meta",
+        "ui-report__decision-title",
+        "ui-report__decision-value",
         "ui-report__evidence",
         "ui-report__figure",
         "ui-report__finding",
+        "ui-report__finding-caveat",
+        "ui-report__finding-claim",
+        "ui-report__finding-evidence",
+        "ui-report__finding-impact",
+        "ui-report__finding-remediation",
+        "ui-report__finding-title",
         "ui-report__footnotes",
         "ui-report__head",
         "ui-report__meta",
@@ -1469,6 +1541,19 @@
     "ui-chip--accent",
     "ui-citation",
     "ui-citation--chip",
+    "ui-claim",
+    "ui-claim--disputed",
+    "ui-claim--partial",
+    "ui-claim--supported",
+    "ui-claim--unknown",
+    "ui-claim--unsupported",
+    "ui-claim__basis",
+    "ui-claim__caveat",
+    "ui-claim__limits",
+    "ui-claim__refs",
+    "ui-claim__scope",
+    "ui-claim__statement",
+    "ui-claim__status",
     "ui-cluster",
     "ui-cluster--between",
     "ui-code",
@@ -1566,6 +1651,18 @@
     "ui-error-summary",
     "ui-error-summary__list",
     "ui-error-summary__title",
+    "ui-evidence-grid",
+    "ui-evidence-item",
+    "ui-evidence-item__body",
+    "ui-evidence-item__caveat",
+    "ui-evidence-item__kind",
+    "ui-evidence-item__meta",
+    "ui-evidence-item__method",
+    "ui-evidence-item__source",
+    "ui-evidence-item__title",
+    "ui-evidence-item__value",
+    "ui-evidence-item__window",
+    "ui-evidence-ledger",
     "ui-eyebrow",
     "ui-eyebrow--muted",
     "ui-eyebrow--sm",
@@ -1706,13 +1803,41 @@
     "ui-report",
     "ui-report--compact",
     "ui-report--numbered",
+    "ui-report__action",
+    "ui-report__action-criteria",
+    "ui-report__action-due",
+    "ui-report__action-owner",
+    "ui-report__action-priority",
+    "ui-report__action-source",
+    "ui-report__action-status",
+    "ui-report__action-title",
+    "ui-report__actions",
     "ui-report__appendix",
     "ui-report__caption",
     "ui-report__cover",
     "ui-report__cover--compact",
+    "ui-report__decision",
+    "ui-report__decision-body",
+    "ui-report__decision-grid",
+    "ui-report__decision-item",
+    "ui-report__decision-kicker",
+    "ui-report__decision-label",
+    "ui-report__decision-meta",
+    "ui-report__decision-title",
+    "ui-report__decision-value",
     "ui-report__evidence",
     "ui-report__figure",
     "ui-report__finding",
+    "ui-report__finding--critical",
+    "ui-report__finding--major",
+    "ui-report__finding--minor",
+    "ui-report__finding--resolved",
+    "ui-report__finding-caveat",
+    "ui-report__finding-claim",
+    "ui-report__finding-evidence",
+    "ui-report__finding-impact",
+    "ui-report__finding-remediation",
+    "ui-report__finding-title",
     "ui-report__footnotes",
     "ui-report__head",
     "ui-report__meta",
@@ -1908,6 +2033,12 @@
       "scope": ".ui-tab and other selectable items",
       "effect": "active/selected state"
     },
+    {
+      "class": "is-source-active",
+      "scope": ".ui-source-card",
+      "effect": "temporary source highlight after a citation/backref activation",
+      "managed": "runtime"
+    },
     {
       "class": "is-inactive",
       "scope": "interactive .ui-legend__item",
@@ -2378,6 +2509,19 @@
       "behavior": "initCommand",
       "note": "wires the filter input + active-option keyboard model"
     },
+    {
+      "name": "data-bronto-sources",
+      "on": "a source/citation island",
+      "behavior": "initSources",
+      "note": "scopes citation preview metadata and source-card focus/highlight behavior; the host still owns numbering, fetching, and trust decisions."
+    },
+    {
+      "name": "data-bronto-source-ref",
+      "on": "a button/control that references a source card",
+      "value": "id of the source card, with or without a leading #",
+      "behavior": "initSources",
+      "note": "button/control equivalent of a .ui-citation[href=\"#source-id\"]; activation focuses and highlights the referenced source."
+    },
     {
       "name": "data-bronto-dismiss",
       "on": "a button",