@ponchia/ui 0.4.0 → 0.5.0

package/docs/reporting.md

@@ -0,0 +1,305 @@
+# Static reports
+
+`@ponchia/ui` can dress static, LLM-authored HTML reports without a component
+runtime. Load the normal bundle, then opt in to the report layer, chart palette,
+and annotation layer only when the report needs them.
+
+In a bundled app, package specifiers are fine because Vite or another bundler
+rewrites them:
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/report.css';
+@import '@ponchia/ui/css/dataviz.css';
+@import '@ponchia/ui/css/annotations.css';
+@import '@ponchia/ui/css/legend.css';
+```
+
+For standalone browser HTML, use real stylesheet URLs. Package specifiers like
+`@ponchia/ui/css/report.css` do not resolve in a saved `.html` file:
+
+```html
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/annotations.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/legend.css" />
+```
+
+If you copy the built CSS next to the report, keep the same relationship between
+`dist/bronto.css`, `dist/css/report.css`, `dist/css/dataviz.css`,
+`dist/css/annotations.css`, `dist/css/legend.css`, and `fonts/` so font URLs
+continue to resolve.
+
+The report layer is static and PDF-first. It does not initialize behaviors and
+does not sanitize content. If a report includes arbitrary LLM, CMS, or user HTML,
+sanitize that content before rendering it and do not initialize
+`data-bronto-*` behaviors on the generated region.
+
+## Canonical skeleton
+
+```html
+<main class="ui-report ui-report--numbered">
+  <header class="ui-report__cover">
+    <p class="ui-eyebrow">Quarterly review</p>
+    <h1 class="ui-report__title">Personal systems report</h1>
+    <p class="ui-report__subtitle">A static report generated from trusted data.</p>
+    <ul class="ui-report__meta">
+      <li><time datetime="2026-06-01">2026-06-01</time></li>
+      <li>Static HTML</li>
+      <li>Chromium PDF-ready</li>
+    </ul>
+  </header>
+
+  <nav class="ui-report__toc" aria-label="Report contents">
+    <p class="ui-eyebrow ui-eyebrow--muted">Contents</p>
+    <ol>
+      <li><a href="#summary">Executive summary</a></li>
+      <li><a href="#findings">Findings</a></li>
+    </ol>
+  </nav>
+
+  <section id="summary" class="ui-report__section">
+    <h2 class="ui-report__section-head">Executive summary</h2>
+    <div class="ui-report__summary">
+      <p>The summary block is for the decision-level conclusion.</p>
+    </div>
+    <div class="ui-statgrid">
+      <div class="ui-stat">
+        <span class="ui-stat__label">Open risks</span>
+        <span class="ui-stat__value">3</span>
+        <span class="ui-stat__delta is-neg">+1 this week</span>
+      </div>
+    </div>
+  </section>
+
+  <section id="findings" class="ui-report__section">
+    <h2 class="ui-report__section-head">Findings</h2>
+    <article class="ui-report__finding" aria-labelledby="finding-1">
+      <p class="ui-eyebrow" id="finding-1">Finding 1 — short title</p>
+      <div class="ui-prose">
+        <p>Use prose only for narrative body content.</p>
+      </div>
+    </article>
+  </section>
+</main>
+```
+
+## Composition rules
+
+- Use `ui-report` as the page-level wrapper. Add `ui-report--numbered` when
+  section headings should auto-number. Add `ui-report--compact` to tighten the
+  whole report's vertical rhythm (gap + page padding) for dense briefs — this
+  is the document-level density toggle, distinct from `ui-report__cover--compact`
+  below, which only shrinks the cover.
+- Use `ui-report__cover` for title, subtitle, author/date, and generation
+  metadata. Add `ui-report__cover--compact` for short screen-first reports.
+  Use `ui-report__header` for a compact in-page header instead of a full cover
+  (same role, no tall hero block). Author `ui-report__meta` as a `<ul>` — the
+  facts it lists are unordered.
+- Use `ui-report__section` and `ui-report__section-head` for report chapters.
+  Keep one `h1` for the report title; use ordered `h2`/`h3` headings after it.
+- Add `ui-report__section--unnumbered` to appendices, sources, or footnotes
+  when the report uses `ui-report--numbered` but the section should not count as
+  a numbered chapter.
+- Use `ui-prose` only around narrative HTML you do not fully control, such as
+  Markdown output. Do not wrap structured app/report UI in `ui-prose`.
+- Use existing primitives for shared meanings: `ui-statgrid` for KPIs,
+  `ui-alert` for persistent notices, `ui-table` for structured evidence,
+  `ui-timeline` for events, `ui-meter` for measured values, and `ui-num` for
+  non-table numeric values.
+- Give `ui-report__finding` blocks an accessible name so the visual grouping is
+  also programmatic: point `aria-labelledby` at the block's `ui-eyebrow` label
+  (give it an `id`), or lead with a real heading. Do the same for a
+  multi-part `ui-report__evidence` block; a single evidence table is already
+  named by its own `<caption>`.
+- Name the `ui-report__sources` and `ui-report__footnotes` blocks
+  (`aria-labelledby` on their `ui-eyebrow`), and link footnotes both ways:
+  an in-text `<sup><a id="fnref1" href="#fn1">1</a></sup>` to an
+  `<ol><li id="fn1">… <a href="#fnref1">↩</a></li></ol>`. They are real
+  regions, not decoration.
+- Every `<table>` that carries report data should have a `<caption>`, header
+  cells, and `.is-num` on numeric columns. (`.is-num`, `.is-pos`, `.is-neg`
+  and `.is-key` only take effect inside `.ui-table` cells and `.ui-stat`
+  deltas — they are not free-standing utilities.) Keep raw Markdown tables
+  inside `ui-prose`; use `.ui-table` for curated evidence tables. If a
+  `ui-report__evidence` block contains only a `ui-table-wrap`, the report layer
+  removes the inner frame so evidence tables do not look double-boxed.
+- Every `<figure>` should include a `figcaption` using
+  `ui-chart__caption` (chart figures) or `ui-report__caption` (any other
+  report figure); the two are interchangeable in style.
+- Do not use raw color values. Theme with `--accent`; use status tones for
+  status; use chart tokens only in chart figures.
+
+## Chart figure recipe
+
+The report layer supplies chart containers and a small static bar pattern, not a
+chart engine. The data key is the standalone, portable `.ui-legend`
+(`@ponchia/ui/css/legend.css`) — see [legends.md](./legends.md). For
+CSS/HTML/SVG charts, pair each chart color with a direct label, a pattern, or a
+fallback table.
+
+```html
+<figure class="ui-report__figure ui-chart ui-print-exact" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-chart__caption">
+    Fig 1 - Weekly focus split
+  </figcaption>
+  <ul class="ui-legend" aria-label="Series">
+    <li class="ui-legend__item">
+      <span
+        class="ui-legend__swatch"
+        style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+        aria-hidden="true"
+      ></span>
+      <span class="ui-legend__label">Research</span>
+    </li>
+    <li class="ui-legend__item">
+      <span
+        class="ui-legend__swatch"
+        style="--chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
+        aria-hidden="true"
+      ></span>
+      <span class="ui-legend__label">Delivery</span>
+    </li>
+  </ul>
+  <div class="ui-chart__plot" aria-hidden="true">
+    <div
+      class="ui-chart__bar"
+      style="--chart-value: 72%; --chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+    >
+      <div class="ui-chart__label"><span>Research</span><span>18 h</span></div>
+      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
+    </div>
+    <div
+      class="ui-chart__bar"
+      style="--chart-value: 44%; --chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
+    >
+      <div class="ui-chart__label"><span>Delivery</span><span>11 h</span></div>
+      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
+    </div>
+  </div>
+  <div class="ui-chart__fallback">
+    <div class="ui-table-wrap">
+      <table class="ui-table ui-table--dense">
+        <caption>Chart source data</caption>
+        <thead>
+          <tr><th>Series</th><th class="is-num">Hours</th></tr>
+        </thead>
+        <tbody>
+          <tr><td>Research</td><td class="is-num">18</td></tr>
+          <tr><td>Delivery</td><td class="is-num">11</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</figure>
+```
+
+For canvas or SVG libraries, import resolved series colors from
+`@ponchia/ui/charts.json` and keep the same legend/caption/fallback structure in
+the surrounding HTML.
+
+## Annotation recipe
+
+When a report chart needs an explicit callout, import
+`@ponchia/ui/css/annotations.css` and layer SVG annotations inside the same
+`ui-report__figure`. Keep the subject/connector/note text visible in the SVG or
+represented by the figure caption/fallback data.
+
+```html
+<svg viewBox="0 0 360 160" role="img" aria-labelledby="annotated-title annotated-desc">
+  <title id="annotated-title">Weekly focus chart with peak callout</title>
+  <desc id="annotated-desc">The annotation marks the research peak.</desc>
+  <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(210, 58)">
+    <path class="ui-annotation__subject" d="M0,-18A18,18 0 1 1 0,18A18,18 0 1 1 0,-18Z" />
+    <path class="ui-annotation__connector" d="M15.556,-7.424L84,-40" />
+    <g class="ui-annotation__note" transform="translate(84, -40)">
+      <path class="ui-annotation__note-line" d="M0,0H92" />
+      <text class="ui-annotation__title" y="-8">Peak</text>
+      <text class="ui-annotation__label" y="12">18 research hours</text>
+    </g>
+  </g>
+</svg>
+```
+
+For generated SVG, use `@ponchia/ui/annotations` to compute connector and
+subject path strings. Full annotation recipes and the complete variant list are
+in `docs/annotations.md`; the shipped `demo/annotations.html` page is the
+visual specimen.
+
+## Timeline recipe
+
+Incident reviews and research logs should use the existing timeline primitive
+with its required item and time parts. Do not emit a bare list and expect it to
+style itself.
+
+```html
+<ol class="ui-timeline">
+  <li class="ui-timeline__item">
+    <time class="ui-timeline__time" datetime="2026-06-01T09:12:00">09:12</time>
+    <span>Latency alert fired for p95 over threshold.</span>
+  </li>
+  <li class="ui-timeline__item" aria-current="step">
+    <time class="ui-timeline__time" datetime="2026-06-01T09:54:00">09:54</time>
+    <span>Latency returned to baseline.</span>
+  </li>
+</ol>
+```
+
+## Common templates
+
+- Executive brief: compact cover, one summary block, KPI `ui-statgrid`, short
+  findings, and sources.
+- Research brief: compact header, decision frame, evidence table, quotes or
+  prose excerpts, and sources.
+- Incident review: compact cover, summary, `ui-timeline`, corrective-action
+  evidence table, and footnotes.
+- Project status: compact header, KPI `ui-statgrid`, chart figure with fallback
+  data, print-only notes, and unnumbered appendix.
+
+## Print and PDF
+
+The supported export target is modern Chromium print/PDF. Two ways to produce
+the file:
+
+- **By hand:** open the report in Chrome/Edge → Print (Cmd/Ctrl+P) → "Save as
+  PDF". In **More settings**, enable **Background graphics** (the dialog's
+  equivalent of `printBackground` — without it chart fills and swatches drop
+  out), and pick the paper size there. Paper size is a browser print setting,
+  not a token; the layer only themes the page _margin_ via
+  `--report-page-margin`.
+- **Headless (agents/CI):** `await page.pdf({ format: 'A4', printBackground: true })`
+  with Playwright or Puppeteer.
+
+The report prints ink-on-white regardless of the on-screen theme. Older
+HTML-to-PDF engines are not part of the browser floor and may not support
+cascade layers, `oklch()`, `color-mix()`, `:has()`, or modern paged-media
+behavior.
+
+- Use `ui-print-only` for content that should appear only in print.
+- Use `ui-screen-only` for navigation or helper content that should not print.
+- Use `ui-break-before` and `ui-break-after` for deliberate page boundaries.
+- Use `ui-keep` on short figures, findings, and summary blocks that should not
+  split across pages.
+- Use `ui-print-exact` on charts whose fills and patterns must survive PDF
+  export.
+- External links inside `ui-prose` print their URL automatically through the
+  base print stylesheet.
+
+**Not provided** (use the browser's paged-media features, or author the markup
+yourself): running headers/footers with "Page X of Y", automatic table-of-contents
+pagination, multi-column layout, and automatic citation/footnote numbering. The
+report layer is a document grammar, not a paged-media or citation engine — do not
+fake page numbers with inert markup.
+
+## LLM checklist
+
+Before returning a report, an LLM should verify:
+
+- All `ui-*` classes exist in `@ponchia/ui/classes`.
+- The document has one `h1`, ordered headings, and a single main report region.
+- Tables have captions and header cells.
+- Charts have captions, direct labels or legends, and fallback data.
+- No raw chromatic colors appear in inline styles.
+- No remote scripts, styles, iframes, or images are required for the report.
+- Generated/untrusted body HTML was sanitized before insertion.

package/docs/selection.md

@@ -0,0 +1,40 @@
+# Selection states
+
+`@ponchia/ui/css/selection.css` is a tiny, **cross-cutting selection-emphasis
+vocabulary** — the carve-out from "brush/lasso". Bronto does **not** do region
+selection or hit-testing (that needs your scales and geometry). It ships only
+the *states* an item can be in once your code has decided what's selected, so
+the same emphasis works on a chart mark, a table row, a list item, or a map
+region.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/selection.css';
+```
+
+| Class | State |
+| --- | --- |
+| `ui-sel` | Base — opt the element into the emphasis transitions. |
+| `ui-sel--on` | In the selection (accent outline). |
+| `ui-sel--off` | Excluded / filtered out (dimmed). |
+| `ui-sel--maybe` | A live-brush candidate (dashed outline). |
+
+```html
+<rect class="ui-sel ui-sel--on" … />
+<tr class="ui-sel ui-sel--off">…</tr>
+```
+
+```js
+import { ui } from '@ponchia/ui/classes';
+el.className = ui.sel({ state: inBrush ? 'maybe' : selected ? 'on' : 'off' });
+```
+
+Your code adds/removes these classes from its own brush, filter, or selection
+logic — Bronto only styles them. `--off` uses `opacity` (which survives
+forced-colors), and `--on` falls back to the system `Highlight` color in
+forced-colors so the selection stays visible.
+
+> **Why no brush behavior?** A rectangular brush or lasso must translate a
+> dragged region into a data domain (or test points against a polygon), which
+> requires owning the chart's scales/geometry — across Bronto's line. Bring your
+> own selection logic; use these classes to render the result.

