@ponchia/ui 0.6.6 → 0.6.8

package/docs/usage.md

@@ -191,6 +191,12 @@ destructive action).
 | toast    | transient, out-of-flow, system-initiated. Danger toasts route to an assertive live region; everything else polite. |
 | tooltip  | supplemental, hover/focus, never essential info (it's not announced reliably; don't hide required content in it). |
 
+For dismissible in-flow alerts, mark the host with `data-bronto-dismissible`,
+put `data-bronto-dismiss` on the close button, and wire `dismissible()` from
+`@ponchia/ui/behaviors`. With no attribute value, the button removes the nearest
+dismissible host; with a selector value, it removes the nearest matching
+ancestor and dispatches a cancelable `bronto:dismiss` event first.
+
 The CSS `ui-tooltip` is hover/focus-only and CSS can't wire it to assistive
 tech for you — associate the bubble with its trigger yourself, or it conveys
 nothing to a screen reader: give `.ui-tooltip__bubble` an `id`, point the
@@ -222,6 +228,8 @@ Both are a thin horizontal bar; they mean different things.
   zero bar — so the helper returns just `role="progressbar"` + `aria-busy="true"`
   (no `aria-valuenow`, no `--value`). Pair it with the class:
   `<div class={ui.progress({ indeterminate: true })} {...attrs.progress()}>`.
+  The segmented `.ui-dotbar` uses the same accessibility contract through
+  `attrs.dotbar(value)` or `attrs.dotbar()` for the indeterminate sweep.
 
 Rule of thumb: *something is happening* → progress; *something measures
 this much* → meter.
@@ -276,12 +284,14 @@ without it these widgets are unlabelled or unannounced:
 - **`ui-skiplink`** — keep it the first focusable element and point its `href`
   at the `id` of your main landmark.
 
-## App shell: the admin dashboard frame
+## App shell: the service frame
 
