@ponchia/ui 0.6.4 → 0.6.6

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 540 classes across 167 component groups
+- 593 classes across 171 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
   vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
@@ -330,6 +330,24 @@ each one matches a real selector in the stylesheet.
 | `cls.citation` | `ui-citation` | base |
 | `cls.citationChip` | `ui-citation--chip` | modifier |
 
+### `.ui-claim`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.claim` | `ui-claim` | base |
+| `cls.claimBasis` | `ui-claim__basis` | part |
+| `cls.claimCaveat` | `ui-claim__caveat` | part |
+| `cls.claimLimits` | `ui-claim__limits` | part |
+| `cls.claimRefs` | `ui-claim__refs` | part |
+| `cls.claimScope` | `ui-claim__scope` | part |
+| `cls.claimStatement` | `ui-claim__statement` | part |
+| `cls.claimStatus` | `ui-claim__status` | part |
+| `cls.claimDisputed` | `ui-claim--disputed` | modifier |
+| `cls.claimPartial` | `ui-claim--partial` | modifier |
+| `cls.claimSupported` | `ui-claim--supported` | modifier |
+| `cls.claimUnknown` | `ui-claim--unknown` | modifier |
+| `cls.claimUnsupported` | `ui-claim--unsupported` | modifier |
+
 ### `.ui-cluster`
 
 | Registry key | Class | Kind |
@@ -557,6 +575,33 @@ each one matches a real selector in the stylesheet.
 | `cls.errorSummaryList` | `ui-error-summary__list` | part |
 | `cls.errorSummaryTitle` | `ui-error-summary__title` | part |
 
+### `.ui-evidence-grid`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.evidenceGrid` | `ui-evidence-grid` | base |
+
+### `.ui-evidence-item`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.evidenceItem` | `ui-evidence-item` | base |
+| `cls.evidenceItemBody` | `ui-evidence-item__body` | part |
+| `cls.evidenceItemCaveat` | `ui-evidence-item__caveat` | part |
+| `cls.evidenceItemKind` | `ui-evidence-item__kind` | part |
+| `cls.evidenceItemMeta` | `ui-evidence-item__meta` | part |
+| `cls.evidenceItemMethod` | `ui-evidence-item__method` | part |
+| `cls.evidenceItemSource` | `ui-evidence-item__source` | part |
+| `cls.evidenceItemTitle` | `ui-evidence-item__title` | part |
+| `cls.evidenceItemValue` | `ui-evidence-item__value` | part |
+| `cls.evidenceItemWindow` | `ui-evidence-item__window` | part |
+
+### `.ui-evidence-ledger`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.evidenceLedger` | `ui-evidence-ledger` | base |
+
 ### `.ui-eyebrow`
 
 | Registry key | Class | Kind |
