@ponchia/ui 0.10.0 → 0.12.0

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/discussion.md

@@ -0,0 +1,64 @@
+# Discussions
+
+Use the opt-in discussion leaf for readable thread lists, messages, quotations,
+and composers in a host application:
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/discussion.css';
+```
+
+BrontoUI supplies the visual structure. The host owns storage, identity,
+thread resolution, text anchoring, unread state, and posting behavior. This leaf
+adds no JavaScript or editor dependency.
+
+## Thread structure
+
+```html
+<section class="ui-discussion" aria-labelledby="thread-title">
+  <header class="ui-discussion__header">
+    <div>
+      <h2 id="thread-title">Discussion</h2>
+      <p>Release notes</p>
+    </div>
+  </header>
+  <p class="ui-discussion__state">Open · passage attached</p>
+  <blockquote class="ui-discussion__quote">The selected passage.</blockquote>
+  <ol class="ui-discussion__messages">
+    <li class="ui-discussion__message">
+      <p class="ui-discussion__meta"><strong>Reviewer</strong> · today</p>
+      <p>Can we clarify this sentence?</p>
+    </li>
+  </ol>
+  <form class="ui-discussion__composer">
+    <label for="reply">Reply</label>
+    <textarea id="reply" name="reply" rows="4"></textarea>
+    <div class="ui-discussion__actions">
+      <button class="ui-button" type="submit">Post reply</button>
+    </div>
+  </form>
+</section>
+```
+
+Wire the form to the host's posting mechanism. Keep the draft when posting
+fails, disable duplicate submissions while a request is pending, and announce
+success only after confirmation. Use native buttons for actions and real links
+for navigation. A modal host must supply focus management and focus return.
+
+## Reading and recovery
+
+The styles use sentence case and sans-serif prose, wrap long text, and allow
+action rows to wrap in narrow panels. Keep secondary actions visually quiet
+with `ui-button--ghost`; posting is normally the primary action. The quote
+should remain visible when its anchor disappears, with a clear status and a
+host-owned way to choose a new target. Anchor status and thread resolution
+answer different questions and should be labelled separately.
+
+`ui-discussion__list` and `ui-discussion__item` style a host-owned thread index.
+Keep the list bounded and offer more results explicitly. If a canvas uses pins,
+provide the same discussions in a keyboard-accessible list. Pins, positions,
+and annotation geometry are outside this CSS leaf.
+
+The [discussion specimen](https://ponchia.github.io/bronto-ui/demo/discussion.html) includes a narrow-container
+example and a local reply/resolve demonstration. Its state lasts only until
+the page reloads.

package/docs/figure.md

@@ -61,7 +61,7 @@ when the same stage appears in a dashboard, doc page, or generated artifact.
 | --- | --- | --- |
 | `--figure-max-inline` | `.ui-figure__stage` | Maximum stage width, default `42rem`. |
 | `--figure-min-block` | `.ui-figure__stage` | Reserved stage height for late-rendered media. |
-| `--figure-key-width` | `.ui-figure__body--key-right` | Right key column width before mobile collapse. |
+| `--figure-key-width` | `.ui-figure__body--key-right` | Right key column width before the figure container stacks. |
 
 ## Boundary
 
@@ -76,3 +76,12 @@ when the same stage appears in a dashboard, doc page, or generated artifact.
 
 - [Usage](usage.md#static-reports) shows report figure composition.
 - [Reference](reference.md) lists the generated figure and report classes.
+
+## Narrow containers
+
+The figure establishes the named `bronto-figure` inline-size container. Its
+right-hand key stacks below 44rem of figure width, even in a wide browser.
+Print disables size containment and uses document flow. Keep annotation text
+and strokes within the authored `viewBox`; container layout does not reposition
+chart geometry. Verify a 280px parent with long legend names and a fallback
+table, not just a narrow viewport.

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/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.10-to-0.11.md

@@ -0,0 +1,61 @@
+# Upgrade from 0.10 to 0.11
+
+0.11 completes the readable composition direction. The structured visual
+changes are in [`MIGRATIONS.json`](../../MIGRATIONS.json). JavaScript exports,
+classes, and tokens remain available. If you are coming from 0.9, apply the
+[0.10 migration](0.9-to-0.10.md) first, including the retired adapters/modal.
+
+## Review reusable layouts
+
+Figures use their own inline-size container to stack a right-hand key below
+44rem. Decision grids and action lists stack their rows below 32rem of their
+own width, including inside an otherwise wide report. Keep the documented
+`ui-report__decision-grid` and `ui-report__actions` wrappers. Two-up comparisons
+need no wrapper: they keep at most two columns, with a 16rem reading floor.
+
+Test a 280px and 320px parent inside a 1440px browser. Check that charts have
+useful drawing width, text columns remain readable, long labels wrap and all
+sources are reachable. Zero page overflow alone does not prove those things.
+Keep authored SVG labels and annotations inside the drawing's `viewBox`, or
+provide a narrow fallback with the same information. Bronto does not own chart
+geometry. Named size containment is disabled in print; review your PDF too.
+
+## Review typography overrides by role
+
+Figure captions, legends, generated labels and command groups use sans and
+sentence case. Technical log bodies and identifiers keep mono. Inline citation
+markers have a 12px floor at a default 16px root. Do not globally replace `Doto`:
+keep intentional hero/display and readout roles.
+
+1. Find explicit `font-family: var(--display)` and `var(--dot-font)` declarations
+   in your loaded consumer styles, plus old root-size and control-height rules.
+2. Classify each use: display identity, numeric readout, heading, instruction,
+   control label or metadata. Check grouped selectors individually.
+3. Remove overrides that recreate old generic styles. Use `var(--sans)` for
+   local explanatory headings and labels; keep intentional display roles.
+4. Inspect complete tasks, not just the homepage. Include setup, result,
+   filtering, error/retry, source details and an empty state where applicable.
+5. Compare long names and translated text at narrow, laptop, and desktop widths,
+   in both themes, with keyboard and touch input.
+
+Consumer CSS outside a layer takes precedence over the package's `bronto` layer.
+Updating the package alone cannot change those explicit overrides. A prepared
+patch from an older application revision must be reintegrated and checked
+against current source before it can count as migration evidence.
+
+## Verify the package and consumer together
+
+Install the packed candidate into an isolated consumer checkout before changing
+production pins. Record the exact package version, consumer revision and screens
+checked. Update the dependency and registry lock file together after publication;
+do not commit a task-local tarball path into a production lock file.
+
+Use the [composition guide](../compositions.md) for the service's local state
+scenarios, container boundaries and report reading/print checks. Existing package
+checks remain necessary; real consumer tasks provide additional evidence.
+
+## Optional discussion UI
+
+Import `@ponchia/ui/css/discussion.css` for thread lists, quotations, messages,
+and composers. The new `ui-discussion` vocabulary is additive. It carries no
+posting behavior, storage, or editor dependency; see [Discussions](../discussion.md).

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

@@ -150,6 +150,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. |
@@ -208,6 +209,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. |
@@ -222,6 +224,11 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/adr/0005-productive-tools-and-editorial-reports.md` | `./docs/adr/0005-productive-tools-and-editorial-reports.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./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. |
 
 ## Shipped Files Allowlist
 
@@ -244,6 +251,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. |
@@ -264,9 +272,11 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/vega.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/figure.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/annotations.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/discussion.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `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. |
@@ -304,6 +314,8 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/adr/0005-productive-tools-and-editorial-reports.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `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
 
@@ -316,8 +328,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 (47 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 (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/; renderer/; 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. |
 | 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).
 
-- 683 classes across 186 component groups
+- 695 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`,
@@ -487,6 +487,23 @@ each one matches a real selector in the stylesheet.
 | `cls.diffRowRemove` | `ui-diff__row--remove` | modifier |
 | `cls.diffSplit` | `ui-diff--split` | modifier |
 
