@ponchia/ui 0.11.0 → 0.13.0

package/docs/adr/0001-color-system.md

@@ -223,6 +223,35 @@ Hard acceptance criteria for every step below:
    safety, which the gate caught); the ramps are OKLCH. A chart colour's WCAG
    ratio vs the background is reported **advisory** (a fill is not body text;
    the pattern + ΔE gate carry distinguishability).
+
+   **Amended in 0.12 — categorical, not accent-led; measured, not inherited.**
+   The accent-led set failed the measurable palette checks on the package's own
+   surfaces: Okabe-Ito's yellow and the slate fell outside the lightness band,
+   the slate read as grey under the chroma floor, and spending slot 1 on the
+   alert red made every ordinary first series look like an error. A consumer
+   that draws charts, timeline lanes, graph colours and participant presence
+   from one palette shipped validated values and recorded the divergence; 0.12
+   adopts them. The order is fixed (blue, orange, aqua, yellow, magenta, green,
+   violet, red) and no slot is the accent, which keeps rule 5's single
+   interactive accent intact.
+
+   The gate changed with it. A fixed order means adjacent slots are the pairs a
+   legend or a stacked mark puts side by side, so `check:charts` holds
+   *adjacent* pairs apart under simulated protanopia/deuteranopia (OKLab
+   ΔE×100 ≥ 6) and in normal vision (≥ 15), with every slot inside the theme's
+   OKLCH lightness band and above the chroma floor, measured per theme against
+   the panel, the page and the OLED surfaces. All-pairs separation is reported,
+   not gated: no eight-hue set clears it, which is why the pattern fill stays
+   the mandated second channel for scatter and map use. Contrast under 3:1 is
+   reported for the same reason.
+
+   The tier also gains its second use, which the Context above names as a
+   monochrome restriction: **categorical identity**. `--cat-N` carries the same
+   hue for a tag, a participant or a user-chosen tint, with `--cat-N-tint` (a
+   16% wash over `--panel`, so it follows skins) and `--cat-N-ink` (text that
+   holds 4.5:1 on the panel, the page and its own tint, gated). Rule 4 still
+   holds: neither namespace may appear in core component CSS, and identity
+   colour is never status.
 8. **OKLCH `--accent-1..6` ramp migration.** *(done in 0.4.0)* Steps 1–4 mix
    the accent toward `--accent-ramp-end` (white in light, black in dark)
    `in oklch` (perceptually even). The explicit endpoint avoids low-chroma

package/docs/architecture.md

@@ -188,7 +188,7 @@ are copied into consumer reports.
 | GitHub Actions workflow syntax and embedded shell snippets lint | `check:workflows` (`github-actionlint`) |
 | every shipped CSS leaf is classified as foundation or has explicit docs/demo/e2e ownership | `check-component-matrix.mjs` |
 | every public behavior export has explicit docs, unit-test, and browser-test ownership | `check-behavior-matrix.mjs` |
-| every public helper export in `classes`/`annotations`/`connectors`/`glyphs` has explicit docs, unit-test, and type-test ownership | `check-helper-matrix.mjs` |
+| every public helper export in `classes`/`annotations`/`connectors`/`renderer`/`glyphs` has explicit docs, unit-test, and type-test ownership | `check-helper-matrix.mjs` |
 | `@playwright/test` version ⇄ pinned Playwright container image ⇄ visual workflows/docs/local runner | `check-playwright-container.mjs` |
 | every shipped JSON schema is exported, documented, validates its public cookbook example, and rejects malformed sidecars | `check-schemas.mjs` |
 | packed public text contains no private terms, local paths, or secret-looking assignments | `check-public-hygiene.mjs` |

package/docs/compositions.md

@@ -74,8 +74,8 @@ Use the core stylesheet plus `report-kit.css` for a standalone HTML report.
 Use real asset URLs in HTML; package specifiers resolve only in build tools.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/report-kit.css" />
 <article class="ui-report">
   <header class="ui-report__cover ui-report__cover--compact">
     <h1 class="ui-report__title">Keep the current configuration</h1>

package/docs/contrast.md

@@ -283,40 +283,40 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 ## Data-viz palette (advisory)
 