@@ -939,13 +984,41 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.report` | `ui-report` | base |
+| `cls.reportAction` | `ui-report__action` | part |
+| `cls.reportActionCriteria` | `ui-report__action-criteria` | part |
+| `cls.reportActionDue` | `ui-report__action-due` | part |
+| `cls.reportActionOwner` | `ui-report__action-owner` | part |
+| `cls.reportActionPriority` | `ui-report__action-priority` | part |
+| `cls.reportActionSource` | `ui-report__action-source` | part |
+| `cls.reportActionStatus` | `ui-report__action-status` | part |
+| `cls.reportActionTitle` | `ui-report__action-title` | part |
+| `cls.reportActions` | `ui-report__actions` | part |
 | `cls.reportAppendix` | `ui-report__appendix` | part |
 | `cls.reportCaption` | `ui-report__caption` | part |
 | `cls.reportCover` | `ui-report__cover` | part |
 | `cls.reportCoverCompact` | `ui-report__cover--compact` | modifier |
+| `cls.reportDecision` | `ui-report__decision` | part |
+| `cls.reportDecisionBody` | `ui-report__decision-body` | part |
+| `cls.reportDecisionGrid` | `ui-report__decision-grid` | part |
+| `cls.reportDecisionItem` | `ui-report__decision-item` | part |
+| `cls.reportDecisionKicker` | `ui-report__decision-kicker` | part |
+| `cls.reportDecisionLabel` | `ui-report__decision-label` | part |
+| `cls.reportDecisionMeta` | `ui-report__decision-meta` | part |
+| `cls.reportDecisionTitle` | `ui-report__decision-title` | part |
+| `cls.reportDecisionValue` | `ui-report__decision-value` | part |
 | `cls.reportEvidence` | `ui-report__evidence` | part |
 | `cls.reportFigure` | `ui-report__figure` | part |
 | `cls.reportFinding` | `ui-report__finding` | part |
+| `cls.reportFindingCritical` | `ui-report__finding--critical` | modifier |
+| `cls.reportFindingMajor` | `ui-report__finding--major` | modifier |
+| `cls.reportFindingMinor` | `ui-report__finding--minor` | modifier |
+| `cls.reportFindingResolved` | `ui-report__finding--resolved` | modifier |
+| `cls.reportFindingCaveat` | `ui-report__finding-caveat` | part |
+| `cls.reportFindingClaim` | `ui-report__finding-claim` | part |
+| `cls.reportFindingEvidence` | `ui-report__finding-evidence` | part |
+| `cls.reportFindingImpact` | `ui-report__finding-impact` | part |
+| `cls.reportFindingRemediation` | `ui-report__finding-remediation` | part |
+| `cls.reportFindingTitle` | `ui-report__finding-title` | part |
 | `cls.reportFootnotes` | `ui-report__footnotes` | part |
 | `cls.reportHead` | `ui-report__head` | part |
 | `cls.reportMeta` | `ui-report__meta` | part |
@@ -1472,7 +1545,7 @@ works in any framework without a binding layer:
 - **Opt-in component CSS** — a few classes are not in the core bundle and need
   their leaf imported, or they render unstyled: `ui-property`/`ui-readout` →
   `@ponchia/ui/css/workbench.css`; `ui-mark`/`ui-bracket-note` →
-  `@ponchia/ui/css/marks.css`; the analytical leaves (`ui-annotations`,
+  `@ponchia/ui/css/marks.css`; the analytical leaves (`ui-annotation`,
   `ui-crosshair`, `ui-spotlight`, …) → their matching leaf.
 - **Loaders need their children** — `ui-dotspinner` requires exactly eight
   `<i>` children, `ui-dotloader` three `<span>`, and a static `ui-dotbar`

package/docs/reporting.md

@@ -37,11 +37,11 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -59,8 +59,11 @@ sanitize that content before rendering it and do not initialize
 `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:
+the default bundle — add the leaves a given report actually needs.
+`@ponchia/ui/css/analytical.css` is a convenience roll-up of the **seven
+figure-layer leaves only** (annotations, legends, marks, connectors, spotlight,
+crosshair, selection) — sources, generated, state, and the prose/evidence
+leaves below are NOT in it and must be linked individually. Reach for:
 
 | Layer | Import | Reach for it when… |
 | --- | --- | --- |
@@ -72,6 +75,16 @@ whole set with `@ponchia/ui/css/analytical.css`. Reach for:
 | **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). |
