@ponchia/ui 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -5,6 +5,59 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 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
+in #116. No breaking changes, no `MIGRATIONS.json` entry.
+
+### Added
+
+- **Dot-matrix/glyph expansion** — adds the generated glyph metadata surface,
+  docs, and contract tests for the expanded dot/readout vocabulary.
+- **Report authoring guidance** — documents the static report grammar around
+  captions, alert bodies, table wrapping, and local/CDN asset handling.
+
+### Fixed
+
+- **Static report print/layout behavior** — hardens report print margins and
+  table wrapping so standalone HTML reports and PDF exports degrade more
+  predictably across long tokens and normal prose.
+
 ## 0.6.3 — 2026-06-08
 
 Patch release to publish the WebKit release fix after the `v0.6.1` and `v0.6.2`

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)
@@ -57,7 +57,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,7 +102,7 @@ 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:**
 
@@ -126,7 +126,7 @@ 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).
 - **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.
@@ -173,13 +173,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 +193,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/glyph.d.ts

@@ -7,6 +7,13 @@
  * name is left untouched. Idempotent (skips an already-expanded host); the
  * returned cleanup removes the cells and restores the original attributes.
  *
+ * `data-bronto-glyph-render="mask"` takes the cheap one-node path instead:
+ * the host becomes a single `.ui-icon` masked by the glyph (no GLYPH_SIZE²
+ * cells), inheriting `currentColor` and scaling with the text — the DOM
+ * counterpart to renderGlyph's `render: 'mask'`, for an icon in every table
+ * row where 256 cells per glyph is too heavy. `data-bronto-glyph-size` sets
+ * `--icon-size`. The cell-mode attributes (solid/anim) don't apply.
+ *
  * @param {import('./internal.js').DelegateOpts} [opts]
  * @returns {import('./internal.js').Cleanup}
  */

package/behaviors/glyph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glyph.d.ts","sourceRoot":"","sources":["glyph.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;GAWG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAiH3C"}
+{"version":3,"file":"glyph.d.ts","sourceRoot":"","sources":["glyph.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAyJ3C"}

package/behaviors/glyph.js

@@ -1,11 +1,18 @@
 import { hasDom, resolveHost, noop, collectHosts } from './internal.js';
-import { GLYPH_SIZE, glyphCells } from '../glyphs/glyphs.js';
+import { GLYPH_SIZE, glyphCells, glyphMask } from '../glyphs/glyphs.js';
 
 function restoreAttr(el, name, prev) {
   if (prev === null) el.removeAttribute(name);
   else el.setAttribute(name, prev);
 }
 
+// `dot`/`gap`/`size` land in inline CSS, so allow only length/calc syntax —
+// drop anything with a `;`/`{` that could open a second declaration (mirrors
+// glyphs.js cssLen). Used for the mask path's --icon-size.
+function cssLen(v) {
+  return v && /^[\w.%+\-*/()\s,]+$/.test(v) ? v : '';
+}
+
 /**
  * Expand `[data-bronto-glyph="name"]` placeholders into a `.ui-dotmatrix`
  * grid of GLYPH_SIZE² cells — the DOM counterpart to renderGlyph() from
@@ -15,6 +22,13 @@ function restoreAttr(el, name, prev) {
  * name is left untouched. Idempotent (skips an already-expanded host); the
  * returned cleanup removes the cells and restores the original attributes.
  *
+ * `data-bronto-glyph-render="mask"` takes the cheap one-node path instead:
+ * the host becomes a single `.ui-icon` masked by the glyph (no GLYPH_SIZE²
+ * cells), inheriting `currentColor` and scaling with the text — the DOM
+ * counterpart to renderGlyph's `render: 'mask'`, for an icon in every table
+ * row where 256 cells per glyph is too heavy. `data-bronto-glyph-size` sets
+ * `--icon-size`. The cell-mode attributes (solid/anim) don't apply.
+ *
  * @param {import('./internal.js').DelegateOpts} [opts]
  * @returns {import('./internal.js').Cleanup}
  */
@@ -26,14 +40,54 @@ export function initDotGlyph({ root } = {}) {
   const cleanups = [];
 
   for (const el of els) {
+    const name = el.getAttribute('data-bronto-glyph');
+    const label = el.getAttribute('data-bronto-glyph-label');
+
+    // One-node mask path — the icon-at-scale counterpart to the 256-cell grid.
+    if (el.getAttribute('data-bronto-glyph-render') === 'mask') {
+      if (el.classList.contains('ui-icon') && el.style.getPropertyValue('--icon-mask')) continue;
+      const mask = glyphMask(name);
+      if (!mask) continue; // unknown glyph — leave the placeholder as-is
+      const hadIcon = el.classList.contains('ui-icon');
+      const hadMask = el.style.getPropertyValue('--icon-mask');
+      const hadSize = el.style.getPropertyValue('--icon-size');
+      const hadAriaHiddenM = el.getAttribute('aria-hidden');
+      const hadRoleM = el.getAttribute('role');
+      const hadAriaLabelM = el.getAttribute('aria-label');
+      const sizeM = cssLen(el.getAttribute('data-bronto-glyph-size'));
+
+      el.classList.add('ui-icon');
+      el.style.setProperty('--icon-mask', mask);
+      if (sizeM) el.style.setProperty('--icon-size', sizeM);
+      if (label) {
+        el.setAttribute('role', 'img');
+        el.setAttribute('aria-label', label);
+        el.removeAttribute('aria-hidden');
+      } else {
+        el.setAttribute('aria-hidden', 'true');
+      }
+
+      cleanups.push(() => {
+        if (!hadIcon) el.classList.remove('ui-icon');
+        if (hadMask) el.style.setProperty('--icon-mask', hadMask);
+        else el.style.removeProperty('--icon-mask');
+        if (sizeM && !hadSize) el.style.removeProperty('--icon-size');
+        else if (hadSize) el.style.setProperty('--icon-size', hadSize);
+        restoreAttr(el, 'aria-hidden', hadAriaHiddenM);
+        restoreAttr(el, 'role', hadRoleM);
+        restoreAttr(el, 'aria-label', hadAriaLabelM);
+        if (el.getAttribute('class') === '') el.removeAttribute('class');
+        if (el.getAttribute('style') === '') el.removeAttribute('style');
+      });
+      continue;
+    }
+
     // Scope to DIRECT-child cells (the ones we append) — so a placeholder that
     // legitimately nests its own .ui-dotmatrix is neither mis-read as already
     // expanded here nor have its inner cells removed by cleanup below.
     if (el.querySelector(':scope > .ui-dotmatrix__cell')) continue; // already expanded
-    const cells = glyphCells(el.getAttribute('data-bronto-glyph'));
+    const cells = glyphCells(name);
     if (!cells.length) continue; // unknown glyph — leave the placeholder as-is
-
-    const label = el.getAttribute('data-bronto-glyph-label');
     // `data-bronto-glyph-solid` → square, gapless pixel glyph (legible small),
     // the DOM counterpart to renderGlyph's `solid` option. Implies glyph-only.
     const solid = el.hasAttribute('data-bronto-glyph-solid');

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());
+}