-`ui-app-shell` is a CSS-only two-column admin frame (sidebar rail + main
-column) that collapses to a single column with a horizontal rail below 880px —
-no behavior required. The nesting matters; the rail is `ui-app-rail` and the
-content side is `ui-app-main`:
+`ui-app-shell` is the default cross-service identity frame: a CSS-only
+two-column app shell (sidebar rail + main column) that collapses to a single
+column with a horizontal rail below 880px — no behavior required. Use it for
+ops tools, admin apps, internal services, generated dashboards, and any workflow
+surface that should feel like part of the same system. The nesting matters; the
+rail is `ui-app-rail` and the content side is `ui-app-main`:
 
 ```html
 <div class="ui-app-shell">
@@ -290,7 +300,9 @@ content side is `ui-app-main`:
     <nav class="ui-app-nav" aria-label="Primary">
       <span class="ui-app-nav__section">Main</span>
       <a href="/overview" aria-current="page">Overview</a>
-      <a href="/reports">Reports</a>
+      <a href="/jobs">Jobs</a>
+      <a href="/integrations">Integrations</a>
+      <a href="/settings">Settings</a>
     </nav>
     <div class="ui-app-rail__account">…</div>
   </aside>
@@ -310,6 +322,21 @@ Knobs: `--app-rail` sets the rail width (default 14rem); `ui-app-shell--full`
 drops the rail for a single-column app. `ui-app-nav` honours `aria-current="page"`
 (preferred) and the visual-only `.is-active`.
 
+Service composition checklist:
+
+- Start with `ui-app-shell`, `ui-app-rail`, `ui-app-nav`, `ui-app-main`,
+  `ui-app-topbar`, and `ui-app-content`.
+- Put brand and account identity in the rail; do not rebuild that frame per app.
+- Use `ui-app-toolbar` for filters/actions above a workflow surface.
+- Use `ui-app-panel` for grouped operational sections, not nested cards.
+- Use `ui-statgrid`/`ui-stat`, `ui-table`, `ui-field`, `ui-alert`, and
+  `ui-progress` inside panels; add opt-in `state.css` for `ui-state` lifecycle
+  labels.
+- Keep nav current state on `aria-current="page"` so the visual cue and AT cue
+  match.
+- Reach for opt-in `workbench.css` only when the service needs panes,
+  inspectors, or selected-object bulk actions.
+
 ## Menus: `data-bronto-menu` + `initMenu`
 
 A dropdown menu is a native `<details data-bronto-menu>` styled as
@@ -570,7 +597,9 @@ one of these a screen reader announces nothing while the user waits.
 carries the native `popover` attribute (never clipped by `overflow`/stacking);
 without it, it falls back to an `is-open` class that a clipping ancestor can cut
 off. Add `popover` to the panel for the robust path — the `is-open` form is a
-fallback, not the default to copy.
+fallback, not the default to copy. Placement flips to the roomier vertical side,
+keeps the panel on-screen, and scrolls tall content inside the available viewport
+space.
 
 It is a **non-modal** dialog by design: the panel gets `role="dialog"` and focus
 moves into it, but there is **no focus trap** and the rest of the page stays
@@ -591,7 +620,7 @@ HTML, print/PDF, and before any hydration:
 
 | Component | How it works without JS |
 | --- | --- |
-| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` (+ anchor positioning where supported) |
+| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` for short local labels |
 | Accordion | native `<details>` / `<summary>` |
 | Segmented control (`ui-segmented`) | `:has(input:checked)` over a radio group |
 | Scroll-reveal (`ui-scroll-reveal`) | scroll-driven animation, zero JS |
@@ -603,20 +632,25 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 
 | Component | Behavior | With the behavior absent |
 | --- | --- | --- |
+| Disclosure trigger (`[data-bronto-disclosure]`) | `initDisclosure` | a button with stale `aria-expanded`; the controlled panel never toggles |
 | Tabs (`ui-tabs`) | `initTabs` | **author panels visible** — ship `hidden` panels and if `initTabs` never runs the content is unreachable |
 | Combobox (`ui-combobox`) | `initCombobox` | a plain text input beside an unfiltered list |
 | Command palette (`ui-command`) | `initCommand` | a static, unfiltered list |
+| Splitter (`ui-splitter`) | `initSplitter` | fixed panes at the authored `--splitter-pos`; no keyboard/pointer resize or `aria-valuenow` updates |
 | Table sort/select (`[data-bronto-sortable]`) | `initTableSort` | a static table (still readable) |
 | Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
 | Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
-| Controlled modal (`ui-modal.is-open`) | `initModal` | no focus trap — provide one or use native `<dialog>` |
+| Controlled modal (`ui-modal.is-open`) | `initModal` | open skin only — no inert trap, focus-return, or Escape close signal |
 | Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
+| Dismissible alert/callout (`data-bronto-dismissible`) | `dismissible` | the close affordance is just a button; nothing is removed |
 | Toast | `toast()` | nothing — it is imperative-only |
 
 One cross-cutting guard, not tied to a single component:
 
 | Concern | Behavior | With the behavior absent |
 | --- | --- | --- |
+| Theme persistence before first paint | `applyStoredTheme` | the token layer follows OS preference until client code sets `data-theme`, so a stored preference can flash |
+| Theme toggle controls | `initThemeToggle` | the button is inert and does not persist `data-theme` |
 | `aria-disabled="true"` controls | `initDisabledGuard` | dimmed + pointer-inert via CSS, but still **keyboard**-activatable on Enter/Space (native `disabled` is already fully inert) |
 
 Rule of thumb: if a component needs ARIA-state sync, focus management, a keyboard
@@ -628,10 +662,10 @@ boundary of what CSS alone cannot do.
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*
 home for the little JS that genuinely needs scripting (theme persistence,
 disclosure, dialog glue, modal focus-trap, toast, combobox, form-validation,
-table-sort). Reach for it instead of reimplementing — every initializer is
-SSR-safe, idempotent, and returns a cleanup. If you find yourself writing focus
-management or `aria-expanded` toggling by hand, there is probably already
-a behavior for it.
+table-sort, splitter resizing). Reach for it instead of reimplementing — every
+initializer is SSR-safe, idempotent, and returns a cleanup. If you find yourself
+writing focus management, ARIA value sync, or `aria-expanded` toggling by hand,
+there is probably already a behavior for it.
 
 ## Re-brand obligations (the short version)
 

package/docs/vega.md

@@ -137,7 +137,7 @@ one chromatic default (series 1 / the lone mark), never the chrome:
 | `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
 
 The palette is the same CVD-safe, pattern-paired set documented in