package/docs/sources.md

@@ -0,0 +1,110 @@
+# Sources, citations & provenance
+
+`@ponchia/ui/css/sources.css` is an opt-in **trust layer** for generated
+reports, AI output, audits, and docs — the grammar that answers _"where did
+this come from?"_. Generic UI kits have tags and footnotes; this is a small,
+explicit vocabulary for sources and their trust state.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sources.css';
+```
+
+Bronto owns the visual grammar and the trust **states**. The host owns fetching,
+citation numbering, permission checks, and whether a source is actually
+trustworthy. The state is carried by a rationed tone **and** an author-written
+label, so it never relies on colour alone (WCAG 1.4.1). Not in the core bundle.
+
+## Trust states
+
+A cross-cutting trust-state class — `ui-src--verified`, `ui-src--stale`, and the
+rest in the table below — sets the tone on a citation chip, source card, or
+provenance item. Always pair it with a word: the colour is a second channel, not
+the only one.
+
+| State | Class | Tone |
+| --- | --- | --- |
+| Verified | `ui-src--verified` | success |
+| Reviewed (by a human) | `ui-src--reviewed` | accent |
+| Generated | `ui-src--generated` | info |
+| Unverified | `ui-src--unverified` | muted |
+| Stale | `ui-src--stale` | warning |
+| Conflict | `ui-src--conflict` | danger |
+
+## Inline citation — `.ui-citation`
+
+A reference marker on a real `<a>` or `<button>` (the visual index is never the
+only label — give it an accessible name).
+
+```html
+<p>
+  Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.
+</p>
+
+<!-- Named-source pill, with a leading trust dot: -->
+<a class="ui-citation ui-citation--chip ui-src--verified" href="#s1">
+  Q3 incident review
+</a>
+```
+
+## Source card — `.ui-source-card`
+
+A single source preview: title, origin, time, excerpt, actions. The
+`border-inline-start` carries the trust tone.
+
+```html
+<article class="ui-source-card ui-src--generated">
+  <h3 class="ui-source-card__title">Model output — pricing summary</h3>
+  <p class="ui-source-card__origin">gpt-x · internal</p>
+  <p class="ui-source-card__time">2026-06-01 09:42</p>
+  <p class="ui-source-card__excerpt">The migration cut p95 latency by 38%…</p>
+  <div class="ui-source-card__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Open</button>
+  </div>
+</article>
+```
+
+## Source list — `.ui-source-list`
+
+A references section: a reset list of source cards (or rows).
+
+```html
+<ol class="ui-source-list">
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--verified">…</article></li>
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--stale">…</article></li>
+</ol>
+```
+
+## Provenance — `.ui-provenance`
+
+A compact metadata row beside generated content — each `__item` carries a trust
+dot and a label.
+
+```html
+<p class="ui-provenance">
+  <span class="ui-provenance__item ui-src--generated">Generated</span>
+  <span class="ui-provenance__item ui-src--verified">3 sources</span>
+  <span class="ui-provenance__item ui-src--reviewed">Human-reviewed</span>
+</p>
+```
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.citation({ chip: true, state: 'verified' });
+// "ui-citation ui-citation--chip ui-src--verified"
+ui.source({ state: 'generated' }); // "ui-source-card ui-src--generated"
+ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"
+```
+
+## Accessibility & print
+
+- A citation must be a real link or button with a stable accessible name; the
+  bracketed index alone is not enough.
+- The trust state must be readable as text — the tone dot/border is decorative
+  reinforcement. Under `forced-colors`, dots and borders fall back to
+  `CanvasText`, so the label remains the channel.
+- Tone dots and the card's tone border carry `print-color-adjust: exact`, so
+  they survive printing; expand citation URLs in print where it helps the reader.

