@ponchia/ui 0.6.4 → 0.6.6

package/docs/frontier-primitives.md

@@ -0,0 +1,286 @@
+# Frontier primitives
+
+This is the strategic memory for Bronto's design-system differentiation. The
+goal is not to out-catalog Radix, Carbon, Atlassian, Fluent, Spectrum, or
+shadcn. Those systems already cover the standard component center: buttons,
+forms, dialogs, tabs, menus, cards, tables, tooltips, badges, navigation,
+loaders, and date inputs.
+
+Bronto should instead own the interface layer that makes complex work legible:
+explanation, provenance, relationships, command access, workbench ergonomics,
+generated reports, and durable system state. In short: interfaces that explain
+themselves.
+
+## Boundary
+
+The pattern that worked for annotations should stay the rule:
+
+- Bronto owns visual grammar, class vocabulary, token use, accessibility
+  guidance, pure geometry helpers, and small idempotent behavior kernels.
+- The host owns domain state, data mapping, chart scales, tour step order,
+  command execution, persistence, AI/tool orchestration, and announcements that
+  need product-specific wording.
+- New surfaces stay opt-in. They should not enter `dist/bronto.css` by default
+  unless they are clearly universal chrome.
+- Prefer CSS and markup first. Add JS only when the browser cannot express the
+  behavior without measuring, filtering, keyboard state, or pointer tracking.
+
+This keeps Bronto useful across Astro, SvelteKit, React, Solid, Qwik, plain
+HTML, and generated static reports without becoming a framework component kit.
+
+## Already aligned in 0.5.0
+
+The analytical/generated-report suite is already the first concrete expression
+of this strategy:
+
+- `annotations`: subject / connector / note grammar for SVG figures.
+- `legends`: data keys that prevent chart meaning drifting from palette tokens.
+- `marks`: semantic prose evidence and passage brackets.
+- `connectors`: DOMRect leader lines between related UI regions.
+- `spotlight`: the visual language of guided focus without a tour engine.
+- `crosshair`: pointer/ruler/readout surface without chart-domain mapping.
+- `selection`: shared selected/excluded/candidate states without hit-testing.
+- `sources`: citation / source-card / source-list / provenance with a
+  trust-state grammar (candidate #1 below — now shipped in 0.5.0).
+
+These are intentionally not a chart framework. They are communication
+primitives.
+
+## 2026 scout batch — report & evidence grammar
+
+A multi-source scout pass (2026-06-03) surfaced the next concrete batch. All
+four are novel, Baseline-clean on the 2026 floor, and squarely on the
+"explains itself" north star — the report / review / evidence lane. They ship
+as opt-in surfaces (never default `dist/bronto.css`), CSS-and-markup first,
+each with the same host-owns-state boundary that kept the chart renderer out in
+0.6.0. **All four shipped** — `ui-diff` in PR #97, then `ui-code` / `ui-spark` /
+`ui-sidenote` in PR #100 — opt-in leaves, unreleased on the 0.6.0 package line.
+
+### `ui-diff` — line/row change grammar  ✅ shipped
+
+A CSS-grid gutter grammar (`ui-diff`, `__row --add/--remove/--context`,
+`__hunk`, `--unified/--split`). The host supplies pre-classified rows; Bronto
+only paints — redundant `::before` +/- sign glyphs (never colour-only), tone
+tints, and optional subgrid alignment that degrades to plain grid. Composes
+with the shipped `ui-compare--2up`. Boundary: all tokenizing, row alignment,
+and hunk computation stay in the host — the moment Bronto parses or aligns rows
+it crosses the line that deleted the bar renderer in 0.6.0. Diff is the most
+explanation-dense surface Bronto does not yet own.
+
+### `ui-code` — fenced-code evidence chrome
+
+A static code surface that paints already-tokenized markup (head bar,
+line-number gutter via CSS counters, `.is-add` / `.is-del` / `.is-hl` line
+states) and **never parses**. The host — or Shiki, via the shipped
+`shiki/nothing.json` token-colour theme — supplies the token spans; Bronto owns
+chrome only. Code-as-evidence for changelogs, version history, and generated
+reports; pairs with the `.ui-src` provenance pill and marks. Degrades to a
+plain scrollable `<pre>`.
+
+### `ui-spark` — inline datawords
+
+Word-sized inline microcharts (line / bar / tristate / win-loss) for
+trend-in-a-sentence inside reports and dense tables — the inline-series gap the
+scalar `ui-delta` / `ui-num` / `ui-stat` leave open, and one block-level Vega
+will not fill. The host normalises each point to `0..1` (`--v`); Bronto paints
+geometry via inline SVG + custom properties + `currentColor`. No JS,
+SSR-static, print-survivable. Boundary: Bronto refuses raw values and
+min/max/scale computation, and every spark carries a host-supplied text / aria
+equivalent (a bare sparkline is opaque to AT).
+
+### `ui-sidenote` / `ui-marginnote` — marginal explanation
+
+Numbered margin sidenotes plus unnumbered marginnotes with CSS-counter
+numbering and zero-JS responsive collapse (the Tufte `:checked` pattern);
+degrades to an inline aside on narrow viewports and a footnote under
+`@media print`. The channel for evidence, caveats, and provenance asides that
+do not belong in the main column. Scope it as typographic margin notes,
+reconciled with the existing `report.css` `__footnotes` numbering — not a
+second backref engine.
+
+## 2026 scout batch #2 — explanation & provenance cluster  ✅ shipped
+
+A second scout pass (2026-06-04) ranked the next five and they all shipped as
+opt-in leaves (unreleased on the 0.6.0 line). All clear web-native + fit +
+leverage, and sit dead-centre on the explanation / provenance / orientation
+lanes — not component parity.
+
+### `ui-textref` — deep-link to the cited sentence  ✅ shipped
+
+`@ponchia/ui/css/textref.css`. A citation whose `href` is a URL Text Fragment
+(`#…:~:text=`): the browser scrolls to + highlights the exact quoted text, and
+Bronto owns the on-brand `::target-text` paint (`--textref-highlight`). The
+cheapest high-leverage item in the scout — extends the `sources.css` trust layer
+from "label a source" to "point inside it". The host builds the fragment URL (a
+three-line pure encoder, documented); no kernel. Degrades cleanly where Text
+Fragments are unsupported.
+
+### `ui-bullet` — Stephen-Few bullet graph  ✅ shipped
+
+`@ponchia/ui/css/bullet.css`. Measure bar + target tick + 2–3 grayscale
+qualitative bands — the canonical SLO / error-budget figure `ui-meter` cannot
+encode. Same host-normalises-to-0..1 contract as `ui-spark` (`--v` measure,
+`--t` target, `--band-lo`/`--band-hi` boundaries; `ui.bulletMeasure({ tone })`).
+Few designed it grayscale, which is exactly the Nothing palette. Requires a
+host-written `role="img"` + `aria-label`.
+
+### `ui-term` / `ui-glossary` — inline glossary  ✅ shipped
+
+`@ponchia/ui/css/term.css`. The accessible upgrade of the touch/keyboard-broken
+`abbr[title]`: a `ui-term` `<button popovertarget>` whose `ui-def` definition is
+a native `[popover]`, plus an end-of-document `ui-glossary` `<dl>`. The native
+popover pairing gives open/Esc/light-dismiss for free — no kernel. Popovers don't
+print, so the printed doc leans on the glossary block.
+
+### `ui-toc` — scrollspy table of contents  ✅ shipped
+
+`@ponchia/ui/css/toc.css`. A sticky contents rail (`--toc-top`) whose active
+entry keys on `aria-current="true"`. CSS can't know the in-view section, so the
+host mirrors it — statically, or with a small copy-paste IntersectionObserver
+(no kernel ships). Degrades to a plain anchored list.
+
+### `ui-tree` — hierarchy outline  ✅ shipped
+
+`@ponchia/ui/css/tree.css`. A depth-indented outline on nested native
+`<details>` (`ui-tree__branch`/`__leaf`/`__summary`/`__label`; add `name` for an
+exclusive-accordion group). Composes the disclosure grammar `ui-accordion` owns —
+it does not reinvent it. A11y honesty: a `<details>` group is a disclosure group,
+NOT an ARIA `tree`; the roving-focus kernel is deferred behind a real consumer
+(e.g. a workbench file pane).
+
+## Next strong candidates
+
+### 1. Source, citation, and provenance UI — ✅ shipped in 0.5.0
+
+Shipped as `@ponchia/ui/css/sources.css` (`ui-citation`/`ui-source-card`/
+`ui-source-list`/`ui-provenance` + the cross-cutting `ui-src--*` trust states),
+matching the surface below. The optional `initSources` behavior now adds
+source-card focus, a temporary `.is-source-active` cue, and lightweight preview
+metadata over existing citation/source IDs.
+
+Why it matters: AI output, generated reports, audit views, docs, and operational
+tools all need to answer "where did this come from?" Normal UI kits have tags
+and footnotes, but not a trust grammar. The shipped surface and its trust-state
+vocabulary are documented with the component; richer preview popovers remain
+host-owned.
+
+### 2. Lifecycle and system-state UI — 🟡 `ui-state` family shipped in 0.5.0
+
+Shipped as `@ponchia/ui/css/state.css` (`ui-state` + the canonical state matrix
++ `ui-syncbar`), matching the "good first build" below. `ui-job` (background
+progress) and `ui-conflict` (resolution affordances) remain deferred until a
+consumer needs them; `ui-review-state` is covered by the reviewed/needs-review
+state modifiers.
+
+Why it matters: serious apps spend a lot of time in states like saving, saved,
+queued, offline, stale, retrying, conflicted, locked, reviewed, and background
+job running. These states are usually improvised per product, so even good apps
+feel inconsistent. Still deferred: `ui-job` (background progress) and
+`ui-conflict` (resolution affordances), each until a consumer needs it.
+
+### 3. Command-first UI — ✅ shipped in 0.5.0
+
+The keyboard-hint primitive (`.ui-shortcut` + `.ui-shortcut__sep` over `.ui-kbd`,
+core chrome) landed first, then the `ui-command` palette: the
+`@ponchia/ui/css/command.css` shell + the `initCommand` `data-bronto-command`
+behavior (filter, roving focus, `bronto:command:select`/`close`) + `useCommand`
+bindings. The host still owns the action registry and execution — Bronto only
+filters and navigates.
+
+Why it matters: command palettes turn a product from a page collection into a
+tool. Existing libraries such as cmdk and kbar are good, but Bronto can own the
+design-system contract: shortcuts, actions, groups, disabled reasons, context,
+and command result feedback. The host still owns the action registry and
+execution; global Cmd/Ctrl+K stays opt-in by design.
+
+### 4. Workbench UI — 🟡 inspector / property / selectionbar shipped in 0.5.0
+
+Shipped as `@ponchia/ui/css/workbench.css` (`ui-inspector`, `ui-property`,
+`ui-selectionbar`) — the low-risk CSS core below. Resizable split panes
+(`ui-splitter`, an ARIA window-splitter behavior) and drag handles remain
+deferred until a consumer needs them.
+
+Why it matters: real tools need inspectors, object action bars, split panes,
+resize handles, property rows, dense trees, and selected-object affordances.
+Generic UI kits tend to stop at cards/tables/forms, leaving every app to build
+its own half-consistent workbench. Still open: a `ui-splitter` ARIA
+window-splitter behavior (focusable separator, `aria-valuemin/max/now`,
+arrow-key resize) and drag/drop affordances — both deferred, and Bronto should
+style drag handles, not become a drag-and-drop framework.
+
+### 5. Generated-content and AI trust primitives — 🟡 shipped in 0.5.0
+
+Shipped as `@ponchia/ui/css/generated.css` (`ui-generated`, `ui-origin-label`,
+`ui-reasoning`, `ui-tool-log` / `ui-tool-call`) — the origin/provenance labels,
+generated-content wrapper, and tool-call log of the "good first build" below.
+Chat-thread components and a `ui-confidence` widget are intentionally not shipped.
+
+Why it matters: AI interfaces are becoming common, but most UI systems either
+ship chat bubbles or nothing. Bronto should not become a chat framework. It
+should own the trust surfaces around generated content. The host still owns model
+metadata, tool execution, traces, redaction, and safety; chat-thread components
+and a `ui-confidence` widget are intentionally not shipped (never fabricate a
+precision signal the product does not have).
+
+## Priority
+
+The CSS cores of candidates 1–5 shipped in 0.5.0, the 2026 scout batch shipped
+in PRs #97/#100, and scout batch #2 (textref / bullet / term / toc / tree)
+shipped 2026-06-04.
+
+**The proven lane is report / provenance / explanation** — it is the only lane
+with a real consumer (LLM-authored reports). The command, workbench, and
+durable-state lanes shipped their CSS cores and have had **no non-demo
+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.
+
+### Report-lane candidates (build only after the routing hub carries them)
+
+From the 2026-06-09 local scout — kept on merit, deliberately NOT started
+until the reporting.md routing/adoption pass has landed (shipping more leaves
+into an unrouted hub repeats the discoverability gap):
+
+1. `ui-interval` — honest low–high uncertainty span + ± chip, inline in
+   reports; the error-bar grammar generic kits never ship.
+2. `ui-clamp` — N-line clamp + fade + native show-more for claim-basis and
+   source excerpts (`-webkit-line-clamp` + `mask-image` + `<details>`).
+3. `ui-highlights` — cited-evidence / search-hit spans painted from host
+   Ranges via the CSS Custom Highlight API (progressive enhancement; clean
+   no-op below the floor).
+
+### Dormant (build with the first real app consumer, not before)
+
+- `ui-job` / `ui-conflict` lifecycle surfaces (candidate 2).
+- `ui-splitter` ARIA window-splitter behavior + drag affordances
+  (candidate 4), which is also the gating consumer for `ui-tree`'s deferred
+  roving-focus tree kernel.
+- Any command/workbench follow-ons beyond the shipped CSS cores.
+
+Dormant items stay gated on a real consumer needing them. This posture keeps
+Bronto differentiated while staying inside its core philosophy: small,
+framework-agnostic primitives that make complex interfaces clearer.
+
+## Inspiration watchlist
+
+These are examples of the kind of older or under-supported work worth mining for
+ideas. They are not dependency recommendations; the useful part is the shape of
+the primitive, not the implementation stack.
+
+| Project | Useful idea | Bronto-shaped lesson |
+| --- | --- | --- |
+| Susie Lu `d3-annotation` | Subject / connector / note grammar for explaining SVG figures. | Keep annotation as a grammar, not a chart engine or editor. |
+| Susie Lu `d3-legend` | Colour, size, and symbol legends as reusable figure keys. | Legends belong in the design system because they explain visual encodings. |
+| Twitter `labella.js` | One-dimensional label collision avoidance for timelines and dense axes. | A tiny `declutterLabels` helper can be more valuable than another component. |
+| `D3-Labeler` / `d3fc-label-layout` | Greedy/simulated-annealing label placement. | Direct labels need layout helpers; host still owns chart scales and data. |
+| `d3-lasso` | Possible / not-possible / selected / not-selected states while drawing a region. | Bronto should own selection vocabulary and maybe region visuals, not hit-testing. |
+| `leader-line` / `react-xarrows` | Lines and arrows between DOM elements. | DOMRect connectors are broadly useful, but should be styleable and token-bound. |
+| LinkedIn `hopscotch` / `chardin.js` | Guided tours as target + note + step metadata. | Bronto should own spotlight visuals, not the tour state machine. |
+| `Waypoints` / `gumshoe` | Scroll-triggered section awareness and scrollspy navigation. | Long documents and reports may need section-progress/navigation affordances. |
+| `mark.js`, `Rangy`, `TextHighlighter` | Search hits, user text selections, persistent text highlights. | Evidence/source marks need careful semantics around ranges and generated content. |
+| `Mousetrap` / `Keypress` | Keyboard shortcut grammar and key sequences. | Command-first UI needs shortcut display and action dispatch boundaries. |
+| `Split.js` | Small, unopinionated resizable split views. | Workbench panes are worth styling; behavior must follow accessible splitter rules. |
+| jQuery Steps / old wizard plugins | Multi-step flows with progress, validation, and branching. | If Bronto adds stepper/wizard UI, it should be state vocabulary first. |
+| `progressbar.js` | Lightweight progress shapes and determinate/indeterminate motion. | Lifecycle/job UI should make long-running work persistent and legible. |
+| `react-json-view` / old JSON viewers | Inspectable structured data with collapse/copy/path affordances. | Generated/tool output needs compact inspector primitives without a React lock-in. |
+| old diff viewers / `jsdifflib` | Side-by-side and inline change explanation. | Becoming `ui-diff` (2026 batch): Bronto paints the row/gutter grammar, the host pre-classifies rows — parsing and alignment stay outside Bronto. |

package/docs/package-contract.md

@@ -0,0 +1,263 @@
+<!-- @ponchia/ui - GENERATED from package.json by scripts/gen-package-contract.mjs.
+     Do not edit by hand; run `npm run package-contract:build`.
+     Drift-checked in CI through check:fresh. -->
+
+# Package Contract
+
+This is the manifest-facing contract for `@ponchia/ui`: every exported
+subpath, every `files` allowlist entry, and the committed generated-artifact
+pipeline. It complements [stability.md](./stability.md), which defines the
+semantic versioning contract for the surfaces listed here.
+
+## Contract Summary
+
+| Surface group | Stability | Contract |
+| --- | --- | --- |
+| CSS root and `dist/bronto.css` | Stable | CSS-only default bundle. CSS side-effect imports are supported in CSS-aware bundlers; Node/runtime JS root imports are not. |
+| CSS leaves | Stable additive | Direct leaves are generated as layered `dist/css/*.css` exports; raw unlayered source leaves are explicit escape hatches under `./css/unlayered/*`. |
+| JS subpaths | Stable | ESM-only public subpaths. Runtime behavior is SSR-safe and dependency-free unless a framework binding declares an optional peer. |
+| Machine-readable data | Stable additive | JSON/data exports are for non-JS hosts, validators, renderers, and offline agents. Additive fields are allowed within a compatible minor. |
+| Shipped docs | Stable paths | Curated Markdown/text docs ship inside the npm tarball for offline readers. Generated docs are regenerated and drift-checked. |
+| Fonts | Stable path pattern | Doto assets ship under `fonts/*` with their OFL license. |
+| Repo tooling, demos, tests, examples, workflows | Internal | Useful for development and learning, but not shipped runtime API unless a path is explicitly exported below. |
+
+## Export Matrix
+
+| Export | Target | Group | Stability | Contract |
+| --- | --- | --- | --- | --- |
+| `.` | style: `./dist/bronto.css`<br>default: `./dist/bronto.css` | CSS root bundle | Stable | CSS-only package root. Supported as a CSS side-effect import in CSS-aware bundlers; not a Node/runtime JS entrypoint. |
+| `./dist/bronto.css` | `./dist/bronto.css` | Flattened CSS bundle | Stable path | The prebuilt default stylesheet. Generated from css/core.css and byte-checked by check:dist. |
+| `./css` | `./css/core.css` | CSS source fan-out | Stable path | Bundler entrypoint for css/core.css. It preserves source @import boundaries and layer behavior. |
+| `./css/core.css` | `./css/core.css` | CSS source fan-out | Stable path | Source fan-out file for consumers that want the authored leaf graph through a bundler. |
+| `./css/tokens.css` | `./dist/css/tokens.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/fonts.css` | `./dist/css/fonts.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/base.css` | `./dist/css/base.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/motion.css` | `./dist/css/motion.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/dots.css` | `./dist/css/dots.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/navigation.css` | `./dist/css/navigation.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/site.css` | `./dist/css/site.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/content.css` | `./dist/css/content.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/primitives.css` | `./dist/css/primitives.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/forms.css` | `./dist/css/forms.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/feedback.css` | `./dist/css/feedback.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/overlay.css` | `./dist/css/overlay.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/disclosure.css` | `./dist/css/disclosure.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./css/table.css` | `./dist/css/table.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
+| `./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/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/annotations.css` | `./dist/css/annotations.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/legend.css` | `./dist/css/legend.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/marks.css` | `./dist/css/marks.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/connectors.css` | `./dist/css/connectors.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/spotlight.css` | `./dist/css/spotlight.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/crosshair.css` | `./dist/css/crosshair.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/selection.css` | `./dist/css/selection.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/sources.css` | `./dist/css/sources.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/diff.css` | `./dist/css/diff.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/code.css` | `./dist/css/code.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/spark.css` | `./dist/css/spark.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/sidenote.css` | `./dist/css/sidenote.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/textref.css` | `./dist/css/textref.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/bullet.css` | `./dist/css/bullet.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/term.css` | `./dist/css/term.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/toc.css` | `./dist/css/toc.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/tree.css` | `./dist/css/tree.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/state.css` | `./dist/css/state.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/generated.css` | `./dist/css/generated.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/workbench.css` | `./dist/css/workbench.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/command.css` | `./dist/css/command.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/analytical.css` | `./dist/css/analytical.css` | Opt-in CSS roll-up | Stable additive | Generated layered roll-up of the analytical leaves. Not included in the default bundle. |
+| `./css/unlayered/tokens.css` | `./css/tokens.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/fonts.css` | `./css/fonts.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/base.css` | `./css/base.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/motion.css` | `./css/motion.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/dots.css` | `./css/dots.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/navigation.css` | `./css/navigation.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/site.css` | `./css/site.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/content.css` | `./css/content.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/primitives.css` | `./css/primitives.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/forms.css` | `./css/forms.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/feedback.css` | `./css/feedback.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/overlay.css` | `./css/overlay.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/disclosure.css` | `./css/disclosure.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/table.css` | `./css/table.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./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/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/annotations.css` | `./css/annotations.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/legend.css` | `./css/legend.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/marks.css` | `./css/marks.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/connectors.css` | `./css/connectors.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/spotlight.css` | `./css/spotlight.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/crosshair.css` | `./css/crosshair.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/selection.css` | `./css/selection.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/sources.css` | `./css/sources.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/diff.css` | `./css/diff.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/code.css` | `./css/code.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/spark.css` | `./css/spark.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/sidenote.css` | `./css/sidenote.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/textref.css` | `./css/textref.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/bullet.css` | `./css/bullet.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/term.css` | `./css/term.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/toc.css` | `./css/toc.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/tree.css` | `./css/tree.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/state.css` | `./css/state.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/generated.css` | `./css/generated.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/workbench.css` | `./css/workbench.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/command.css` | `./css/command.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./tokens` | types: `./tokens/index.d.ts`<br>default: `./tokens/index.js` | Design tokens JS | Stable names/roles | ESM token registry and helpers. Token names and documented roles are public; exact values may tune before 1.0. |
+| `./vscode.css-custom-data.json` | `./classes/vscode.css-custom-data.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. |
+| `./tokens.json` | `./tokens/index.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. |
+| `./tokens.dtcg.json` | `./tokens/tokens.dtcg.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. |
+| `./tokens/resolved.json` | `./tokens/resolved.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. |
+| `./shiki/nothing.json` | `./shiki/nothing.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. |
+| `./llms.txt` | `./llms.txt` | Agent entrypoint | Stable path | Plain-text orientation file shipped for offline agents and tooling. |
+| `./docs/architecture.md` | `./docs/architecture.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/reference.md` | `./docs/reference.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/theming.md` | `./docs/theming.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/contrast.md` | `./docs/contrast.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/stability.md` | `./docs/stability.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/package-contract.md` | `./docs/package-contract.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/usage.md` | `./docs/usage.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/frontier-primitives.md` | `./docs/frontier-primitives.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/reporting.md` | `./docs/reporting.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/dots.md` | `./docs/dots.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/glyphs.md` | `./docs/glyphs.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/mermaid.md` | `./docs/mermaid.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/d2.md` | `./docs/d2.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/vega.md` | `./docs/vega.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/annotations.md` | `./docs/annotations.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./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/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. |
+| `./docs/sources.md` | `./docs/sources.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/diff.md` | `./docs/diff.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/code.md` | `./docs/code.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/spark.md` | `./docs/spark.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/sidenote.md` | `./docs/sidenote.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/textref.md` | `./docs/textref.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/bullet.md` | `./docs/bullet.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/term.md` | `./docs/term.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/toc.md` | `./docs/toc.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/tree.md` | `./docs/tree.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/state.md` | `./docs/state.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/generated.md` | `./docs/generated.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/workbench.md` | `./docs/workbench.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./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/adr/0001-color-system.md` | `./docs/adr/0001-color-system.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/adr/0002-scope-and-2026-baseline.md` | `./docs/adr/0002-scope-and-2026-baseline.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/adr/0003-theme-model.md` | `./docs/adr/0003-theme-model.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./classes` | types: `./classes/index.d.ts`<br>default: `./classes/index.js` | Class recipes JS | Stable | ESM class registry, recipes, attrs helpers, and cx joiner. The emitted class vocabulary is public. |
+| `./classes.json` | `./classes/classes.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. |
+| `./behaviors` | types: `./behaviors/index.d.ts`<br>default: `./behaviors/index.js` | Vanilla behavior JS | Stable | ESM, SSR-safe, cleanup-returning behavior initializers. Behavior internals are not public. |
+| `./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. |
+| `./react` | types: `./react/index.d.ts`<br>default: `./react/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
+| `./solid` | types: `./solid/index.d.ts`<br>default: `./solid/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
+| `./qwik` | types: `./qwik/index.d.ts`<br>default: `./qwik/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
+| `./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. |
+| `./mermaid` | types: `./tokens/mermaid.d.ts`<br>default: `./tokens/mermaid.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
+| `./mermaid.json` | `./tokens/mermaid.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. |
+| `./d2` | types: `./tokens/d2.d.ts`<br>default: `./tokens/d2.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
+| `./d2.json` | `./tokens/d2.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. |
+| `./vega` | types: `./tokens/vega.d.ts`<br>default: `./tokens/vega.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
+| `./vega.json` | `./tokens/vega.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. |
+| `./fonts/*` | `./fonts/*` | Vendored font asset glob | Stable path pattern | Doto font files and license. Font file names are shipped assets, not JS APIs. |
+
+## Shipped Files Allowlist
+
+`package.json` controls the npm tarball with this `files` list. npm also
+always includes `package.json`, `README.md`, `LICENSE`, and
+`CHANGELOG.md`; `check:pack` verifies no dev-only path leaks.
+
+| Path | Kind | Contract |
+| --- | --- | --- |
+| `css` | Source CSS directory | Public source leaves. Mostly hand-authored; generated exceptions are called out in the provenance table. |
+| `dist` | Generated CSS directory | Prebuilt layered bundle and leaves. Never hand-edit. |
+| `fonts` | Vendored assets | Doto woff2 files plus OFL license. |
+| `tokens` | Mixed source/generated data | Token source plus generated JSON, declarations, and renderer theme data. |
+| `classes` | Mixed source/generated data | Class recipe source plus generated JSON/declarations/custom-data. |
+| `behaviors` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `glyphs` | Authored public JS directory | Glyph registry/renderers shipped as JS; declarations are generated. |
+| `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. |
+| `react` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `solid` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `qwik` | 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. |
+| `MIGRATIONS.json` | Migration data | Shipped rename/migration map for tooling. |
+| `docs/architecture.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/reference.md` | Generated documentation | Committed generated doc; never hand-edit. |
+| `docs/theming.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/contrast.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/stability.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/package-contract.md` | Generated documentation | Committed generated doc; never hand-edit. |
+| `docs/usage.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/frontier-primitives.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/reporting.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/dots.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/glyphs.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/mermaid.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/d2.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/vega.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/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/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. |
+| `docs/sources.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/diff.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/code.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/spark.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/sidenote.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/textref.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/bullet.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/term.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/toc.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/tree.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/state.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/generated.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/workbench.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/command.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/adr/0001-color-system.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/adr/0002-scope-and-2026-baseline.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/adr/0003-theme-model.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+
+## Artifact Provenance
+
+Generated files are committed so the package can publish without a consumer-side
+build step. Edit the source of truth, run the listed generator, and commit the
+result. The listed gates are part of `npm run check`.
+
+| Surface | Source of truth | Generated outputs | Generator | Gate | Note |
+| --- | --- | --- | --- | --- | --- |
+| Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh | The complete export/file matrix in this document is generated from the manifest. |
+| Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved 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 (40 layered outputs) | `npm run dist:build` | check:dist; check:exports | Default bundle and direct layered leaf imports are generated from authored CSS and size-gated. |
+| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:attw; check:publint | Declarations are emitted from the shipped JS, not separately maintained. |
+| Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; npm test | 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. |
+| External renderer themes | `tokens/mermaid.js; tokens/d2.js; tokens/vega.js` | tokens/{mermaid,d2,vega}.{js,json,d.ts} | `npm run mermaid:build; d2:build; vega:build` | check:mermaid; check:d2; check:vega | Renderer configs use resolved colors because the external renderers cannot consume CSS variables directly. |
+| Contrast report | `tokens/resolved.json; tokens/skins.js; tokens/charts.js` | docs/contrast.md | `npm run contrast:build` | check:contrast | WCAG floors are hard-gated; APCA is reported as advisory. |
+
+## Internal Paths
+
+These paths are intentionally not part of the npm runtime surface:
+`scripts/`, `demo/`, `test/`, `examples/`, `.github/`, local config
+files, visual baselines, and development-only audit artifacts. They may change
+without a package-level compatibility promise.