+### `.ui-discussion`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.discussion` | `ui-discussion` | base |
+| `cls.discussionActions` | `ui-discussion__actions` | part |
+| `cls.discussionComposer` | `ui-discussion__composer` | part |
+| `cls.discussionHeader` | `ui-discussion__header` | part |
+| `cls.discussionHint` | `ui-discussion__hint` | part |
+| `cls.discussionItem` | `ui-discussion__item` | part |
+| `cls.discussionList` | `ui-discussion__list` | part |
+| `cls.discussionMessage` | `ui-discussion__message` | part |
+| `cls.discussionMessages` | `ui-discussion__messages` | part |
+| `cls.discussionMeta` | `ui-discussion__meta` | part |
+| `cls.discussionQuote` | `ui-discussion__quote` | part |
+| `cls.discussionState` | `ui-discussion__state` | part |
+
 ### `.ui-display`
 
 | Registry key | Class | Kind |

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.10.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.10.0/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.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.10.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.10.0/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.10.0/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.10.0/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.10.0/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.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.10.0/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.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.10.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.12.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,13 +93,15 @@ 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. |
+| 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. |
 | 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. |
 | Figure stage (`css/figure.css`, `.ui-figure*`) | Stable additive | Figure class names, overlay/key/fallback-data slots, and report composition hooks are public. Opt-in, not in the default bundle. Bronto owns the figure frame, not chart rendering, scales, or data mapping. |
 | 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. Opt-in, not in the default bundle. Rich placement, renderer, editing, and chart/diagram adapter APIs belong to the sibling `@ponchia/annotations` package; `@ponchia/ui` does not depend on it at runtime or through public declarations. |
+| Discussions (`css/discussion.css`, `.ui-discussion*`) | Stable additive | Thread-list, message, quotation and composer class names are public. Opt-in, not in the default bundle. The host owns posting, persistence, identity, resolution, text anchors and focus management. |
 | 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. |
 | Connectors (`@ponchia/ui/connectors`, `css/connectors.css`, `.ui-connector*`, `initConnectors`) | Stable additive | Connector class names, the `data-bronto-connector` attribute contract, geometry helper function names, and recipe options are public. Helper internals/heuristics may tune before 1.0. Opt-in, not in the default bundle. |