package/docs/spotlight.md

@@ -0,0 +1,78 @@
+# Spotlight (guided focus)
+
+`@ponchia/ui/css/spotlight.css` is an opt-in **guided-focus overlay** — a
+dimming layer with a cutout over a target element, an optional ring, and a
+callout note. It's the *visual language* of a product tour or onboarding step.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/spotlight.css';
+```
+
+**Bronto is not a tour engine.** It owns the look and (via `initSpotlight`)
+positions the cutout over a target. Step order, advancing, persistence, and
+whether the overlay is shown are the host's job — Bronto deliberately stays out
+of that state machine.
+
+## Markup
+
+```html
+<div
+  class="ui-spotlight ui-spotlight--ring"
+  data-bronto-spotlight
+  data-target="save-button"
+  role="region"
+  aria-label="Tour"
+>
+  <div class="ui-spotlight__hole"></div>
+
+  <div class="ui-tour-note" style="position: absolute; …place near the hole…">
+    <span class="ui-tour-note__step">Step 2 of 4</span>
+    <h2 class="ui-tour-note__title">Save your work</h2>
+    <p class="ui-tour-note__body">Changes autosave, but you can force a save here.</p>
+    <div class="ui-tour-note__actions">
+      <button class="ui-button ui-button--ghost" type="button">Skip</button>
+      <button class="ui-button" type="button">Next</button>
+    </div>
+  </div>
+</div>
+```
+
+```js
+import { initSpotlight } from '@ponchia/ui/behaviors';
+const stop = initSpotlight(); // positions the cutout; re-places on resize/scroll
+// Advance the tour by pointing at the next target — the cutout follows:
+document.querySelector('[data-bronto-spotlight]').dataset.target = 'next-thing';
+// Hide it when the tour ends (host-owned):
+document.querySelector('[data-bronto-spotlight]').hidden = true;
+```
+
+## Pieces
+
+| Class | Role |
+| --- | --- |
+| `ui-spotlight` | The fixed overlay. Non-blocking (`pointer-events: none`) — a visual highlight, not a modal trap. |
+| `ui-spotlight__hole` | The cutout. Dims the page via one box-shadow; positioned by `--spot-x/y/w/h`. |
+| `ui-spotlight--ring` | Adds an accent ring around the cutout. |
+| `ui-tour-note` | The callout card (re-enables pointer events for its controls). |
+| `ui-tour-note__step` / `__title` / `__body` / `__actions` | Callout parts. |
+
+`ui.spotlight({ ring })` builds the overlay class string.
+
+## How positioning works
+
+`initSpotlight` reads each `[data-bronto-spotlight]`'s `data-target` id, measures
+that element with `getBoundingClientRect`, and sets `--spot-x/y/w/h` (viewport
+coordinates) on the overlay. Because the overlay is `position: fixed`, those map
+directly. It re-places on resize, scroll, and whenever `data-target` changes —
+so stepping a tour is just updating `data-target`. `--spot-pad` insets the
+cutout from the target; `--spot-radius` rounds it.
+
+## Accessibility notes
+
+- The overlay is **non-blocking by design** (the dim is a box-shadow, not an
+  interaction trap). If a step must block interaction, that's a host concern —
+  add your own inert/`aria-hidden` handling around it.
+- Put the tour's real content in `.ui-tour-note` (a focusable region with a
+  heading), not in the visual dim, so screen-reader users get the same guidance.
+- Keep the callout's label stable and move focus to it when a step opens (host).

package/docs/stability.md

@@ -0,0 +1,52 @@
+# Public API Stability
+
+`@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
+patches are non-breaking. This matrix defines what counts as public API.
+
+| Surface | Stability | Contract |
+| --- | --- | --- |
+| CSS package root (`@ponchia/ui`) | Stable | CSS-only entrypoint. CSS side-effect imports are supported in CSS-aware bundlers; Node/runtime JS root imports are not. |
+| JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
+| CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
+| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
+| Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
+| `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
+| Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. (A computed-style smoke test guards the OLED `--bg` flip; the others are unverified.) |
+| Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
+| Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
+| Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
+| `.ui-icon` mask renderer | Stable | Class name, `--icon-size`, currentColor inheritance, and `--icon-mask` contract are public. The internal data URL encoding is not. |
+| React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
+| Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
+| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
+| Reports (`css/report.css`, `.ui-report*`, `.ui-chart*`, print utilities) | Stable additive | Report class names, BEM part names, chart helper class 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`. |
+| Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
+| Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
+| Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
+| 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. |
+| Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
+| Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
+| Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
+| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the seven analytical leaves (annotations, legend, marks, connectors, spotlight, crosshair, selection). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
+| Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
+| Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
+| Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
+| Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |
+| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
+| Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
+| Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
+
+## Trust Boundary
+
+Behaviors assume trusted application markup. If a delegated root includes
+untrusted CMS or user HTML, sanitize it first or do not initialize behaviors on
+that root. The behavior layer intentionally lets authored `data-bronto-*`,
+`aria-controls`, and `id` relationships control elements inside the root.
+Dialog, disclosure, and popover targets resolve root-first and then
+document-wide for body/portal-mounted overlays; scoped roots are not a sandbox
+for untrusted markup.
+
+The one-node glyph mask renderer emits inline style/custom-property data. Apps
+with a strict CSP should either allow the required `data:` mask/image source and
+inline custom-property style path, or use the DOM dot/solid renderers.