-The opt-in Tier-4 chart palette (`@ponchia/ui/css/dataviz.css`, authored in
-`tokens/charts.js`) is gated differently: categorical series are held to
-**mutual distinguishability under normal + simulated protan/deutan/tritan
-vision** (`check:charts`, OKLab ΔE), and colour is **never the sole signal** —
-each series ships a matching `--chart-pattern-*` dot-matrix fill. So the
-WCAG ratios below are **advisory** (a chart fill is not body text); use them to
-pick a darker series for thin lines/points, or rely on the pattern. Series 1 is
-the brand accent.
+The opt-in Tier-4 categorical palette (`@ponchia/ui/css/dataviz.css`, authored
+in `tokens/charts.js`) is gated differently: each slot sits inside the theme's
+OKLCH lightness band and above the chroma floor, and **adjacent slots stay apart
+under simulated protanopia/deuteranopia and in normal vision** (`check:charts`,
+OKLab ΔE). Colour is **never the sole signal** — each series ships a matching
+`--chart-pattern-*` dot-matrix fill. So the WCAG ratios below are **advisory**
+(a chart fill is not body text); for thin lines, points or text use the slot's
+`--cat-N-ink`, which `check:charts` holds to 4.5:1. No slot is the accent.
 
 ### Light theme — categorical vs `--bg`
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#d71921` | 4.71:1 | Lc 66.8 |
-| 2 | `#e69f00` | 2.05:1 | Lc 37.4 |
-| 3 | `#56b4e9` | 2.10:1 | Lc 38.6 |
-| 4 | `#009e73` | 3.11:1 | Lc 54.4 |
-| 5 | `#f0e442` | 1.20:1 | Lc 9.1 |
-| 6 | `#0072b2` | 4.71:1 | Lc 68.4 |
-| 7 | `#cc79a7` | 2.78:1 | Lc 50.6 |
-| 8 | `#4d5358` | 7.08:1 | Lc 80.4 |
+| 1 _(accent)_ | `#2a78d6` | 4.01:1 | Lc 63.5 |
+| 2 | `#eb6834` | 2.91:1 | Lc 51.8 |
+| 3 | `#1baf7a` | 2.56:1 | Lc 46.9 |
+| 4 | `#eda100` | 1.97:1 | Lc 35.5 |
+| 5 | `#e87ba4` | 2.44:1 | Lc 45.2 |
+| 6 | `#008300` | 4.49:1 | Lc 66.8 |
+| 7 | `#4a3aa7` | 7.77:1 | Lc 82.3 |
+| 8 | `#e34948` | 3.59:1 | Lc 59.1 |
 
 ### Dark theme — categorical vs `--bg`
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#ff3b41` | 5.31:1 | Lc 40.0 |
-| 2 | `#e69f00` | 8.32:1 | Lc 57.5 |
-| 3 | `#56b4e9` | 8.12:1 | Lc 56.3 |
-| 4 | `#009e73` | 5.48:1 | Lc 40.0 |
-| 5 | `#f0e442` | 14.17:1 | Lc 87.4 |
-| 6 | `#0072b2` | 3.61:1 | Lc 26.1 |
-| 7 | `#cc79a7` | 6.12:1 | Lc 43.9 |
-| 8 | `#4d5358` | 2.40:1 | Lc 14.4 |
+| 1 _(accent)_ | `#3987e5` | 5.15:1 | Lc 37.5 |
+| 2 | `#d95926` | 4.82:1 | Lc 35.6 |
+| 3 | `#199e70` | 5.50:1 | Lc 40.1 |
+| 4 | `#c98500` | 6.10:1 | Lc 43.9 |
+| 5 | `#d55181` | 4.75:1 | Lc 35.0 |
+| 6 | `#008300` | 3.79:1 | Lc 27.7 |
+| 7 | `#9085e9` | 5.99:1 | Lc 43.0 |
+| 8 | `#e66767` | 5.80:1 | Lc 42.2 |
 
 ## Scope & caveats
 

package/docs/frontier-primitives.md

@@ -235,6 +235,11 @@ consumer since**; their follow-ons are demand-gated, not queued. Active work
 is therefore consolidation of the report lane (hub routing, print/PDF
 fidelity, consumer-contract gates), not new surfaces.
 