+| **Spark** (`.ui-spark*`) | `css/spark.css` | A trend belongs _inside a sentence or table cell_ — a word-sized inline microchart, the inline counterpart to `ui-delta`/`ui-num`/`ui-stat`. See [spark.md](./spark.md). |
+| **Bullet graph** (`.ui-bullet*`) | `css/bullet.css` | A measure needs "inside budget? vs target?" at a glance — the canonical SLO / error-budget figure that `ui-meter` structurally cannot express. See [bullet.md](./bullet.md). |
+| **Diff** (`.ui-diff*`) | `css/diff.css` | The report shows what _changed_ — code review, changelogs, version history, config diffs. Marks call out a sentence; diff calls out a line. See [diff.md](./diff.md). |
+| **Code** (`.ui-code*`) | `css/code.css` | Code-as-evidence: fenced snippets with an optional gutter and add/remove/highlight line states, sharing diff's change vocabulary. On-brand syntax colours via the [Shiki theme](./code.md). See [code.md](./code.md). |
+| **Sidenotes** (`.ui-sidenote`, `.ui-marginnote`) | `css/sidenote.css` | Evidence, caveats, and provenance asides that belong _beside_ the prose, Tufte-style, instead of interrupting it. See [sidenote.md](./sidenote.md). |
+| **Textref** (`.ui-textref`) | `css/textref.css` | A citation should deep-link to the _exact quoted sentence_ (URL text fragments, on-brand `::target-text` paint) — the inline counterpart to the source-card layer. See [textref.md](./textref.md). |
+| **Term / glossary** (`.ui-term`, `.ui-glossary`) | `css/term.css` | Jargon should explain itself inline (native popover definition) and gather into an end-of-report glossary. See [term.md](./term.md). |
+| **Contents rail** (`.ui-toc*`) | `css/toc.css` | A long report needs a sticky table of contents with the in-view section highlighted; degrades to a plain anchored list with zero JS. Distinct from the in-flow `ui-report__toc` block. See [toc.md](./toc.md). |
+| **Tree** (`.ui-tree*`) | `css/tree.css` | Nested structure — file trees, object graphs, nested provenance — as a depth-indented outline on native `<details>`. See [tree.md](./tree.md). |
+| **Dot surfaces** (`.ui-waffle`, `.ui-activity`, `.ui-level`, `.ui-dotgauge`, `.ui-readout`, …) | _(in the core bundle)_ | A count, rate, level, or gauge wants the library's signature dot-matrix expression — waffle units, activity strips, dot gauges, readouts. See [dots.md](./dots.md). |
 
 These compose with the report-native primitives already called out in
 [Composition rules](#composition-rules): `ui-statgrid`, `ui-alert`, `ui-table`,
@@ -106,6 +119,24 @@ they are all safe in the static, PDF-first report path.
     <div class="ui-report__summary">
       <p>The summary block is for the decision-level conclusion.</p>
     </div>
+    <aside class="ui-report__decision" aria-labelledby="decision-title">
+      <p class="ui-report__decision-kicker">Decision</p>
+      <h3 class="ui-report__decision-title" id="decision-title">Ship the low-risk path</h3>
+      <p class="ui-report__decision-body">
+        State the operator-facing call first, then list the evidence below it.
+      </p>
+      <dl class="ui-report__decision-grid">
+        <div class="ui-report__decision-item">
+          <dt class="ui-report__decision-label">Basis</dt>
+          <dd class="ui-report__decision-value">Two verified sources support the call.</dd>
+        </div>
+        <div class="ui-report__decision-item">
+          <dt class="ui-report__decision-label">Next action</dt>
+          <dd class="ui-report__decision-value">Owner rechecks the remaining caveat by Jun 8.</dd>
+        </div>
+      </dl>
+      <p class="ui-report__decision-meta">Evidence state: supported · Checked: 2026-06-01</p>
+    </aside>
     <div class="ui-statgrid">
       <div class="ui-stat">
         <span class="ui-stat__label">Open risks</span>
@@ -127,6 +158,147 @@ they are all safe in the static, PDF-first report path.
 </main>
 ```
 
+## Report-specific primitives
+
+Use these report-layer primitives before inventing custom card layouts. They are
+generic, static, and PDF-safe; the host still owns the content, scoring, source
+fetching, and claim wording.
+
+- `ui-report__decision` is the above-the-fold call. Pair it with
+  `ui-report__decision-kicker`, `ui-report__decision-title`,
+  `ui-report__decision-body`, optional `ui-report__decision-grid` /
+  `ui-report__decision-item` detail rows, and optional
+  `ui-report__decision-meta`. It should answer "what should the reader do or
+  believe now?" before the deep evidence. Good rows are basis, impact, next
+  action, owner, recheck date, and evidence state.
+- `ui-report__finding` is the repeated finding block. Add
+  `ui-report__finding--critical`, `--major`, `--minor`, or `--resolved` only
+  when the written finding label also states the severity/status. The colour
+  band is a scanning aid, not the data of record. For dense reports, use
+  `ui-report__finding-title`, `ui-report__finding-claim`,
+  `ui-report__finding-impact`, `ui-report__finding-remediation`,
+  `ui-report__finding-evidence`, and `ui-report__finding-caveat` so impact,
+  evidence, caveat, and remediation do not collapse into one paragraph.
+- `ui-claim` is the smallest claim/evidence contract. Use
+  `ui-claim--supported`, `--partial`, `--disputed`, `--unsupported`, or
+  `--unknown` only when the written `ui-claim__status` says the same thing.
+  Use `ui-claim__statement`, `__scope`, `__basis`, `__limits`, `__refs`, and
+  `__caveat` to show what the report asserts, where it applies, what supports
+  it, what would limit or change it, and which sources/evidence entries it maps
+  to.
+- `ui-evidence-grid` and `ui-evidence-item` are for compact evidence packets:
+  one source, check, observation, counterexample, or assumption per item. Use
+  `ui-evidence-item__title`, `__meta`, and `__body` for simple cards; add
+  `__kind`, `__method`, `__window`, `__value`, `__source`, and `__caveat` when
+  the evidence needs to say how it was gathered. Link to source cards or a table
+  when the evidence is more than a sentence.
+- `ui-evidence-ledger` is a wrapper for a claim/evidence/source matrix. Put a
+  normal `ui-table` inside it with columns such as claim, evidence, source,
+  trust, freshness, relation, and caveat.
+- `ui-report__actions`, `ui-report__action`, and
+  `ui-report__action-status` are for follow-up rows in status, incident, and
+  audit reports. Add `ui-report__action-title`, `__action-owner`,
+  `__action-due`, `__action-priority`, `__action-criteria`, and
+  `__action-source` when the action is a real workflow item. The status text
+  must be written out; do not rely on tone alone.
+
+Decision brief pattern:
+
+```html
+<aside class="ui-report__decision" aria-labelledby="decision-title">
+  <p class="ui-report__decision-kicker">Decision</p>
+  <h3 class="ui-report__decision-title" id="decision-title">Adopt the safer option</h3>
+  <p class="ui-report__decision-body">
+    The current evidence supports the lower-risk path while the disputed source is rechecked.
+  </p>
+  <dl class="ui-report__decision-grid">
+    <div class="ui-report__decision-item">
+      <dt class="ui-report__decision-label">Basis</dt>
+      <dd class="ui-report__decision-value">Verified metrics support the call; one source is stale.</dd>
+    </div>
+    <div class="ui-report__decision-item">
+      <dt class="ui-report__decision-label">Recheck</dt>
+      <dd class="ui-report__decision-value"><time datetime="2026-06-08">2026-06-08</time></dd>
+    </div>
+  </dl>
+  <p class="ui-report__decision-meta">Evidence state: partial · Sources: 4 · Checked: 2026-06-01</p>
+</aside>
+```
+
+Finding + evidence pattern:
+
+```html
+<article class="ui-report__finding ui-report__finding--major" aria-labelledby="finding-cache">
+  <p class="ui-eyebrow" id="finding-cache">Major finding — cache pressure is rising</p>
+  <p class="ui-report__finding-claim">
+    Claim: cache pressure is rising during the refresh window.
+  </p>
+  <p class="ui-report__finding-impact">Impact: p95 latency is likely to breach target if volume rises.</p>
+  <p class="ui-report__finding-remediation">Remediation: lower the refresh batch size before the next rollout.</p>
+  <p class="ui-report__finding-caveat">
+    Caveat: the conclusion assumes comparable traffic shape in the next window.
+  </p>
+</article>
+<div class="ui-evidence-grid" aria-label="Evidence summary">
+  <article class="ui-evidence-item">
+    <h3 class="ui-evidence-item__title">Metric trend</h3>
+    <p class="ui-evidence-item__kind">Observation</p>
+    <p class="ui-evidence-item__meta">Prometheus · 24 h window</p>
+    <p class="ui-evidence-item__body">p95 latency rose 18% while request volume stayed flat.</p>
+  </article>
+  <article class="ui-evidence-item">
+    <h3 class="ui-evidence-item__title">Log sample</h3>
+    <p class="ui-evidence-item__meta">Application logs · reviewed</p>
+    <p class="ui-evidence-item__body">Timeouts cluster around cache refresh intervals.</p>
+  </article>
+</div>
+```
+
+Claim block pattern:
+
+```html
+<article class="ui-claim ui-claim--partial" id="claim-latency">
+  <p class="ui-claim__statement">The migration improved latency without reducing availability.</p>
+  <p class="ui-claim__status">Evidence state: partial</p>
+  <p class="ui-claim__scope">Scope: last 7 days, production traffic only</p>
+  <p class="ui-claim__basis">Basis: metrics export S1 and incident note S2 support the claim.</p>
+  <p class="ui-claim__limits">Limit: retry volume still needs a separate review.</p>
+  <p class="ui-claim__refs">Sources: <a class="ui-citation" href="#source-metrics">S1</a></p>
+</article>
+```
+
+Evidence ledger pattern:
+
+```html
+<div class="ui-evidence-ledger">
+  <div class="ui-table-wrap">
+    <table class="ui-table ui-table--dense">
+      <caption>Claim, evidence, and caveat ledger</caption>
+      <thead>
+        <tr>
+          <th>Claim</th>
+          <th>Evidence</th>
+          <th>Source</th>
+          <th>Trust</th>
+          <th>Relation</th>
+          <th>Caveat</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><a href="#claim-latency">Latency improved</a></td>
+          <td>p95 fell 48 ms</td>
+          <td><a class="ui-citation" href="#source-metrics">S1</a></td>
+          <td>Verified</td>
+          <td>Supports</td>
+          <td>Last 7 days only</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</div>
+```
+
 ## Composition rules
 
 - Use `ui-report` as the page-level wrapper. Add `ui-report--numbered` when
@@ -150,6 +322,12 @@ they are all safe in the static, PDF-first report path.
   `ui-alert` for persistent notices, `ui-table` for structured evidence,
   `ui-timeline` for events, `ui-meter` for measured values, and `ui-num` for
   non-table numeric values.
+- Put a `ui-report__decision` near the start of decision reports, audits, and
+  incident reviews. If the report is intentionally exploratory and has no
+  decision yet, say so in the summary instead of leaving the reader to infer it.
+- Use severity modifiers on `ui-report__finding` only for scanability. The
+  label should still include the severity/status in text, for example
+  "Major finding — …" or "Resolved finding — …".
 - In alerts, put the readable message in `<p class="ui-alert__body">…</p>`
   and use `ui-alert__title` only for a separate title line. `ui-alert` is a
   grid with a leading status dot; raw text or loose inline children such as
@@ -579,14 +757,100 @@ 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
-  findings, and sources.
-- Research brief: compact header, decision frame, evidence table, quotes or
-  prose excerpts, and sources.
-- Incident review: compact cover, summary, `ui-timeline`, corrective-action
-  evidence table, and footnotes.
-- Project status: compact header, KPI `ui-statgrid`, chart figure with fallback
-  data, print-only notes, and unnumbered appendix.
+- Executive brief: compact cover, above-fold reader outcome, KPI
+  `ui-statgrid`, short findings, evidence-state disclosure, and sources.
+- Decision report: decision frame, options considered, chosen option, rationale,
+  tradeoffs, revisit trigger, next actions, evidence ledger, and sources.
+- Research brief: compact header, scope/method block, claim cards, evidence
+  table, quotes or prose excerpts, limitations, and sources.
+- Incident review: compact cover, impact summary, `ui-timeline`, root-cause
+  claim, corrective-action register, evidence ledger, and footnotes.
+- Audit: summary, finding cards with severity in text, evidence/caveat rows,
+  remediation owner/due dates, accepted risk, and sources.
+- Project status: compact header, KPI `ui-statgrid`, current state, blocked
+  decisions, action register, chart figure with fallback data, print-only notes,
+  and unnumbered appendix.
+
+Minimum blocks by report type:
+
+| Type | Required shape |
+| --- | --- |
+| Executive | Summary, above-fold outcome, evidence-state disclosure, source cards. |
+| Decision | Decision frame, options/tradeoffs, claim cards, evidence ledger, next actions, sources. |
+| Research | Scope/method, explicit claims, evidence table, limitations, sources. |
+| Primer | Scope, teaching sequence, key claims, examples, caveats, sources. |
+| Incident | Impact, root-cause claim, timeline, evidence ledger, corrective actions, footnotes. |
+| Audit | Severity-labelled findings, evidence/caveat rows, remediation owners/dates, accepted risk, sources. |
+| Status | Current state, risks/blockers, decision requests, action register, recheck timing, sources. |
+
+## Semantic contract
+
+The report layer is not a fact checker, but it should make a report's reasoning
+auditable. A useful report separates:
+
+- **Reader outcome** — what the reader should do or believe now.
+- **Claim** — the actual assertion, with scope and evidence state.
+- **Evidence** — observation, metric, log, quote, sample, method, assumption,
+  counterevidence, or limitation.
+- **Source** — where the evidence came from, with trust/freshness written in
+  text.
+- **Action** — who does what next, by when, and how completion is checked.
+
+Use inline citations and stable IDs to connect those layers:
+
+```html
+<article class="ui-claim ui-claim--supported" id="claim-1" data-source-ids="source-metrics">
+  <p class="ui-claim__statement">Availability remained above target.</p>
+  <p class="ui-claim__status">Evidence state: supported</p>
+  <p class="ui-claim__refs">Source: <a class="ui-citation" href="#source-metrics">S1</a></p>
+</article>
+
+<article class="ui-source-card ui-src--verified" id="source-metrics">
+  <h3 class="ui-source-card__title">Metrics export</h3>
+  <p class="ui-source-card__origin">Verified operational export</p>
+</article>
+```
+
+If a claim is generated, inferred, stale, disputed, or uncited, say so near the
+claim, not only in the source appendix. Do not use a numeric confidence widget
+unless the number has a real model, sample, or scoring method behind it.
+
+Generator-side tools should keep a machine-readable claim/source sidecar beside
+important reports. The HTML stays the readable artifact; the sidecar lets a
+checker prove that claim IDs, source IDs, trust states, retrieval dates and
+high-risk decisions still line up after editing.
+
+```json
+{
+  "schemaVersion": "bronto-report-claims.v1",
+  "report": { "title": "Decision readiness", "type": "decision" },
+  "claims": [
+    {
+      "id": "claim-primary",
+      "status": "supported",
+      "risk": "medium",
+      "statement": "The guarded option reduces operational risk.",
+      "scope": "Current release window",
+      "sourceIds": ["source-primary"]
+    }
+  ],
+  "sources": [
+    {
+      "id": "source-primary",
+      "state": "verified",
+      "title": "Release metrics export",
+      "origin": "Verified operational export",
+      "retrievedAt": "2026-06-08T10:00:00Z",
+      "supports": ["claim-primary"]
+    }
+  ]
+}
+```
+
+For source archives, keep the same source IDs and add any available immutable
+handles: URL, artifact path, content hash, retrieval timestamp, collection
+method and caveats. A report is more useful when the source appendix, inline
+citations, evidence ledger and sidecar all name the same IDs.
 
 ## Print and PDF
 
@@ -594,6 +858,11 @@ 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.
 
+Chromium's generated PDF is a visual/export artifact, not a tagged accessible
+PDF. Keep the HTML report as the accessible artifact unless the host application
+adds a separate tagged-PDF pipeline and verifies it with PDF accessibility
+tooling.
+
 - **By hand:** open the report in Chrome/Edge → Print (Cmd/Ctrl+P) → "Save as
   PDF". In **More settings**, enable **Background graphics** (the dialog's
   equivalent of `printBackground` — without it chart fills and swatches drop
@@ -620,6 +889,14 @@ need a full automatable browser, only a Chromium-class layout+print pass.
   (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.
+
+  **If the report renders figures from `<script type="module">`, do not load
+  it over `file://`** — browsers block relative module imports from `file://`
+  (CORS, opaque `null` origin), so the figures silently render empty in the
+  PDF. Serve the report over HTTP first; `render-pdf.mjs --serve` does this
+  (loopback server + load over `http://127.0.0.1`), waits for the report's
+  `data-report-ready` signal if it sets one, and logs page errors instead of
+  swallowing them.
 - **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
@@ -666,6 +943,19 @@ Before returning a report, an LLM should verify:
   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.
+- The report type is clear: executive, decision, research, incident, audit,
+  primer, or status. The above-fold block answers what the reader should do or
+  believe now, unless the report explicitly says it is exploratory.
+- Every decision, major finding, quantitative claim, and recommendation has a
+  nearby citation, claim block, evidence packet, evidence ledger row, or an
+  explicit assumption/uncited/generated label.
+- Claim/source sidecars, when present, resolve every claim ID and source ID back
+  to visible HTML. High-risk claims have at least one verified or reviewed
+  source.
+- Stale, conflicting, unverified, or generated inputs are surfaced near the
+  affected claim or decision, not buried only in the source appendix.
+- Actions that represent real follow-up include owner, due/recheck date, status,
+  and success criteria, or explicitly say why those fields are unassigned.
 - Tables have captions and header cells.
 - Charts have captions, direct labels or legends, and fallback data.
 - No raw chromatic colors appear in inline styles.

package/docs/sources.md

@@ -102,6 +102,35 @@ A references section: a reset list of source cards (or rows).
 </ol>
 ```
 
+## Optional behavior — `initSources`
+
+When you want citations to jump back to their source cards with a visible focus
+cue, wrap the report or article in `data-bronto-sources` and initialize the
+behavior:
+
+```html
+<main data-bronto-sources>
+  <p>Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.</p>
+  <article id="s1" class="ui-source-card ui-src--verified">…</article>
+</main>
+
+<script type="module">
+  import { initSources } from '@ponchia/ui/behaviors';
+  const stop = initSources();
+</script>
+```
+
+`initSources()` is progressive enhancement over authored IDs. It resolves
+`.ui-citation[href^="#"]` and `[data-bronto-source-ref]` controls inside each
+`[data-bronto-sources]` island, adds preview metadata (`title` and
+`aria-describedby`) when the author did not already provide it, and activation
+focuses the matching source card with a temporary `.is-source-active` highlight.
+It emits `bronto:source:focus` with `{ id, citation, source }`.
+
+The host still owns fetching, numbering, permission checks, trust decisions, and
+any rich preview popover. Generated/static reports can stay behavior-free:
+hash-link navigation and `.ui-source-card:target` still provide a CSS-only cue.
+
 ## Provenance — `.ui-provenance`
 
 A compact metadata row beside generated content — each `__item` carries a trust
@@ -130,6 +159,9 @@ ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"
 
 - A citation must be a real link or button with a stable accessible name; the
   bracketed index alone is not enough.
+- `initSources()` is optional. Initialize it only on trusted markup; the
+  delegated `data-bronto-source-ref` / `href="#…"` relationships focus elements
+  inside the source island.
 - The trust state must be readable as text — the tone dot/border is decorative
   reinforcement. Under `forced-colors`, dots and borders fall back to
   `CanvasText`, so the label remains the channel.

package/docs/stability.md

@@ -1,12 +1,15 @@
 # Public API Stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.5.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.6.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
 patches, or `^0.x` only if you accept minor-level churn. This policy holds
 until `1.0.0` is tagged. This matrix defines what counts as public API.
+For the exhaustive package-manifest inventory — every `exports` key, every
+shipped `files` entry, and the generated artifact provenance map — see
+[package-contract.md](./package-contract.md).
 
 | Surface | Stability | Contract |
 | --- | --- | --- |
@@ -18,7 +21,7 @@ until `1.0.0` is tagged. This matrix defines what counts as public API.
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
 | Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
-| Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. (A computed-style smoke test guards the OLED `--bg` flip; the others are unverified.) |
+| Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. Computed-style smoke tests guard that the presets apply to their intended token families. |
 | Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
 | Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
 | Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
@@ -35,7 +38,7 @@ until `1.0.0` is tagged. This matrix defines what counts as public API.
 | Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
 | Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
 | Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the seven analytical leaves (annotations, legend, marks, connectors, spotlight, crosshair, selection). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
-| Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
+| Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`, `initSources`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), the optional `data-bronto-sources` / `data-bronto-source-ref` behavior contract, `bronto:source:focus`, and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
 | Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
 | Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
 | Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |