@ponchia/ui 0.6.6 → 0.6.7

package/docs/stability.md

@@ -21,15 +21,17 @@ shipped `files` entry, and the generated artifact provenance map — see
 | 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`). |
+| Schemas (`schemas/*.schema.json`) | Stable additive | Declarative JSON Schema contracts for package-adjacent tooling data. Existing schema files and enum values are public within a compatible minor; new optional properties and new schema files are additive. No validator runtime ships. |
 | 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. |
 | `.ui-icon` mask renderer | Stable | Class name, `--icon-size`, currentColor inheritance, and `--icon-mask` contract are public. The internal data URL encoding is not. |
-| React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
+| Framework lifecycle adapters (`react`/`solid`/`qwik`/`svelte`/`vue`) | Stable thin adapters | Hook/action/directive names, optional peer behavior where applicable, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
 | Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
 | Reports (`css/report.css`, `.ui-report*`, print utilities) | Stable additive | Report class names, BEM part names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`; charting is via the Vega theme target (`@ponchia/ui/vega`, see [vega](./vega.md)) or a token-themed inline SVG, not a shipped renderer. |
+| Report kit roll-up (`css/report-kit.css`) | Stable additive | A convenience `@import` of the complete static-report vocabulary. The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
 | Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
 | Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
 | Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
@@ -37,11 +39,11 @@ shipped `files` entry, and the generated artifact provenance map — see
 | Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
 | 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. |
+| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the nine analytical leaves (figure, annotations, legend, marks, connectors, spotlight, crosshair, selection, highlights). 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--*`, `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. |
+| Workbench (`css/workbench.css`, `.ui-splitter*`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`, `initSplitter`) | Stable additive | Splitter, inspector, property-row and selection-bar class + BEM part names are public (no recipe). `data-bronto-splitter`, `--splitter-pos`, `bronto:splitter:resize`, and the `initSplitter` cleanup contract are public. Opt-in, not in the default bundle. The host owns pane content, persistence, collapse policy, and selection state. |
 | Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
 | Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |

package/docs/state.md

@@ -2,9 +2,10 @@
 
 `@ponchia/ui/css/state.css` is an opt-in vocabulary for the states real apps
 spend their time in — saving, saved, queued, offline, stale, conflicted, locked,
-reviewed. These are usually improvised per product, so even good apps feel
+reviewed, and background work still running after the initiating interaction is
+gone. These are usually improvised per product, so even good apps feel
 inconsistent. This is the canonical set: a labelled state object with a rationed
-tone, plus a page/document sync bar.
+tone, a page/document sync bar, and a persistent background-job row.
 
 ```css
 @import '@ponchia/ui';
@@ -12,10 +13,10 @@ tone, plus a page/document sync bar.
 ```
 
 Bronto ships the visual states and the canonical wording. The host owns the
-state machine, retry policy, persistence, and announcements. **Persistent state
-deserves persistent UI** — a toast is secondary, not the answer. The tone is a
-second channel; the **label is the state**, so it survives forced-colors and
-screen readers (WCAG 1.4.1).
+state machine, retry policy, persistence, cancellation, and announcements.
+**Persistent state deserves persistent UI** — a toast is secondary, not the
+answer. The tone is a second channel; the **label is the state**, so it
+survives forced-colors and screen readers (WCAG 1.4.1).
 
 ## `.ui-state`
 
@@ -68,6 +69,61 @@ the other.
 </div>
 ```
 
+## `.ui-job`
+
+A durable row for background jobs, imports, exports, sync runs, and pipelines.
+It is deliberately not a task runner: the host owns polling, retry/cancel
+semantics, queue position, partial failures, and completion messages. Bronto
+paints a persistent status/progress object so long-running work is not hidden in
+a transient toast.
+
+```html
+<article
+  class="ui-job ui-job--running"
+  style="--job-progress: 64%"
+  aria-labelledby="job-title"
+>
+  <div class="ui-job__head">
+    <h3 class="ui-job__title" id="job-title">Importing listings</h3>
+    <span class="ui-state ui-state--saving ui-state--busy">
+      <span class="ui-state__label">Running</span>
+      <span class="ui-state__detail">64%</span>
+    </span>
+  </div>
+  <p class="ui-job__body">124 of 194 records processed. Latest checkpoint saved.</p>
+  <div
+    class="ui-job__progress"
+    role="progressbar"
+    aria-label="Import progress"
+    aria-valuemin="0"
+    aria-valuemax="100"
+    aria-valuenow="64"
+  >
+    <span class="ui-job__bar"></span>
+  </div>
+  <div class="ui-job__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">View log</button>
+    <button class="ui-button ui-button--ghost ui-button--sm" type="button">Cancel</button>
+  </div>
+</article>
+```
+
+Use the written state as the source of truth:
+
+| State | Class | Typical label | Use when… |
+| --- | --- | --- | --- |
+| Queued | `ui-job--queued` | "Queued" | The job is accepted but not running yet. |
+| Running | `ui-job--running` | "Running" / "Syncing" | Work is actively progressing. |
+| Blocked | `ui-job--blocked` | "Blocked" / "Waiting" | Work cannot proceed without another system or user action. |
+| Failed | `ui-job--failed` | "Failed" | The job stopped and needs retry, inspection, or acknowledgement. |
+| Complete | `ui-job--complete` | "Complete" | Work finished and the result is available. |
+
+For determinate jobs, set `--job-progress` as a percentage on `.ui-job` and
+put `role="progressbar"` plus `aria-valuenow/min/max` on `.ui-job__progress`.
+For indeterminate jobs, omit the progress block or omit `aria-valuenow`, and
+make the written state clear ("Running", "Waiting for worker", "Retrying").
+Use `ui-job--compact` for dense queues.
+
 ## Recipe
 
 ```js
@@ -75,11 +131,12 @@ import { ui } from '@ponchia/ui/classes';
 
 ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
 ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
+ui.job({ state: 'running' }); // "ui-job ui-job--running"
 ```
 
 ## Scope
 
-CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago") or live
-progress text is the host's job; a small optional behavior may come later if a
-real consumer needs it. Background-job progress and conflict-resolution
-affordances are deliberately deferred until then.
+CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago"), live
+progress text, polling, cancellation, retry, and conflict-resolution affordances
+are the host's job. A small optional behavior may come later if a real consumer
+needs it.

package/docs/theming.md

@@ -11,7 +11,7 @@ theme-owned neutral ramp endpoint:
 
 | Token                 | Derivation (light / dark)                    | Role |
 | --------------------- | -------------------------------------------- | ---- |
-| `--accent-strong`     | `--accent` mixed 83% with black / 84% white  | darker/lighter accent for hover, emphasis |
+| `--accent-strong`     | `--accent` mixed 83% with black / 80% white  | darker/lighter accent for hover, emphasis |
 | `--accent-ramp-end`   | white / black                                | neutral endpoint for the low-chroma OKLCH ramp |
 | `--accent-text`       | `var(--accent-strong)` (alias)               | **accent used as foreground text** — the on-surface, AA-safe one |
 | `--accent-soft`       | `--accent` at 10% / 14% over transparent     | tinted fills |
@@ -63,7 +63,7 @@ fills — follows automatically, in both light and dark.
 >    defaults to `--accent-strong` (a darkened/​lightened accent). If you
 >    re-brand to a pale hue, raw `--accent` would fail as text — override
 >    `--accent-text` to a sufficiently dark/light value rather than
->    relying on the 83%/84% mix.
+>    relying on the 83%/80% mix.
 >
 > The defaults are tuned for both; verify if you deviate hard. The focus
 > ring is solid `--accent` (≥ 3:1 non-text) — re-brand to a near-`--bg`
@@ -303,6 +303,14 @@ palette) carry real `$value`s; the CSS-runtime-derived family
 `$value: null` + the CSS in `$extensions["com.ponchia.css"]` rather than
 fabricating a number — the resolvable knob is `color.<theme>.accent`.
 
+`@ponchia/ui/tokens/figma.variables.json` is the resolved local handoff for
+Figma Variables import/sync scripts. It is generated from `tokens/resolved.json`
+and keeps a `Bronto / Color` collection with `Light` and `Dark` modes plus a
+`Bronto / Scale` collection for spacing, radius, type, z-index and motion.
+Colour values are exported as Figma-style RGBA objects; non-colour values keep
+their original CSS value under `$extensions["com.ponchia.css"]` so importer
+scripts do not lose units.
+
 ## Reading tokens from JS
 
 `@ponchia/ui/tokens` exposes the model as data. The ergonomic view only

package/docs/usage.md

@@ -276,12 +276,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 +292,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 +314,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
@@ -606,10 +625,11 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 | 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 |
 | Toast | `toast()` | nothing — it is imperative-only |
 
@@ -628,10 +648,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/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.7/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand
@@ -213,10 +213,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 +371,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 +405,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:
@@ -569,11 +629,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 +678,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 +696,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 +742,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,7 +773,7 @@ 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