@ponchia/ui 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -5,6 +5,175 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.6.8 — 2026-06-16
+
+Patch release for the deep UI-framework audit: broader browser/package gates,
+clean-consumer verification, and runtime fixes found while hardening the public
+surface. No breaking changes, no `MIGRATIONS.json` entry.
+
+### Added
+
+- **Tarball and clean-consumer gates.** `check:consumer-surface` now imports
+  public JS/JSON subpaths from the packed package, resolves concrete CSS/doc/
+  font subpaths without optional peers, and verifies behavior initializers stay
+  SSR-safe. `check:consumer-types` installs the tarball into a clean TypeScript
+  consumer and compiles every typed `@ponchia/ui/...` package subpath.
+- **Matrix ownership gates.** `check:component-matrix`,
+  `check:behavior-matrix`, `check:helper-matrix`, and `check:binding-matrix`
+  now require shipped CSS leaves, public behavior exports, helper modules, and
+  framework bindings to have explicit docs, type, unit, or browser ownership.
+- **Public docs and package hygiene gates.** `check:doc-links` validates local
+  links and heading anchors across shipped docs, authoring docs, and the docs
+  viewer route list. `check:schemas`, `check:visual-baselines`,
+  `check:playwright-container`, and stronger `check:contract` / `check:report`
+  coverage close stale public snippets, missing visual baselines, and invalid
+  report/schema surfaces.
+- **Broader browser coverage.** The Playwright suite now pins docs viewer deep
+  links, cascade-layer behavior, source focusing, renderer geometry, behavior
+  cleanup/idempotency, connector transforms, annotation motion/overflow,
+  command interactions, crosshair payloads, responsive overflow, and more
+  forced-colors/reduced-motion contracts.
+- **Packed example smoke coverage.** The example runner now builds and smokes
+  the packed examples from one registry, with richer runtime assertions,
+  desktop/mobile visual health, and optional Chromium/Firefox/WebKit coverage.
+  Astro joins the packed-tarball smoke matrix.
+- **Renderer theme helper coverage.** Chart, Mermaid, D2, and Vega package
+  helpers now have type/runtime coverage that checks default exports,
+  theme-selection fallbacks, resolved colors, and `var()` leak prevention.
+
+### Fixed
+
+- **Standalone dot readouts survive `report-kit.css`.** `crosshair.css` now
+  scopes pinned readout-chip styling to `.ui-crosshair .ui-readout`, so the
+  core dot-matrix `.ui-readout` keeps its normal inline layout when a report
+  imports the full report kit.
+- **Rendered docs deep links work.** `docs/index.html` now preserves
+  `doc.md#section` routes, generates deterministic heading IDs, keeps
+  same-page anchors inside the current doc route, and drops the invalid
+  meta-CSP `frame-ancestors` directive that browsers reported as a console
+  error.
+- **Command adapter docs match the shipped matrix.** `docs/command.md`, the
+  stability matrix, package-contract provenance, and `llms.txt` now name the
+  Svelte action and Vue directive/plugin paths alongside the React/Solid/Qwik
+  bindings.
+- **CodeQL review findings.** Docs slug helpers no longer use incomplete
+  regex-based tag stripping, and wildcard package-subpath expansion replaces
+  every placeholder rather than only the first one.
+
+### Changed
+
+- `npm run check` now owns the unit suite through `check:unit`; CI, release
+  workflow validation, PR templates, release docs, and package-contract docs
+  all describe the same aggregate gate instead of duplicating `npm test`.
+- Release hygiene now verifies the aggregate check includes unit coverage and
+  prevents duplicate release-workflow unit runs from drifting out of sync.
+- `check:exports` now pins package-level CSS metadata: the top-level `style`
+  field, root export targets, `files`, and CSS-preserving `sideEffects`.
+- Type-only coverage now instantiates Svelte action and Vue directive
+  declarations from consumer-shaped code, including invalid root-shape
+  assertions.
+- The default bundle budget is recalibrated to 91 kB raw / 15.65 kB gzip after
+  the audited bundle landed below that ceiling at 87.9 kB raw / 15.0 kB gzip.
+
+## 0.6.7 — 2026-06-15
+
+### Added
+
+- **Tailwind v4 bridge.** `@ponchia/ui/tailwind` / `@ponchia/ui/tailwind.css`
+  ships a CSS-first `@theme inline` bridge, `bronto-dark` and `bronto-oled`
+  custom variants, and source-registration guidance for Tailwind v4 projects.
+  `docs/interop/tailwind.md` documents `@reference` / `@source`, and
+  `examples/tailwind-vite` builds from the packed tarball and browser-smokes
+  the emitted Bronto utilities.
+- **Svelte and Vue lifecycle adapters.** `@ponchia/ui/svelte` exports
+  dependency-free actions over the delegated behavior layer, and
+  `@ponchia/ui/vue` exports directives, plugin helpers, and the shared
+  imperative `useToast()` helper.
+  The SvelteKit example now uses the Svelte adapter, and `examples/vue-vite`
+  covers Vue consumer install/build/runtime smoke from the packed package.
+- **Figma Variables handoff artifact.** `tokens/figma.variables.json` is
+  generated from the token source, exported as
+  `@ponchia/ui/tokens/figma.variables.json`, drift-checked in `check:fresh`,
+  and documented as a local import/sync handoff alongside the DTCG token export.
+- **Report-primitive batch** — four additive opt-in leaves for static reports
+  and explanation surfaces: `ui-figure` (`css/figure.css`) for reusable
+  chart/diagram/media stages with overlay, key and fallback-data slots;
+  `ui-interval` (`css/interval.css`) for host-normalised low/high evidence
+  windows; `ui-clamp` (`css/clamp.css`) for bounded excerpts with CSS-only
+  show-more / show-less; and `ui-highlights` (`css/highlights.css`) for named
+  CSS Custom Highlight API paints (`bronto-evidence`, `bronto-search`,
+  `bronto-current`). All stay out of `dist/bronto.css`; `figure.css` and
+  `highlights.css` join the analytical roll-up.
+- **Background-job state primitive.** `state.css` now includes `ui-job` for
+  persistent asynchronous work: written status, determinate progress via
+  `--job-progress`, optional actions, compact mode, and queued/running/blocked/
+  failed/complete tones. The host still owns polling, retries, cancellation,
+  and announcements.
+- **Workbench splitter primitive.** `workbench.css` now includes
+  `ui-splitter` / `__pane` / `__handle` plus the optional `initSplitter`
+  behavior (`data-bronto-splitter`) for focusable ARIA separator handles,
+  keyboard and pointer resizing, `--splitter-pos` / `aria-valuenow` sync, and a
+  `bronto:splitter:resize` event. React, Solid, Qwik, Svelte, and Vue adapters
+  expose the matching hook/action/directive.
+- **Service identity demo and report kit.** The public demo set now includes
+  `demo/service.html`, a cross-service `ui-app-shell` specimen that keeps the
+  default bundle centered on shared app identity. Static reports get the new
+  opt-in `@ponchia/ui/css/report-kit.css` roll-up for the complete report
+  vocabulary, plus `@ponchia/ui/schemas/report-claims.v1.schema.json` for
+  claim/source sidecar validation.
+- **Public-package hardening gates.** `check:public-hygiene`,
+  `check:variables`, and `check:migrations` are now part of the aggregate
+  `npm run check` chain, covering packed public text leaks, undefined CSS
+  custom-property references, and migration-map/doc alignment.
+
+### Fixed
+
+- **Silent CSS token typos.** `css/workbench.css` now uses the real
+  `--focus-ring` token for splitter focus outlines, and `css/report.css` uses
+  `--text-base` for finding/evidence value text. The new variable-reference
+  gate prevents the same class of no-op declaration from shipping again.
+- **Print: stat tiles and table rows no longer slice across PDF page
+  boundaries** — the report-layer `@media print` break-inside guard covered
+  the report shell (`.ui-report__*`, `.ui-claim`, `.ui-evidence-item`) but
+  not `.ui-stat` tiles, generic `.ui-statgrid` children, or `tr`, so a stat
+  card landing on a page boundary printed half its value on one page and the
+  delta on the next (observed in a consumer report's PDF export). Guarded at
+  the item level — the tile / the row, not the container — so a long
+  statgrid or table can still span pages.
+
+- **Sidenote gutter contract actually works now** — `--sidenote-width` /
+  `--sidenote-gap` are root-scoped instead of declared only on the notes.
+  The documented host wiring (container
+  `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))`)
+  referenced vars an ancestor could never see, so the calc was invalid and
+  silently reserved NO gutter — the floated notes spilled past the page edge
+  (caught by a real report's visual QA). The demo now uses the documented
+  calc verbatim (it previously masked the bug with a hardcoded literal), and
+  a wide-viewport e2e asserts the contract: gutter resolves, float stays
+  on-page, no horizontal scroll. Overriding either knob on the container now
+  re-sizes the notes and the gutter together.
+
+### Changed
+
+- `docs/d2.md` tokenize recipe covers the full embedded-style surface
+  (`.color-*` / `.background-color-*` rules, not just `fill`/`stroke`) and
+  warns that `tooltip:`/`|md` shapes embed GitHub-Primer styling that
+  survives tokenization. `docs/sidenote.md` documents the root-scoped knobs.
+- Local verification is now reproducible through named scripts:
+  `npm run test:e2e:nonpixel` runs every non-screenshot Playwright spec across
+  Chromium, Firefox, and WebKit, while `npm run test:examples` packs the real
+  tarball, builds all examples in temp directories, and browser-smokes the
+  runtime examples. `CONTRIBUTING.md`, `docs/release.md`, and
+  `docs/architecture.md` describe when to use those local gates versus the
+  pinned-container screenshot gate.
+- `check:examples` keeps the example inventory, CI matrix, browser-smoke list,
+  README rows, and preview ports aligned from one registry; `check:dead` now
+  runs in the aggregate `npm run check` chain.
+- README, package metadata, usage docs, workbench examples, and the docs index
+  now frame `@ponchia/ui` as the shared UI identity layer for services, tools,
+  sites, and reports, with reports as an opt-in consumer rather than the center
+  of the package.
+
 ## 0.6.6 — 2026-06-10
 
 Consolidation pass from the 2026-06-10 multi-agent audit: two real PDF-export
@@ -68,13 +237,13 @@ changes, no `MIGRATIONS.json` entry.
   post-0.6.0 leaves. The broadened scan immediately caught the demo/reference
   class defects above. `core.css` imports are now closed over an explicit
   CORE_BUNDLE allowlist in both directions.
-- `ROADMAP.md` / `docs/frontier-primitives.md` reconciled to 0.6.5: the
+- `ROADMAP.md` / `docs/frontier-primitives.md` reconciled to 0.6.7: the
   report/provenance/explanation lane is named the proven core; ui-job,
-  ui-conflict, ui-splitter, the tree roving-focus kernel, and
-  command/workbench follow-ons are explicitly dormant until a real app
-  consumer exists; the 2026-06-09 scout keeps (ui-interval, ui-clamp,
-  ui-highlights) are recorded as report-lane candidates gated behind the
-  routing hub. The adoption stance is stated in ROADMAP.
+  ui-conflict, drag/drop workbench follow-ons, the tree roving-focus kernel,
+  and command follow-ons are explicitly dormant until a real app consumer
+  exists; the 2026-06-09 scout keeps (ui-interval, ui-clamp, ui-highlights) are
+  recorded as report-lane candidates gated behind the routing hub. The adoption
+  stance is stated in ROADMAP.
 
 ## 0.6.5 — 2026-06-09
 

package/README.md

@@ -3,30 +3,32 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~87kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~88kB%20%2F%20~15kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first design system for interfaces that explain themselves.** It works in
-plain HTML, every modern framework, and print/PDF, with no component runtime to
-adopt and zero runtime dependencies.
+**A CSS-first identity and UI layer for services, tools, sites, and reports.** It
+works in plain HTML, every modern framework, and print/PDF, with no component
+runtime to adopt and zero runtime dependencies.
 
 The look is a deliberate stance: a neutral monochrome canvas with one rationed
 accent (colour signals, it never decorates), dot-matrix display type, and
 hairline borders — all re-skinnable from a single `--accent` knob (opt-in
 amber-CRT, phosphor-green, and e-ink colorways).
 
-Beyond the standard component set it ships an opt-in analytical & report layer —
-SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text
-marks, a colourblind-safe data-viz palette, and a static/PDF report grammar — for
-dashboards and LLM-authored reports.
+The default bundle is the shared service identity: app shells, navigation,
+forms, tables, feedback, overlays, workflow surfaces, prose, motion and the
+token system that lets each app feel related without sharing a component
+runtime. On top of that it ships opt-in tooling/report layers — workbench panes,
+commands, system state, provenance, figure stages, annotations, legends,
+evidence highlights, intervals, data-viz tokens and a static/PDF report grammar.
 
-### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Static report →](https://ponchia.github.io/bronto-ui/demo/report-standalone.html)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
+### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Service shell →](https://ponchia.github.io/bronto-ui/demo/service.html)  ·  [Static report →](https://ponchia.github.io/bronto-ui/demo/report-standalone.html)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
 The demo is the kitchen sink — every component, light/dark, RTL, live theming.
-The static report is the differentiator in one file: a complete, no-build,
-no-JS, Chromium-PDF-ready report built from the report grammar.
+The service shell shows the shared app identity; the static report shows the
+same system under a no-build, no-JS, Chromium-PDF-ready constraint.
 
 <p>
   <img alt="A research report built with the @ponchia/ui report layer" src="https://raw.githubusercontent.com/Ponchia/bronto-ui/main/demo/_preview-report-research.png" width="49%" />
@@ -48,7 +50,13 @@ and the accent is a spotlight, not a paint bucket. Because everything lives in a
 single `@layer bronto`, your own un-layered CSS overrides the framework with no
 specificity fight and no `!important`.
 
-It ships a complete, accessible **standard component set**, but that's not where it competes — its differentiator is the opt-in **analytical & communication layer** sketched above. The line that holds it together: each primitive owns only its visual grammar and pure geometry — no chart engine, no state, no hit-testing. See **[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)** for the thesis.
+It ships a complete, accessible **standard component set** because that is the
+identity layer every service consumes. Its sharper edge is the opt-in **tooling,
+analytical, and communication layer** sketched above. The line that holds it
+together: each primitive owns only its visual grammar and pure geometry — no
+chart engine, no domain state, no hit-testing. See
+**[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)**
+for the thesis.
 
 ## Install
 
@@ -59,12 +67,12 @@ npm i @ponchia/ui
 Or drop it in with no build step, straight from a CDN:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/bronto.css">
 ```
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~87 kB raw / ~15 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~88 kB raw / ~15 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -77,7 +85,7 @@ Or drop it in with no build step, straight from a CDN:
 
 > Prefer source leaves through a bundler? Use `@import '@ponchia/ui/css'` (a thin `@import` fan-out) instead. Both resolve the Doto `@font-face` with relative URLs, so there's no `/fonts` path assumption.
 
-> The bundle is the standard component set. The opt-in analytical & report layers — `report.css`, `dataviz.css`, `annotations.css`, `legend.css`, and the rest — are **not** in `bronto.css`; link each one you need from `dist/css/`. For LLM-authored static reports see [docs/reporting.md](docs/reporting.md).
+> The bundle is the standard component set. The opt-in analytical & report layers — `report.css`, `dataviz.css`, `figure.css`, `annotations.css`, `legend.css`, `interval.css`, `clamp.css`, `highlights.css`, and the rest — are **not** in `bronto.css`; link each one you need from `dist/css/`. For LLM-authored static reports see [docs/reporting.md](docs/reporting.md).
 
 **2. Write markup with `ui-*` classes** (primary is the default button; modifiers are opt-in):
 
@@ -130,10 +138,10 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Feedback** — alert/callout, toast, tooltip, `ui-progress` (task) and `ui-meter` (measured value).
 - **Overlay** — modal + drawer on native `<dialog>`, dropdown menu, `ui-carousel` + `ui-lightbox` (gallery, user-driven — not an auto-slider).
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
-- **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
+- **Shells** — a service/app shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
-- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
-- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, figures, chart wrappers and print utilities.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: **figure** stages, SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, a cross-cutting **selection** vocabulary, and CSS Custom Highlight API **highlights**. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust), **interval**, **clamp**, and **lifecycle `state`** leaves.
+- **Reports** _(opt-in)_ — `@ponchia/ui/css/report-kit.css` for a complete static/PDF report vocabulary, or `@ponchia/ui/css/report.css` plus only the leaves a narrow report uses. Covers, decisions, claims, sections, severity-labelled findings, evidence packets, evidence ledgers, action registers, source-card bindings, `ui-figure` composition, intervals, bounded excerpts, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
 - **Glyphs** — `@ponchia/ui/glyphs`, a 71-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
 - **Colorways** _(opt-in)_ — `data-bronto-skin="amber-crt | phosphor-green | e-ink"`: a root-level recolour of the one accent (OKLCH, per-theme, contrast-gated), never in the default bundle.
@@ -143,13 +151,17 @@ Full generated catalog of every class: **[docs/reference.md](https://github.com/
 
 ## Theming: one knob
 
-Everything accent-colored derives from a single `--accent` variable via `color-mix()`. Re-brand the entire app — both light and dark — with one declaration, globally or scoped to any subtree:
+Everything accent-colored derives from a single `--accent` variable via `color-mix()`. Re-brand the entire app — both light and dark — with root-level, per-theme overrides:
 
 ```css
 :root   { --accent: #2f6df6; }   /* whole app blue   */
-.promo  { --accent: #16a34a; }   /* …or just this section green */
 ```
 
+Scoped `--accent` overrides recolor direct accent uses in that subtree, but the
+derived family (`--accent-text`, `--accent-soft`, focus/dot/ramp tokens) is a
+root-level skin contract. Use the full per-theme recipe in
+[`docs/theming.md`](docs/theming.md) for production rebrands.
+
 Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the default monochrome look is **one skin, not the architecture**.
 
 **One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
@@ -162,7 +174,7 @@ Not an afterthought — a gate. Every contractual token pairing has a declared W
 
 ## Works with anything
 
-The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps, so the core stays zero-dependency.
+The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps. Svelte and Vue get dependency-free lifecycle adapters too: `@ponchia/ui/svelte` exports actions, and `@ponchia/ui/vue` exports directives/plugin helpers over the same behavior layer.
 
 Per-framework getting-started guides + runnable example apps live in the repo:
 
@@ -171,16 +183,17 @@ Per-framework getting-started guides + runnable example apps live in the repo:
 | Vanilla / Vite / plain HTML | [vanilla.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vanilla.md) | [`examples/vanilla-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vanilla-vite) |
 | Astro | [astro.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/astro.md) | [`examples/astro`](https://github.com/Ponchia/bronto-ui/tree/main/examples/astro) |
 | SvelteKit | [sveltekit.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/sveltekit.md) | [`examples/sveltekit`](https://github.com/Ponchia/bronto-ui/tree/main/examples/sveltekit) |
+| Vue | [vue.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vue.md) | [`examples/vue-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vue-vite) |
 | React | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/react-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/react-vite) |
 | Solid | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/solid-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/solid-vite) |
 | Qwik | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/qwik-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/qwik-vite) |
-| Tailwind / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | — |
+| Tailwind v4 bridge / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | [`examples/tailwind-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/tailwind-vite) |
 
 ## Extras
 
-- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` — concrete hex per theme for canvas/SVG/MapLibre).
+- **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, `tokens/resolved.json` for concrete values in canvas/SVG/MapLibre, and `tokens/figma.variables.json` for local Figma Variables import/sync scripts).
 - **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json' with { type: 'json' }` in Node ESM, or the same path through a bundler JSON import (resolved hex per theme; series 1 = your accent) plus the opt-in `@ponchia/ui/css/dataviz.css`.
-- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure, claim/evidence/action grammar, source-card bindings, and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
+- **Static reports for LLMs** — add `@ponchia/ui/css/report-kit.css` for the complete report vocabulary, or `@ponchia/ui/css/report.css` plus the specific leaves a smaller report needs. Sidecar claim/source contracts can validate against `@ponchia/ui/schemas/report-claims.v1.schema.json`. Full cookbook: `docs/reporting.md`.
 - **Modern-platform motion** — overlays (modal/drawer/popover), toasts and the `<details>` accordion animate **in and out** with zero JS (`@starting-style` + `allow-discrete`, `::details-content` + `interpolate-size`). Progressive-enhancement extras: `.ui-scroll-progress` / `.ui-scroll-reveal` (scroll-driven, no JS) and `.ui-vt` for View Transitions. All degrade to a static end-state and respect `prefers-reduced-motion`. For smooth **cross-document** navigations, add the document-global one-liner to your own top-level (unlayered) CSS: `@view-transition { navigation: auto; }`.
 - **Editor IntelliSense** — point VS Code at the shipped custom-data file so every token autocompletes in `var(--…)`:
   ```json
@@ -188,7 +201,7 @@ Per-framework getting-started guides + runnable example apps live in the repo:
   ```
 - **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, `docs/package-contract.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
 
-> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, and `/charts`.
+> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. CSS helper subpaths are explicit too, including `/tailwind` for the Tailwind v4 theme/variant bridge. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/annotations`, `/connectors`, `/react`, `/solid`, `/qwik`, `/svelte`, `/vue`, `/skins`, `/charts`, `/mermaid`, `/d2`, and `/vega`.
 > JS subpaths are **ESM-only**. CommonJS consumers should use dynamic
 > `import('@ponchia/ui/behaviors')`.
 

package/annotations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"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"}

package/annotations/index.js

@@ -237,6 +237,24 @@ function validateOffset(opts) {
   };
 }
 
+function annotationConnectorType(value) {
+  const type = value ?? 'callout';
+  if (type === 'callout' || type === 'elbow' || type === 'curve') return type;
+  throw new TypeError('type must be "callout", "elbow" or "curve"');
+}
+
+function directLabelAxis(value) {
+  const axis = value ?? 'y';
+  if (axis === 'x' || axis === 'y') return axis;
+  throw new TypeError('axis must be "x" or "y"');
+}
+
+function directLabelShape(value) {
+  const shape = value ?? 'straight';
+  if (shape === 'straight' || shape === 'elbow' || shape === 'curve') return shape;
+  throw new TypeError('shape must be "straight", "elbow" or "curve"');
+}
+
 function trimForCircle(dx, dy, subject) {
   const len = Math.hypot(dx, dy);
   const radius = dimension('subject.radius', subject.radius);
@@ -673,7 +691,7 @@ const SUBJECT_BUILDERS = {
  * @returns {AnnotationParts}
  */
 export function annotationParts(opts = {}) {
-  const type = opts.type ?? 'callout';
+  const type = annotationConnectorType(opts.type);
   const transform = annotationTransform({ x: opts.x ?? 0, y: opts.y ?? 0 });
   const dx = finite('dx', opts.dx, 0);
   const dy = finite('dy', opts.dy, 0);
@@ -764,9 +782,9 @@ export function declutterLabels(items, opts = {}) {
  */
 export function directLabels(items, opts = {}) {
   if (!Array.isArray(items)) throw new TypeError('items must be an array');
-  const axis = opts.axis === 'x' ? 'x' : 'y';
+  const axis = directLabelAxis(opts.axis);
   const cross = finite('cross', opts.cross, 0);
-  const shape = opts.shape === 'elbow' || opts.shape === 'curve' ? opts.shape : 'straight';
+  const shape = directLabelShape(opts.shape);
 
   const anchors = items.map((it) => ({
     anchor: { x: finite('anchor.x', it?.anchor?.x), y: finite('anchor.y', it?.anchor?.y) },

package/behaviors/carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAuK3C"}
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA8L3C"}

package/behaviors/carousel.js

@@ -5,8 +5,44 @@ import {
   bindOnce,
   scrollIntoViewSafe,
   collectHosts,
+  closestSafe,
 } from './internal.js';
 
+const snapshotAttrs = (el) =>
+  Array.from(el.attributes, ({ name, value }) => ({
+    name,
+    value,
+  }));
+
+const restoreAttrs = (el, attrs) => {
+  for (const { name } of Array.from(el.attributes)) el.removeAttribute(name);
+  for (const { name, value } of attrs) el.setAttribute(name, value);
+};
+
+const snapshotNode = (el, { html = false } = {}) =>
+  el
+    ? {
+        el,
+        attrs: snapshotAttrs(el),
+        ...(html ? { innerHTML: el.innerHTML } : {}),
+      }
+    : null;
+
+const restoreNode = (state) => {
+  if (!state) return;
+  restoreAttrs(state.el, state.attrs);
+  if ('innerHTML' in state) state.el.innerHTML = state.innerHTML;
+};
+
+const clampIndex = (value, max) => Math.max(0, Math.min(max, value));
+
+const renderedStatusIndex = (status) => {
+  const match = /^(\d+)\s*\/\s*\d+$/.exec(status?.textContent?.trim() ?? '');
+  if (!match) return -1;
+  const value = Number(match[1]);
+  return Number.isInteger(value) ? value - 1 : -1;
+};
+
 /**
  * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
  * swipe (and momentum) are the browser's, not hand-rolled. This wires the
@@ -54,33 +90,12 @@ export function initCarousel({ root } = {}) {
     const nextBtn = box.querySelector('[data-bronto-carousel-next]');
     const loop = box.hasAttribute('data-bronto-carousel-loop');
 
-    // ARIA scaffolding — pragmatic carousel semantics (not the full APG
-    // tablist), the same restraint initMenu takes.
-    viewport.setAttribute('role', 'group');
-    viewport.setAttribute('aria-roledescription', 'carousel');
-    if (!viewport.hasAttribute('aria-label'))
-      viewport.setAttribute(
-        'aria-label',
-        box.getAttribute('data-bronto-carousel-label') || 'Carousel',
-      );
-    if (!viewport.hasAttribute('tabindex')) viewport.tabIndex = 0;
-    slides.forEach((s, i) => {
-      s.setAttribute('role', 'group');
-      s.setAttribute('aria-roledescription', 'slide');
-      if (!s.hasAttribute('aria-label')) s.setAttribute('aria-label', `${i + 1} of ${n}`);
-    });
-    if (status) status.setAttribute('aria-live', 'polite');
-    for (const b of [prevBtn, nextBtn]) {
-      if (!b) continue;
-      if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
-    }
-    if (prevBtn && !prevBtn.hasAttribute('aria-label'))
-      prevBtn.setAttribute('aria-label', 'Previous');
-    if (nextBtn && !nextBtn.hasAttribute('aria-label')) nextBtn.setAttribute('aria-label', 'Next');
-
-    let index = Math.max(
-      0,
-      slides.findIndex((s) => s.hasAttribute('data-bronto-carousel-current')),
+    const authoredIndex = slides.findIndex((s) => s.hasAttribute('data-bronto-carousel-current'));
+    const renderedThumbIndex = thumbs.findIndex((t) => t.getAttribute('aria-current') === 'true');
+    const statusIndex = renderedStatusIndex(status);
+    let index = clampIndex(
+      renderedThumbIndex >= 0 ? renderedThumbIndex : statusIndex >= 0 ? statusIndex : authoredIndex,
+      n - 1,
     );
 
     // While a button/keyboard nav is smooth-scrolling, the IntersectionObserver
@@ -136,15 +151,15 @@ export function initCarousel({ root } = {}) {
       goTo(target);
     };
     const onClick = (e) => {
-      if (prevBtn && e.target.closest('[data-bronto-carousel-prev]')) {
+      if (prevBtn && closestSafe(e.target, '[data-bronto-carousel-prev]')) {
         goTo(index - 1);
         return;
       }
-      if (nextBtn && e.target.closest('[data-bronto-carousel-next]')) {
+      if (nextBtn && closestSafe(e.target, '[data-bronto-carousel-next]')) {
         goTo(index + 1);
         return;
       }
-      const thumb = e.target.closest('.ui-carousel__thumb');
+      const thumb = closestSafe(e.target, '.ui-carousel__thumb');
       if (thumb) {
         const i = thumbs.indexOf(thumb);
         if (i >= 0) goTo(i);
@@ -178,20 +193,64 @@ export function initCarousel({ root } = {}) {
       );
     }
 
-    render();
     const bound = bindOnce(box, 'carousel', () => {
+      const state = {
+        viewport: snapshotNode(viewport),
+        slides: slides.map((slide) => snapshotNode(slide)),
+        status: snapshotNode(status, { html: true }),
+        controls: [prevBtn, nextBtn, ...thumbs]
+          .filter(Boolean)
+          .map((control) => snapshotNode(control)),
+      };
+
+      // ARIA scaffolding — pragmatic carousel semantics (not the full APG
+      // tablist), the same restraint initMenu takes.
+      viewport.setAttribute('role', 'group');
+      viewport.setAttribute('aria-roledescription', 'carousel');
+      if (!viewport.hasAttribute('aria-label'))
+        viewport.setAttribute(
+          'aria-label',
+          box.getAttribute('data-bronto-carousel-label') || 'Carousel',
+        );
+      if (!viewport.hasAttribute('tabindex')) viewport.tabIndex = 0;
+      slides.forEach((s, i) => {
+        s.setAttribute('role', 'group');
+        s.setAttribute('aria-roledescription', 'slide');
+        if (!s.hasAttribute('aria-label')) s.setAttribute('aria-label', `${i + 1} of ${n}`);
+      });
+      if (status) status.setAttribute('aria-live', 'polite');
+      for (const b of [prevBtn, nextBtn]) {
+        if (!b) continue;
+        if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
+      }
+      for (const b of thumbs) {
+        if (b.tagName === 'BUTTON' && !b.hasAttribute('type')) b.type = 'button';
+      }
+      if (prevBtn && !prevBtn.hasAttribute('aria-label'))
+        prevBtn.setAttribute('aria-label', 'Previous');
+      if (nextBtn && !nextBtn.hasAttribute('aria-label'))
+        nextBtn.setAttribute('aria-label', 'Next');
+
+      render();
       viewport.addEventListener('keydown', onKey);
       box.addEventListener('click', onClick);
       // Observe inside the add callback so observe/disconnect pair with the
       // binding lifecycle: a re-init tears down the prior binding (which
       // disconnects the old observer) before this starts, so two observers
       // never watch the same slides — even for one tick.
-      slides.forEach((s) => io?.observe(s));
+      if (io) {
+        holdProgrammatic();
+        slides.forEach((s) => io.observe(s));
+      }
       return () => {
         viewport.removeEventListener('keydown', onKey);
         box.removeEventListener('click', onClick);
         io?.disconnect();
         if (progTimer) clearTimeout(progTimer);
+        restoreNode(state.viewport);
+        state.slides.forEach(restoreNode);
+        restoreNode(state.status);
+        state.controls.forEach(restoreNode);
       };
     });
     cleanups.push(bound);

package/behaviors/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["combobox.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAqO3C"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["combobox.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA8S3C"}