+> **Superseded (2026-10-01).** A canvas workspace now consumes the command,
+> workbench and state leaves daily, and its notes and visual models carry more
+> agent-authored prose than reports do. The north star moved to objects on a
+> canvas that explain themselves; see the [roadmap](https://github.com/Ponchia/bronto-ui/blob/main/ROADMAP.md#north-star).
+
 ### Report-lane primitives shipped in 0.6.7
 
 From the 2026-06-09 local scout. These were kept on merit, then shipped only

package/docs/interop/blocknote.md

@@ -0,0 +1,60 @@
+# BlockNote interop
+
+[BlockNote](https://www.blocknotejs.org) is a block editor. It themes its
+editor, menus, side menu, formatting toolbar and text highlights through
+`--bn-*` custom properties declared on `.bn-root`, with its own light and dark
+values. `css/blocknote.css` points those properties at bronto tokens, so the
+editor follows the theme, skins, contrast and the OLED surface like the rest of
+the page.
+
+## Import
+
+BlockNote's stylesheet is unlayered, and an unlayered rule outranks every
+layered one. Import this leaf's **unlayered** build, after BlockNote's:
+
+```css
+@import '@blocknote/mantine/style.css';
+@import '@ponchia/ui/css/dataviz.css';
+@import '@ponchia/ui/css/unlayered/blocknote.css';
+```
+
+The rule targets `.bn-root` and `.bn-root[data-color-scheme]`, which has the
+same specificity as BlockNote's dark block, so source order is what makes it
+win.
+
+## What maps to what
+
+| BlockNote | bronto |
+| --- | --- |
+| editor text, background | `--text`, `--panel` |
+| menu text, background | `--text`, `--panel-strong` |
+| tooltip, hovered background | `--panel-soft` |
+| selected text, background | `--on-accent`, `--accent` |
+| disabled text | `--text-dim` |
+| border, shadow | `--line` |
+| side menu (drag handle, add) | `--text-dim` |
+| font, radius | `--sans`, `--radius-lg` |
+
+Text and background highlights are categorical identity: a colour someone chose
+for a span. They take `--cat-N-ink` (text, 4.5:1 on its tint and the panel) and
+`--cat-N-tint` (background) from `css/dataviz.css`:
+
+| BlockNote highlight | Categorical hue |
+| --- | --- |
+| blue | 1 · blue |
+| orange, brown (text) | 2 · orange |
+| yellow | 4 · yellow |
+| pink | 5 · magenta |
+| green | 6 · green |
+| purple | 7 · violet |
+| red | 8 · red |
+| gray | `--text-dim` on `--panel-soft` |
+
+Without `css/dataviz.css` the highlights fall back to the status colours.
+
+## A read view that matches the editor
+
+A surface that shows the same text read-only (a preview, a fallback while the
+editor loads) can use `.ui-prose.ui-prose--blocks`. That variant reproduces
+BlockNote's block geometry, so text does not jump when the surface switches
+between reading and editing. See [the prose reference](../reference.md).

package/docs/mermaid.md

@@ -92,7 +92,7 @@ switch, re-`initialize` with the other palette and re-render.
 - **Chart-like** diagrams carry a categorical series palette — **pie**
   (`pie1`…`pie12`), **git** (`git0`…`git7`), and **user-journey**
   (`fillType0`…`fillType7`) are wired to the CVD-safe
-  [charts palette](./legends.md) (series 1 = the resolved accent).
+  [charts palette](./legends.md) (blue first; no slot is the accent).
 - **Structural** diagrams — flowchart, sequence, class, ER, state — use the
   monochrome node/edge/cluster grammar and spend the accent only on notes.
 - **Not themed: `gantt` and `timeline`.** Their colours come from

package/docs/migrations/0.11-to-0.12.md

@@ -0,0 +1,47 @@
+# Upgrade from 0.11 to 0.12
+
+0.12 replaces the categorical palette and adds a runtime resolver for
+renderers. Classes and core tokens are unchanged; the structured changes are
+in [`MIGRATIONS.json`](../../MIGRATIONS.json). If you are coming from 0.10,
+apply the [0.11 migration](0.10-to-0.11.md) first.
+
+## Review charts that relied on series 1 being the accent
+
+Until 0.11, `--chart-1` was `var(--accent)` and series 2–8 were Okabe-Ito.
+From 0.12 the eight slots are fixed hues: blue, orange, aqua, yellow, magenta,
+green, violet, red. No slot is the accent.
+
+1. Find uses of `--chart-1`, `range.category[0]`, `charts.<theme>.categorical[0]`
+   and `ACCENT` from `@ponchia/ui/charts`. `ACCENT` is removed.
+2. Where a chart meant "the brand", paint that one mark with the accent through
+   an explicit encoding (`brontoVegaAccent(theme)`, or `var(--accent)` in SVG),
+   and leave the categorical palette for categories.
+3. Where you pinned `--chart-1` to a fixed value to keep the accent out of
+   your data, delete the pin.
+4. `brontoVegaAccent(theme)` now returns the resolved `--accent`, and
+   `brontoVegaNeutral(theme)` the resolved `--text-dim`. They no longer index
+   `range.category`.
+
+## Sequential ramps have five steps
+
+`--chart-seq-6` is removed; `--chart-seq-1..5` is one blue hue, step 1 nearest
+the surface. Re-map a six-bin choropleth or heatmap to five bins, or
+interpolate between steps in your renderer.
+
+## The static Vega config is frameless
+
+`brontoVegaConfig()` sets `view.stroke: null` (no plot frame), draws a single
+series in the first categorical hue, keeps a `--panel` gap between adjacent
+rect, arc and area fills, and sets readable label sizes. A spec's own `config`
+still wins. Review dashboards that relied on the frame or the accent-coloured
+default mark.
+
+## New: categorical identity and runtime tokens
+
+- `--cat-N`, `--cat-N-tint` and `--cat-N-ink` carry the same hues for tags,
+  participants and user-chosen tints. Replace hand-picked tag colours, and
+  status tokens borrowed as category colours, with these.
+- `@ponchia/ui/renderer` resolves the live theme for canvas, WebGL and SVG
+  renderers (`readTokens`, `observeTokens`, `vegaConfig`, `xtermTheme`). A page
+  that switches skin, contrast or the OLED surface should use it instead of
+  `charts.json` or the static Vega files. See [renderer](../renderer.md).

package/docs/package-contract.md

@@ -48,6 +48,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/app.css` | `./dist/css/app.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
 | `./css/skins.css` | `./dist/css/skins.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/dataviz.css` | `./dist/css/dataviz.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/blocknote.css` | `./dist/css/blocknote.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/report.css` | `./dist/css/report.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/row.css` | `./dist/css/row.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
 | `./css/figure.css` | `./dist/css/figure.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
@@ -94,6 +95,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/unlayered/app.css` | `./css/app.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/skins.css` | `./css/skins.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/dataviz.css` | `./css/dataviz.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/blocknote.css` | `./css/blocknote.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/report.css` | `./css/report.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/row.css` | `./css/row.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/figure.css` | `./css/figure.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -150,6 +152,7 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/legends.md` | `./docs/legends.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/marks.md` | `./docs/marks.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/connectors.md` | `./docs/connectors.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/renderer.md` | `./docs/renderer.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/spotlight.md` | `./docs/spotlight.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/crosshair.md` | `./docs/crosshair.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/selection.md` | `./docs/selection.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -172,6 +175,7 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/command.md` | `./docs/command.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/interop/tailwind.md` | `./docs/interop/tailwind.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/interop/react-flow.md` | `./docs/interop/react-flow.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/interop/blocknote.md` | `./docs/interop/blocknote.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.2-to-0.3.md` | `./docs/migrations/0.2-to-0.3.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.3-to-0.4.md` | `./docs/migrations/0.3-to-0.4.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.4-to-0.5.md` | `./docs/migrations/0.4-to-0.5.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -208,6 +212,7 @@ semantic versioning contract for the surfaces listed here.
 | `./glyphs` | types: `./glyphs/glyphs.d.ts`<br>default: `./glyphs/glyphs.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./annotations` | types: `./annotations/index.d.ts`<br>default: `./annotations/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./connectors` | types: `./connectors/index.d.ts`<br>default: `./connectors/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
+| `./renderer` | types: `./renderer/index.d.ts`<br>default: `./renderer/index.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
 | `./skins` | types: `./tokens/skins.d.ts`<br>default: `./tokens/skins.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
 | `./charts` | types: `./tokens/charts.d.ts`<br>default: `./tokens/charts.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
 | `./charts.json` | `./tokens/charts.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
@@ -223,6 +228,7 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/migrations/0.9-to-0.10.md` | `./docs/migrations/0.9-to-0.10.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/adr/0006-trusted-publishing.md` | `./docs/adr/0006-trusted-publishing.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/migrations/0.10-to-0.11.md` | `./docs/migrations/0.10-to-0.11.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/migrations/0.11-to-0.12.md` | `./docs/migrations/0.11-to-0.12.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./css/discussion.css` | `./dist/css/discussion.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/unlayered/discussion.css` | `./css/discussion.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./docs/discussion.md` | `./docs/discussion.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -248,6 +254,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `schemas` | Machine-readable schemas | Declarative JSON schemas for package-adjacent report/tooling contracts. |
 | `annotations` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `connectors` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `renderer` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `shiki` | Theme data | Shiki theme JSON on the governed palette. |
 | `llms.txt` | Agent entrypoint | Shipped plain-text orientation for offline LLM/agent consumers. |
 | `CHANGELOG.md` | Release record | Shipped historical release notes. |
@@ -272,6 +279,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/legends.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/marks.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/connectors.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/renderer.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/spotlight.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/crosshair.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/selection.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -294,6 +302,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/command.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/interop/tailwind.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/interop/react-flow.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/interop/blocknote.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.2-to-0.3.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.3-to-0.4.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.4-to-0.5.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -310,6 +319,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/migrations/0.9-to-0.10.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0006-trusted-publishing.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.10-to-0.11.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.11-to-0.12.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 
 ## Artifact Provenance
 
@@ -322,8 +332,8 @@ result. The listed gates are part of `npm run check`.
 | Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh; check:exports; check:pack; check:consumer-surface; check:consumer-types; check:publint; check:attw | The complete export/file matrix in this document is generated from the manifest; packed tarball imports, concrete file resolution, and package-level type resolution are smoke-tested in clean consumers. |
 | Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/figma.variables.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; figma:variables:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved and Figma handoff values are visual tuning before 1.0. |
 | Class registry | `classes/index.js plus css/*.css selectors` | classes/classes.json; classes/index.d.ts; classes/vscode.css-custom-data.json; docs/reference.md | `npm run classes:json:build; dts:build; vscode:build; reference:build` | check:fresh; check:classes; check:contract | The typed registry, JSON vocabulary, and generated reference stay aligned with real selectors. |
-| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (48 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
-| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/; svelte/; vue/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
+| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (49 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
+| JSDoc-authored public JS | `connectors/; renderer/; annotations/; behaviors/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
 | Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; check:unit | Glyph names and render options are public. The registry stays sorted and type-covered. |
 | Display colorways | `tokens/skins.js` | css/skins.css; tokens/skins.d.ts | `npm run skins:build` | check:skins; check:contrast | Skins are opt-in root-level choices and never part of dist/bronto.css. |
 | Chart palette | `tokens/charts.js` | css/dataviz.css; tokens/charts.json; tokens/charts.d.ts | `npm run charts:build` | check:charts | Data-viz colors are opt-in, CVD-gated, and never UI chrome. |

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 695 classes across 187 component groups
+- 696 classes across 187 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
   vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
@@ -1035,6 +1035,7 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.prose` | `ui-prose` | base |
+| `cls.proseBlocks` | `ui-prose--blocks` | modifier |
 | `cls.proseCompact` | `ui-prose--compact` | modifier |
 
 ### `.ui-provenance`
@@ -1759,6 +1760,10 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--space-lg` | `1.35rem` |
 | `--space-xl` | `1.75rem` |
 | `--space-2xl` | `2.5rem` |
+| `--space-0-5` | `0.125rem` |
+| `--space-0-75` | `0.1875rem` |
+| `--space-1-5` | `0.375rem` |
+| `--space-2-5` | `0.625rem` |
 | `--tap-target` | `max(44px, 2.9rem)` |
 | `--tap-target-min` | `max(24px, 1.6rem)` |
 | `--safe-area-top` | `env(safe-area-inset-top, 0px)` |
@@ -1793,6 +1798,18 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--z-overlay` | `30` |
 | `--z-popover` | `50` |
 | `--z-toast` | `60` |
+| `--z-canvas` | `var(--z-base)` |
+| `--z-chrome` | `var(--z-sticky)` |
+| `--z-panel` | `25` |
+| `--z-modal` | `var(--z-overlay)` |
+| `--z-menu` | `var(--z-popover)` |
+| `--z-tooltip` | `70` |
+| `--z-navigation` | `80` |
+| `--ui-zoom` | `1` |
+| `--ui-px` | `1px` |
+| `--hairline` | `1px` |
+| `--focus-ring-width` | `2px` |
+| `--focus-ring-offset` | `2px` |
 | `--accent-1` | `color-mix(in oklch, var(--accent) 8%, var(--accent-ramp-end))` |
 | `--accent-2` | `color-mix(in oklch, var(--accent) 16%, var(--accent-ramp-end))` |
 | `--accent-3` | `color-mix(in oklch, var(--accent) 32%, var(--accent-ramp-end))` |

package/docs/renderer.md

@@ -0,0 +1,100 @@
+# Renderer tokens
+
+`@ponchia/ui/renderer` resolves the live bronto theme for renderers that cannot
+read CSS: Vega, xterm.js, a canvas or WebGL graph, a map, a 3D scene. Those
+engines take literal colours, so a page that switches theme, skin, contrast or
+the OLED surface has to resolve its tokens again before each repaint that
+matters.
+
+```js
+import { readTokens, observeTokens, vegaConfig, xtermTheme } from '@ponchia/ui/renderer';
+
+const tokens = readTokens(); // { scheme, bg, panel, text, line, accent, categorical, … }
+view = await embed(el, spec, { config: vegaConfig(tokens, { narrow: el.clientWidth < 480 }) });
+terminal.options.theme = xtermTheme(tokens);
+
+const stop = observeTokens((next) => {
+  terminal.options.theme = xtermTheme(next);
+  rebuildChart(vegaConfig(next));
+});
+```
+
+The static exports serve a different host. [`charts.json`](./theming.md#data-viz-palette)
+and [`tokens/vega.js`](./vega.md) are snapshots per light/dark theme for a
+report, a `file://` document or a build step. They cannot follow a skin or the
+OLED preset; this module reads the page.
+
+## What `readTokens()` returns
+
+Every colour is a renderer literal: `#rrggbb` when opaque, `rgba(r, g, b, a)`
+when translucent. Canvas, SVG, d3-color, xterm.js, three.js and MapLibre all
+accept both.
+
+| Field | Token | Use |
+| --- | --- | --- |
+| `scheme` | luminance of `--bg` | `'light'` or `'dark'` |
+| `bg`, `bgElevated`, `panel`, `panelStrong` | `--bg`, `--bg-elevated`, `--panel`, `--panel-strong` | Backgrounds; draw on `panel` |
+| `text`, `textSoft`, `textDim` | `--text`, `--text-soft`, `--text-dim` | Labels, secondary and tertiary ink |
+| `line`, `lineStrong` | `--line`, `--line-strong` | Grid and hairlines; axes and rules |
+| `accent`, `accentText`, `onAccent`, `focus` | accent family | The one emphasis, its text forms, focus |
+| `selection` | `--accent` at 27% | A translucent selection wash |
+| `success`, `warning`, `danger`, `info` | status tier | Status only, never categories |
+| `sans`, `mono` | `--sans`, `--mono` | Font stacks for a canvas renderer |
+| `categorical` | `--cat-1..8` | Eight hues in fixed order |
+| `categoricalTint` | `--cat-N-tint` | Each hue as a wash over `panel` |
+| `categoricalInk` | `--cat-N-ink` | Each hue as text, 4.5:1 on panel and tint |
+| `sequential`, `diverging` | `--chart-seq-*`, `--chart-div-*` | Ramps for magnitude and ± data |
+
+`readTokens(element)` reads the custom properties as computed on `element`, so a
+subtree that re-points tokens is honoured. Without `css/dataviz.css` on the
+page, the categorical set and the ramps fall back to the packaged palette for
+the resolved scheme, and the tint is computed over the live panel. Without a
+DOM (SSR, tests) it returns the packaged values; pass `{ scheme: 'dark' }` to
+choose.
+
+## Following changes
+
+`observeTokens(callback, { element, signal })` calls back with fresh tokens
+when the root's `data-theme`, `data-bronto-skin`, `data-contrast`,
+`data-surface`, `data-density`, `class` or `style` changes and a token's value
+moved with it, or when the system colour-scheme or contrast preference flips.
+A host that writes its own inline properties on the root every frame (a canvas
+zoom, say) costs one computed-style read per frame and no callback. Calls are
+coalesced to one per animation frame. It returns a stop function; an
+`AbortSignal` also stops it.
+
+A host that already announces its own settled appearance change can read
+`readTokens()` on that event instead and skip the observer.
+
+## Mappings
+
+- **`vegaConfig(tokens, { mode, narrow, background })`** — a Vega-Lite (default)
+  or Vega `config`. Quiet chrome in the bronto inks, no plot frame, the
+  categorical palette as `range.category` (a single series takes its first
+  hue), the sequential ramp for `ordinal`/`ramp`/`heatmap`, the diverging ramp
+  for `diverging`. `narrow` moves the legend under the plot and thins ticks;
+  `background` defaults to transparent so the host panel shows. A spec's own
+  `config` still wins where Vega merges it. The static
+  [`tokens/vega.js`](./vega.md) is this mapping applied to each theme's
+  packaged tokens.
+- **`xtermTheme(tokens)`** — an xterm.js `ITheme`: page ink on the page
+  background, the accent as cursor, the status colours for red, green, yellow
+  and blue, and the categorical magenta and aqua inks for magenta and cyan, so
+  all six ANSI hues differ.
+
+For any other engine, map the fields yourself: they are already the roles a
+renderer needs.
+
+## Conversions
+
+- **`parseColor(value)`** — a resolved CSS colour to `{ r, g, b, alpha }`,
+  clipped into sRGB: hex, `rgb()`, `hsl()`, `oklch()`, `oklab()`, `lab()`,
+  `lch()` and `color(srgb | srgb-linear | display-p3 | xyz-d65 | xyz-d50 …)`.
+  It returns null for `var()`, `color-mix()`, `light-dark()` and named colours,
+  which only a browser can compute.
+- **`formatColor(rgba)`** — `#rrggbb` or `rgba(r, g, b, a)`.
+- **`resolveColor(value, { element })`** — any colour expression to a literal,
+  asking the browser for what `parseColor()` cannot compute.
+
+The module is SSR-safe: it touches the DOM only inside a call that needs it.
+It owns no renderer and imports none.

package/docs/reporting.md

@@ -60,18 +60,18 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/report-kit.css" />
 ```
 
 Leaf-by-leaf CDN imports use the same `dist/css/` paths:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -649,7 +649,7 @@ directly; for a Vega chart, the same colours arrive through
 `brontoVegaConfig`'s `range.*` ramps, projected from `@ponchia/ui/charts.json`.
 
 For a **sequential** figure (a heatmap, a choropleth, a magnitude ramp) fill the
-cells from the single-hue ramp tokens `--chart-seq-1` … `--chart-seq-6`
+cells from the single-hue ramp tokens `--chart-seq-1` … `--chart-seq-5`
 (low → high); for a **diverging** figure (−…0…+) use `--chart-div-1` …
 `--chart-div-7` (the middle band is the neutral midpoint). Both ramps live in
 `css/dataviz.css`, and their resolved per-theme hexes are in
@@ -885,7 +885,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/stability.md

@@ -1,7 +1,7 @@
 # Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.11.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.13.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
@@ -93,7 +93,9 @@ current public-surface matrix and the release policy above still applies.
 | 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. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. Skin CSS is opt-in, not in the default bundle. |
-| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
+| BlockNote interop (`css/blocknote.css`) | Stable additive | The leaf is opt-in and maps BlockNote's `--bn-*` theme variables to bronto tokens. Which bronto token a BlockNote variable points at may tune with the tokens; newly mapped BlockNote variables are additive. Import the unlayered build after BlockNote's own stylesheet. |
+| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names (`--chart-*`, `--cat-N`, `--cat-N-tint`, `--cat-N-ink`), `CATEGORICAL_HUES`, the JSON shape, and the 8 categorical slots in fixed hue order are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
+| Renderer tokens (`@ponchia/ui/renderer`) | Stable additive | Function names, option names and the `RendererTokens` field names are public; new fields are additive. Colours are returned as `#rrggbb` or `rgba()` literals. The exact Vega/xterm mapping may tune with the token model. |
 | External renderer themes (`@ponchia/ui/mermaid`, `@ponchia/ui/mermaid.json`, `@ponchia/ui/d2`, `@ponchia/ui/d2.json`, `@ponchia/ui/vega`, `@ponchia/ui/vega.json`) | Stable additive | Theme helper names, JSON shapes, and supported renderer theme slots are public. Values are resolved colours because Mermaid, D2, and Vega cannot consume Bronto CSS variables directly. Exact colours may tune with token changes, but `check:mermaid`, `check:d2`, and `check:vega` must prove every exported theme resolves with no `var()` leaks. No renderer runtime ships. |
 | Shiki theme data (`@ponchia/ui/shiki/nothing.json`) | Stable additive | The bundled Shiki theme JSON shape and token-derived scope roles are public for syntax-highlighting consumers. Exact colours may tune with the token model and must stay generated from the governed palette. |
 | 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. |