-[theming](./theming.md#data-viz) — colour is never the sole channel. When a
+[theming](./theming.md#data-viz-palette) — colour is never the sole channel. When a
 series needs the redundant second channel, drive the mark's fill from the
 `--chart-pattern-*` tokens or pair a [legend](./legends.md) swatch.
 
@@ -237,8 +237,8 @@ contract**, so pin your Vega version and key off the data, not generated ids.
 
 bronto owns the theme config — gated structurally by `check:vega` (every colour
 slot resolves, both themes, no `var()` leaks, every `range.*` ramp populated),
-and separately a dev-only render-probe (`npm test`, via the `vega`/`vega-lite`
-dev deps) asserts the colours actually land on a rendered chart — and the
-annotation geometry. It does not own Vega's grammar, its rendering, or its internal SVG —
+and by the unit suite (`check:unit`, via the `vega`/`vega-lite` dev deps) which
+asserts the colours actually land on a rendered chart — and the annotation
+geometry. It does not own Vega's grammar, its rendering, or its internal SVG —
 those stay Vega's, and the chart is a documented composition, not a shipped
 runtime binding.

package/docs/workbench.md

@@ -1,29 +1,69 @@
-# Workbench — inspector, properties, selection bar
+# Workbench — split panes, inspector, properties, selection bar
 
 `@ponchia/ui/css/workbench.css` is an opt-in set of primitives for **real
-tools**: an inspector panel, property rows for a selected object, and a bar of
-actions on the current selection. Generic kits stop at cards/tables/forms, so
-every app builds its own half-consistent workbench. This is the low-risk CSS
-core — layout and affordances only.
+tools**: resizable split panes, an inspector panel, property rows for a selected
+object, and a bar of actions on the current selection. Generic kits stop at
+cards/tables/forms, so every app builds its own half-consistent workbench. This
+is the low-risk core — layout, resize affordance, and ARIA value sync.
 
 ```css
 @import '@ponchia/ui';
 @import '@ponchia/ui/css/workbench.css';
 ```
 
-Resizable split panes (a focusable ARIA window-splitter behavior) and drag
-handles are deliberately deferred until a consumer needs them. Not in the core
-bundle.
+```js
+import { initSplitter } from '@ponchia/ui/behaviors';
+
+initSplitter();
+```
+
+Not in the core bundle. Import the CSS leaf where the workbench appears and run
+`initSplitter()` only if the page includes `[data-bronto-splitter]`.
+
+## Splitter — `.ui-splitter`
+
+Two panes separated by a focusable ARIA separator handle. The CSS owns the grid
+tracks and handle affordance; `initSplitter()` owns keyboard/pointer resizing,
+`--splitter-pos`, `aria-valuenow`, and the `bronto:splitter:resize` event. The
+host owns pane content, persistence, saved layout state, collapse policy, and any
+domain selection model.
+
+```html
+<div
+  class="ui-splitter ui-splitter--vertical"
+  data-bronto-splitter
+  style="--splitter-pos: 36%"
+>
+  <section class="ui-splitter__pane" id="files" aria-label="Files">...</section>
+  <div
+    class="ui-splitter__handle"
+    role="separator"
+    tabindex="0"
+    aria-controls="files"
+    aria-label="Resize files pane"
+    aria-orientation="vertical"
+    aria-valuemin="20"
+    aria-valuemax="72"
+    aria-valuenow="36"
+  ></div>
+  <section class="ui-splitter__pane" aria-label="Preview">...</section>
+</div>
+```
+
+Use `.ui-splitter--horizontal` for top/bottom panes. Arrow keys change the value
+by 2 percentage points, Shift+Arrow and PageUp/PageDown by 10, and Home/End jump
+to `aria-valuemin` / `aria-valuemax`. The handle needs a real accessible name
+and `aria-controls` pointing at the primary pane.
 
 ## Inspector — `.ui-inspector`
 
-A panel of details for the selected object: a `__header` (title + actions) over
+A panel of details for the selected object: a `__head` (title + actions) over
 a `__body` of property rows.
 
 ```html
 <aside class="ui-inspector">
   <div class="ui-inspector__head">
-    <h2 class="ui-eyebrow">Rectangle</h2>
+    <h2 class="ui-eyebrow">Sync job</h2>
     <button class="ui-button ui-button--subtle ui-button--sm" type="button">Reset</button>
   </div>
   <div class="ui-inspector__body">
@@ -39,12 +79,12 @@ A label/value pair, denser than `ui-key-value` and tuned for an inspector. The
 
 ```html
 <div class="ui-property">
-  <span class="ui-property__label">Width</span>
-  <span class="ui-property__value">240 px</span>
+  <span class="ui-property__label">Owner</span>
+  <span class="ui-property__value">Platform</span>
 </div>
 <div class="ui-property">
-  <span class="ui-property__label">Fill</span>
-  <span class="ui-property__value"><input class="ui-input" value="#121212" /></span>
+  <span class="ui-property__label">Retries</span>
+  <span class="ui-property__value"><input class="ui-input" value="3" /></span>
 </div>
 ```
 
@@ -72,7 +112,8 @@ A raised bar of actions on the current selection: a `__count` on one side,
 
 ## Scope
 
-CSS only, no recipes — these are structural containers and rows; apply the
-classes directly (or read them from `cls.inspector`, `cls.property`, …). Pair
-the selection bar with the cross-cutting [`ui-sel`](./selection.md) states on the
-selected items themselves; Bronto styles both, the host owns the hit-testing.
+No recipes — these are structural containers and rows; apply the classes
+directly (or read them from `cls.splitter`, `cls.inspector`, `cls.property`, …).
+Pair the selection bar with the cross-cutting [`ui-sel`](./selection.md) states
+on the selected items themselves. Bronto styles both and wires the splitter
+affordance; the host owns hit-testing, persistence, pane contents, and commands.

package/llms.txt

@@ -44,7 +44,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand
@@ -84,13 +84,17 @@ matching `.ui-source-card`, seed lightweight preview metadata, and emit
 `bronto:source:focus`; the host still owns numbering, fetching, trust decisions,
 and any rich preview popover.
 
-For React/Solid/Qwik, optional thin hook bindings over those behaviors (peer
-deps `react` / `solid-js` / `@builder.io/qwik`, optional — core stays zero-dep):
+Optional lifecycle adapters wrap those behaviors without owning markup or state.
+React/Solid/Qwik use hook bindings (peer deps `react` / `solid-js` /
+`@builder.io/qwik`, optional — core stays zero-dep); Svelte uses dependency-free
+actions, and Vue uses dependency-free directives/plugin helpers:
 
 ```js
 import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid' or '@ponchia/ui/qwik'
 // React: scope with { root: reactRef } or a resolver, not { root: ref.current } during render.
 // Qwik: hooks run in useVisibleTask$; scope with a Qwik signal — useDialog({ root: useSignal() }).
+// Svelte: import { dialog, toast } from '@ponchia/ui/svelte'.
+// Vue: import { vDialog, useToast } from '@ponchia/ui/vue', or app.use(brontoVue).
 ```
 
 Optional display glyphs — dot-matrix bitmaps on the `.ui-dotmatrix` primitive
@@ -213,10 +217,30 @@ simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
 
 Building analytical / generated-report UI? Import the roll-up
-`@ponchia/ui/css/analytical.css` (bundles annotations + legend + marks +
-connectors + spotlight + crosshair + selection) instead of the seven leaves;
-add `css/dataviz.css` for chart colours and `css/report.css` for the document
-grammar. The individual layers (each opt-in, none in the default bundle):
+`@ponchia/ui/css/analytical.css` (bundles figure + annotations + legend +
+marks + connectors + spotlight + crosshair + selection + highlights) instead
+of the nine leaves; add `css/dataviz.css` for chart colours and `css/report.css`
+for the document grammar. Interval and clamp are report/evidence leaves but are
+NOT in the roll-up; link them individually. The individual layers (each opt-in,
+none in the default bundle):
+
+Optional figure stage for charts, diagrams, screenshots, and annotated media —
+opt-in, never in the default bundle. It composes with `ui-report__figure` but
+does not replace it:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/figure.css" />
+```
+
+Use `ui-figure` on the `<figure>`, `ui-figure__caption` on the caption,
+`ui-figure__body` and optional `ui-figure__body--key-right` for stage + key
+layout, `ui-figure__stage` for the centered media box, `ui-figure__media` for
+the chart/SVG/img/canvas, `ui-figure__overlay` for pointer-transparent absolute
+overlays, `ui-figure__key` for legends, and `ui-figure__data` for fallback
+tables. Author-set knobs: `--figure-max-inline`, `--figure-min-block`,
+`--figure-key-width`. Bronto owns layout only; the host owns data, scales,
+chart rendering, overlay content, and accessibility text. Details:
+`docs/figure.md`.
 
 Optional SVG annotations for charts/reports — opt-in, never in the default
 bundle. This is Bronto's subject / connector / note grammar inspired by
@@ -351,6 +375,20 @@ Apply `ui-sel` + `ui-sel--on` (selected), `ui-sel--off` (excluded), or
 row, list item, map region) from YOUR selection/brush logic — Bronto only styles
 them. `ui.sel({ state: 'on'|'off'|'maybe' })`. Details: `docs/selection.md`.
 
+Optional Custom Highlight API paint — opt-in, CSS only, never in the default
+bundle. For cited evidence, search hits, and current match ranges without
+wrapping text nodes:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/highlights.css" />
+```
+
+Put `ui-highlights` on the text scope. The host creates `Range` objects and
+registers `Highlight` sets as `CSS.highlights.set('bronto-evidence', ...)`,
+`bronto-search`, and `bronto-current`; Bronto only paints them. Custom props:
+`--highlight-evidence`, `--highlight-search`, `--highlight-current`. Always
+check `CSS.highlights` before registering. Details: `docs/highlights.md`.
+
 Optional source/citation/provenance trust layer — opt-in, CSS only, never in
 the default bundle. The grammar for "where did this come from?" in generated
 reports/AI output:
@@ -371,6 +409,32 @@ author-written label (never colour alone). A tone class **needs a host**:
 states; the host owns fetching, numbering, and trust. `ui.citation({chip,state})` / `ui.source({state})` /
 `ui.provenance({state})`. Details: `docs/sources.md`.
 
+Optional low/high interval — opt-in, CSS only, never in the default bundle. For
+confidence windows, estimates, budget bands, or caveated evidence readings:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/interval.css" />
+```
+
+Use `ui-interval` with host-normalised `--lo` and `--hi` (0..1), optional
+`ui-interval__point` with `--v`, plus `ui-interval__track`,
+`ui-interval__range`, `ui-interval__label`, and `ui-interval__bounds`.
+The container needs host-written text (`role="img"` + `aria-label`, or nearby
+visible prose). Bronto paints geometry only. Details: `docs/interval.md`.
+
+Optional bounded excerpt clamp — opt-in, CSS only, never in the default bundle.
+For source excerpts, claim basis, and caveats that should scan compactly but
+remain reachable:
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/clamp.css" />
+```
+
+Use `ui-clamp` with `--clamp-lines`, `ui-clamp__body`, and optionally a checkbox
+`ui-clamp__toggle` followed by a visible `ui-clamp__control` containing explicit
+`ui-clamp__more` / `ui-clamp__less` text. Host owns IDs and content. Print
+expands the body and hides the control. Details: `docs/clamp.md`.
+
 Optional line/row change-review grammar — opt-in, CSS only, never in the
 default bundle. For code review, changelogs, version history, config diffs, and
 generated reports:
@@ -558,7 +622,8 @@ behavior. Filter + keyboard-navigate a DOM-authored command list:
 Enter→`bronto:command:select` ({value,label}) and Escape→`bronto:command:close`.
 The HOST owns the action registry + execution; NO global Cmd/Ctrl+K (open it
 yourself, e.g. a <dialog> via initDialog). Pairs with `ui-shortcut`. Binding:
-`useCommand()` (react/solid/qwik). Details: `docs/command.md`.
+`useCommand()` (React/Solid/Qwik), `command` / `useCommand` (Svelte), and
+`vCommand` / `brontoVue` (Vue). Details: `docs/command.md`.
 
 Optional static report layer for LLM-authored HTML reports — opt-in, never in
 the default bundle. Pair it with the normal bundle, and add data-viz only when
@@ -569,11 +634,13 @@ specifiers only work after a bundler rewrites them:
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/figure.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/sources.css" />
 ```
 
 In Vite/webpack/etc., import `@ponchia/ui`, `@ponchia/ui/css/report.css`, and
-`@ponchia/ui/css/dataviz.css` instead.
+`@ponchia/ui/css/dataviz.css` instead; add `figure.css`, `interval.css`,
+`clamp.css`, or `highlights.css` only when the report uses them.
 
 Canonical report skeleton:
 
@@ -616,8 +683,9 @@ Report rules for agents:
 - Use semantic headings; give tables captions and header cells; give charts
   captions, legends/direct labels, and fallback data.
 - For a chart, theme Vega-Lite with `@ponchia/ui/vega` or hand-author a
-  token-themed inline `<svg>` inside a `ui-report__figure`. Bronto ships no
-  chart component.
+  token-themed inline `<svg>` inside `ui-report__figure ui-figure`, with a
+  `ui-figure__stage`, optional `ui-figure__key`, and fallback `ui-figure__data`.
+  Bronto ships no chart component.
 - Put the above-the-fold call in `ui-report__decision`; use
   `ui-report__finding--critical|--major|--minor|--resolved` only when the
   written finding label also states the severity/status.
@@ -633,9 +701,12 @@ Report rules for agents:
   conflicting, unverified, or generated inputs should be surfaced near affected
   claims, not only in the source appendix.
 - For important reports, emit a sidecar `claims.json` / source archive manifest
-  with stable claim IDs, source IDs, status, risk, retrieval time, and
-  claim-source relations. The visible HTML remains the primary artifact, but the
-  sidecar lets tools prove IDs and high-risk evidence still resolve.
+  with `schemaVersion: "bronto-report-claims.v1"` and, when validating,
+  `@ponchia/ui/schemas/report-claims.v1.schema.json`. Include stable claim IDs,
+  source IDs, status, risk, retrieval time, and explicit `relations`
+  (`supports`, `limits`, `contradicts`, or `informs`). The visible HTML remains
+  the primary artifact, but the sidecar lets tools prove IDs and high-risk
+  evidence still resolve.
 - Use `ui-delta` (`--up`/`--down`/`--flat`, `--invert` when up is bad) for a
   trend figure and `ui-compare` (`--2up`) for an A/B / before-after section.
 - Use `ui-report__section--unnumbered` for appendices in numbered reports.
@@ -676,6 +747,8 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `docs/reporting.md` — static/PDF-first report cookbook for LLM-authored
   reports, including report skeletons, decision/finding/evidence patterns,
   chart rules, print utilities, and safety boundaries.
+- `schemas/report-claims.v1.schema.json` — declarative JSON Schema for
+  `claims.json` sidecars that map report claims to source IDs and relations.
 - `docs/annotations.md` — SVG annotation recipes and helper guidance for
   analytical figures.
 - `docs/mermaid.md` — theme Mermaid diagrams from bronto tokens (resolved
@@ -705,11 +778,11 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   annotation geometry.
 - `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
 
-## Human-browsable references (not shipped in the npm tarball, by design)
+## External web references
 
 - Live kitchen-sink demo (every component, light/dark, RTL): https://ponchia.github.io/bronto-ui/
 - Architecture & the CSS-first decision: https://github.com/Ponchia/bronto-ui/blob/main/docs/architecture.md
-- Framework integration guides (Astro / SvelteKit / React-Solid-Qwik / vanilla):
+- Framework integration guides (Astro / SvelteKit / Vue / React-Solid-Qwik / vanilla):
   https://github.com/Ponchia/bronto-ui/tree/main/docs/getting-started
 
 ## Rules an agent should respect