@ponchia/ui 0.4.1 → 0.5.0

package/dist/css/report.css

@@ -1 +1 @@
-@layer bronto{.ui-report{--report-gap: var(--space-lg);--report-measure: 74ch;--report-page-margin: 18mm;color: var(--text-soft);display: grid;gap: var(--report-gap);inline-size: min(100%,var(--report-width,72rem));margin-inline: auto;padding: var(--report-padding-block,var(--space-2xl)) var(--space-md)}.ui-report--compact{--report-gap: var(--space-md);--report-padding-block: var(--space-xl)}.ui-report--numbered{counter-reset: report-section}.ui-report__cover{align-content: end;border-block-end: 1px solid var(--line);display: grid;gap: var(--space-md);min-block-size: min(62vh,34rem);padding-block-end: var(--space-xl)}.ui-report__cover--compact{min-block-size: auto;padding-block: var(--space-xl) var(--space-lg)}.ui-report__header{align-items: end;border-block-end: 1px solid var(--line);display: flex;flex-wrap: wrap;gap: var(--space-md);justify-content: space-between;padding-block-end: var(--space-md)}.ui-report__title{color: var(--text);font-family: var(--display);font-size: calc(var(--text-xl) * 1.35);letter-spacing: 0;line-height: 1.05;margin: 0;max-inline-size: var(--report-measure);text-transform: uppercase;text-wrap: balance}.ui-report__subtitle{color: var(--text-dim);font-size: var(--text-lg);line-height: 1.5;margin: 0;max-inline-size: var(--report-measure)}.ui-report__meta{align-items: center;color: var(--text-dim);display: flex;flex-wrap: wrap;font-family: var(--mono);font-size: var(--text-2xs);gap: 0.55rem;letter-spacing: 0;list-style: none;margin: 0;padding: 0;text-transform: uppercase}.ui-report__meta > *{align-items: center;display: inline-flex;gap: 0.55rem}.ui-report__meta > :not(:last-child)::after{background: var(--line-strong);border-radius: 50%;block-size: 0.22rem;content: '';inline-size: 0.22rem}.ui-report__toc{border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-xs);padding: var(--space-md)}.ui-report__toc ol,.ui-report__toc ul{display: grid;gap: 0.35rem;margin: 0;padding-inline-start: var(--space-md)}.ui-report__toc a{color: var(--text);text-decoration: underline;text-decoration-color: color-mix(in srgb,var(--accent) 45%,transparent);text-underline-offset: 0.2rem}.ui-report__summary,.ui-report__finding,.ui-report__evidence{background: var(--panel);border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-sm);padding: var(--space-md)}.ui-report__summary{border-inline-start: 2px solid var(--accent)}.ui-report__finding{border-inline-start: 2px solid var(--line-strong)}.ui-report__evidence{background: var(--panel-soft)}.ui-report__evidence:has(> .ui-table-wrap:only-child){padding: 0}.ui-report__evidence:has(> .ui-table-wrap:only-child) > .ui-table-wrap{border: 0;border-radius: var(--radius-md)}.ui-report__section{display: grid;gap: var(--space-md);scroll-margin-block-start: 6rem}.ui-report__section + .ui-report__section{border-block-start: 1px solid var(--line);padding-block-start: var(--space-xl)}.ui-report__section-head{color: var(--text);font-family: var(--display);font-size: var(--text-xl);letter-spacing: 0;line-height: 1.1;margin: 0;text-transform: uppercase;text-wrap: balance}.ui-report--numbered .ui-report__section-head::before{color: var(--accent-text);content: counter(report-section,decimal-leading-zero) ' / ';counter-increment: report-section}.ui-report--numbered .ui-report__section--unnumbered > .ui-report__section-head::before{content: none;counter-increment: none}.ui-report__figure{display: grid;gap: var(--space-sm);margin: 0}.ui-report__caption,.ui-chart__caption{color: var(--text-dim);font-family: var(--mono);font-size: var(--text-2xs);letter-spacing: 0;line-height: 1.5;text-transform: uppercase}.ui-report__sources,.ui-report__appendix,.ui-report__footnotes{border-block-start: 1px solid var(--line);color: var(--text-dim);display: grid;font-size: var(--text-sm);gap: var(--space-sm);padding-block-start: var(--space-md)}.ui-chart{border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-sm);padding: var(--space-md)}.ui-chart__legend{display: flex;flex-wrap: wrap;gap: var(--space-xs);list-style: none;margin: 0;padding: 0}.ui-chart__legend > *{align-items: center;color: var(--text-soft);display: inline-flex;font-family: var(--mono);font-size: var(--text-xs);gap: 0.45rem}.ui-chart__swatch{background: var(--chart-color,var(--chart-1,var(--accent)));background-image: var(--chart-pattern,var(--chart-pattern-1,none));background-size: var(--chart-pattern-size,8px);border: 1px solid var(--line-strong);block-size: 0.8rem;flex: 0 0 auto;inline-size: 0.8rem}.ui-chart__plot{display: grid;gap: var(--space-xs)}.ui-chart__bar{--chart-value: 0%;display: grid;gap: 0.35rem}.ui-chart__label{align-items: center;color: var(--text-soft);display: flex;font-family: var(--mono);font-size: var(--text-xs);gap: var(--space-sm);justify-content: space-between}.ui-chart__track{background: var(--panel-soft);border: 1px solid var(--line);block-size: 0.8rem;min-inline-size: 0}.ui-chart__fill{background: var(--chart-color,var(--chart-1,var(--accent)));background-image: var(--chart-pattern,var(--chart-pattern-1,none));background-size: var(--chart-pattern-size,8px);block-size: 100%;inline-size: clamp(0%,var(--chart-value),100%)}.ui-chart__fallback{margin-block-start: var(--space-sm)}.ui-print-only{display: none !important}.ui-print-exact{-webkit-print-color-adjust: exact;print-color-adjust: exact}@media print{@page{margin: var(--report-page-margin)}.ui-report{--report-padding-block: 0;color-scheme: light;--text: #111;--text-soft: #2a2a2a;--text-dim: #555;--panel: #fff;--panel-soft: #f7f7f7;--line: #d9d9d9;--line-strong: #b3b3b3;inline-size: auto;padding: 0}.ui-chart__fill,.ui-chart__swatch{-webkit-print-color-adjust: exact;print-color-adjust: exact}.ui-report__cover{min-block-size: auto}.ui-report__cover,.ui-report__header,.ui-report__section,.ui-report__summary,.ui-report__finding,.ui-report__evidence,.ui-report__figure,.ui-chart{break-inside: avoid}.ui-report__section-head{break-after: avoid}.ui-print-only{display: var(--print-display,block) !important}.ui-screen-only{display: none !important}.ui-break-before{break-before: page}.ui-break-after{break-after: page}.ui-keep{break-inside: avoid}}}
+@layer bronto{.ui-report{--report-gap: var(--space-lg);--report-measure: 74ch;--report-page-margin: 18mm;color: var(--text-soft);display: grid;gap: var(--report-gap);inline-size: min(100%,var(--report-width,72rem));margin-inline: auto;padding: var(--report-padding-block,var(--space-2xl)) var(--space-md)}.ui-report--compact{--report-gap: var(--space-md);--report-padding-block: var(--space-xl)}.ui-report--numbered{counter-reset: report-section}.ui-report__cover{align-content: end;border-block-end: 1px solid var(--line);display: grid;gap: var(--space-md);min-block-size: min(62vh,34rem);padding-block-end: var(--space-xl)}.ui-report__cover--compact{min-block-size: auto;padding-block: var(--space-xl) var(--space-lg)}.ui-report__header{align-items: end;border-block-end: 1px solid var(--line);display: flex;flex-wrap: wrap;gap: var(--space-md);justify-content: space-between;padding-block-end: var(--space-md)}.ui-report__title{color: var(--text);font-family: var(--display);font-size: calc(var(--text-xl) * 1.35);letter-spacing: 0;line-height: 1.05;margin: 0;max-inline-size: var(--report-measure);text-transform: uppercase;text-wrap: balance}.ui-report__subtitle{color: var(--text-dim);font-size: var(--text-lg);line-height: 1.5;margin: 0;max-inline-size: var(--report-measure)}.ui-report__meta{align-items: center;color: var(--text-dim);display: flex;flex-wrap: wrap;font-family: var(--mono);font-size: var(--text-2xs);gap: 0.55rem;letter-spacing: 0;list-style: none;margin: 0;padding: 0;text-transform: uppercase}.ui-report__meta > *{align-items: center;display: inline-flex;gap: 0.55rem}.ui-report__meta > :not(:last-child)::after{background: var(--line-strong);border-radius: 50%;block-size: 0.22rem;content: '';inline-size: 0.22rem}.ui-report__toc{border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-xs);padding: var(--space-md)}.ui-report__toc ol,.ui-report__toc ul{display: grid;gap: 0.35rem;margin: 0;padding-inline-start: var(--space-md)}.ui-report__toc a{color: var(--text);text-decoration: underline;text-decoration-color: color-mix(in srgb,var(--accent) 45%,transparent);text-underline-offset: 0.2rem}.ui-report__summary,.ui-report__finding,.ui-report__evidence{background: var(--panel);border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-sm);padding: var(--space-md)}.ui-report__summary{border-inline-start: 2px solid var(--accent)}.ui-report__finding{border-inline-start: 2px solid var(--line-strong)}.ui-report__evidence{background: var(--panel-soft)}.ui-report__evidence:has(> .ui-table-wrap:only-child){padding: 0}.ui-report__evidence:has(> .ui-table-wrap:only-child) > .ui-table-wrap{border: 0;border-radius: var(--radius-md)}.ui-report__section{display: grid;gap: var(--space-md);scroll-margin-block-start: 6rem}.ui-report__section + .ui-report__section{border-block-start: 1px solid var(--line);padding-block-start: var(--space-xl)}.ui-report__section-head{color: var(--text);font-family: var(--display);font-size: var(--text-xl);letter-spacing: 0;line-height: 1.1;margin: 0;text-transform: uppercase;text-wrap: balance}.ui-report--numbered .ui-report__section-head::before{color: var(--accent-text);content: counter(report-section,decimal-leading-zero) ' / ';counter-increment: report-section}.ui-report--numbered .ui-report__section--unnumbered > .ui-report__section-head::before{content: none;counter-increment: none}.ui-report__figure{display: grid;gap: var(--space-sm);margin: 0}.ui-report__caption,.ui-chart__caption{color: var(--text-dim);font-family: var(--mono);font-size: var(--text-2xs);letter-spacing: 0;line-height: 1.5;text-transform: uppercase}.ui-report__sources,.ui-report__appendix,.ui-report__footnotes{border-block-start: 1px solid var(--line);color: var(--text-dim);display: grid;font-size: var(--text-sm);gap: var(--space-sm);padding-block-start: var(--space-md)}.ui-chart{border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-sm);padding: var(--space-md)}.ui-chart__plot{display: grid;gap: var(--space-xs)}.ui-chart__bar{--chart-value: 0%;display: grid;gap: 0.35rem}.ui-chart__bar[hidden]{display: none}.ui-chart__label{align-items: center;color: var(--text-soft);display: flex;font-family: var(--mono);font-size: var(--text-xs);gap: var(--space-sm);justify-content: space-between}.ui-chart__track{background: var(--panel-soft);border: 1px solid var(--line);block-size: 0.8rem;min-inline-size: 0}.ui-chart__fill{background: var(--chart-color,var(--chart-1,var(--accent)));background-image: var(--chart-pattern,var(--chart-pattern-1,none));background-size: var(--chart-pattern-size,8px);block-size: 100%;inline-size: clamp(0%,var(--chart-value),100%)}.ui-chart__fallback{margin-block-start: var(--space-sm)}.ui-print-only{display: none !important}.ui-print-exact{-webkit-print-color-adjust: exact;print-color-adjust: exact}@media print{@page{margin: var(--report-page-margin)}.ui-report{--report-padding-block: 0;color-scheme: light;--text: #111;--text-soft: #2a2a2a;--text-dim: #555;--panel: #fff;--panel-soft: #f7f7f7;--line: #d9d9d9;--line-strong: #b3b3b3;inline-size: auto;padding: 0}.ui-chart__fill{-webkit-print-color-adjust: exact;print-color-adjust: exact}.ui-report__cover{min-block-size: auto}.ui-report__cover,.ui-report__header,.ui-report__section,.ui-report__summary,.ui-report__finding,.ui-report__evidence,.ui-report__figure,.ui-chart{break-inside: avoid}.ui-report__section-head{break-after: avoid}.ui-print-only{display: var(--print-display,block) !important}.ui-screen-only{display: none !important}.ui-break-before{break-before: page}.ui-break-after{break-after: page}.ui-keep{break-inside: avoid}}}

package/dist/css/selection.css

@@ -0,0 +1 @@
+@layer bronto{.ui-sel{transition: opacity 0.12s ease,outline-color 0.12s ease}@media (prefers-reduced-motion: reduce){.ui-sel{transition: none}}.ui-sel--on{outline: 2px solid var(--accent);outline-offset: 1px}.ui-sel--off{opacity: 0.35}.ui-sel--maybe{outline: 1px dashed var(--accent);outline-offset: 1px}@media (forced-colors: active){.ui-sel--on{outline-color: Highlight}}}

package/dist/css/sources.css

@@ -0,0 +1 @@
+@layer bronto{.ui-citation,.ui-source-card,.ui-provenance{--src-tone: var(--text-dim)}.ui-src--verified{--src-tone: var(--success)}.ui-src--reviewed{--src-tone: var(--accent)}.ui-src--generated{--src-tone: var(--info)}.ui-src--unverified{--src-tone: var(--text-dim)}.ui-src--stale{--src-tone: var(--warning)}.ui-src--conflict{--src-tone: var(--danger)}.ui-citation{color: var(--accent-text);font-family: var(--mono);font-size: 0.72em;font-weight: 600;text-decoration: none;vertical-align: super}.ui-citation:hover{text-decoration: underline}.ui-citation--chip{align-items: center;background: var(--panel-soft);border: 1px solid var(--line);border-radius: var(--radius-pill);color: var(--text-soft);display: inline-flex;font-size: var(--text-2xs);gap: 0.35rem;padding: 0.08rem 0.55rem;vertical-align: baseline}.ui-citation--chip::before{background: var(--src-tone);border-radius: 50%;block-size: 0.45rem;content: '';inline-size: 0.45rem;print-color-adjust: exact}.ui-source-list{display: grid;gap: var(--space-sm);list-style: none;margin: 0;padding: 0}.ui-source-list__item{margin: 0}.ui-source-card{background: var(--panel-soft);border: 1px solid var(--line);border-inline-start: 2px solid var(--src-tone);border-radius: var(--radius-md);display: grid;gap: 0.3rem;padding: 0.75rem 0.9rem;print-color-adjust: exact}.ui-source-card__title{color: var(--text);font-size: var(--text-sm);font-weight: 600;margin: 0}.ui-source-card__origin{color: var(--text-soft);font-family: var(--mono);font-size: var(--text-2xs);letter-spacing: var(--tracking-wide)}.ui-source-card__time{color: var(--text-dim);font-family: var(--mono);font-size: var(--text-2xs)}.ui-source-card__excerpt{color: var(--text-soft);margin: 0}.ui-source-card__actions{display: flex;flex-wrap: wrap;gap: 0.5rem;margin-block-start: 0.2rem}.ui-provenance{align-items: center;color: var(--text-dim);display: inline-flex;flex-wrap: wrap;font-family: var(--mono);font-size: var(--text-2xs);gap: 0.3rem 0.75rem;letter-spacing: var(--tracking-wide)}.ui-provenance__item{align-items: center;display: inline-flex;gap: 0.35rem}.ui-provenance__item::before{background: var(--src-tone);border-radius: 50%;block-size: 0.45rem;content: '';inline-size: 0.45rem;print-color-adjust: exact}@media (forced-colors: active){.ui-citation--chip::before,.ui-provenance__item::before{background: CanvasText}.ui-source-card{border-inline-start-color: CanvasText}}}

package/dist/css/spotlight.css

@@ -0,0 +1 @@
+@layer bronto{.ui-spotlight{--spot-x: 50%;--spot-y: 50%;--spot-w: 0px;--spot-h: 0px;--spot-pad: 8px;--spot-radius: var(--radius-md);--spot-backdrop: color-mix(in srgb,#000 55%,transparent);inset: 0;pointer-events: none;position: fixed;z-index: var(--z-overlay,1000)}.ui-spotlight__hole{background: transparent;block-size: calc(var(--spot-h) + var(--spot-pad) * 2);border-radius: var(--spot-radius);box-shadow: 0 0 0 100vmax var(--spot-backdrop);inline-size: calc(var(--spot-w) + var(--spot-pad) * 2);inset-block-start: 0;inset-inline-start: 0;position: absolute;transform: translate( calc(var(--spot-x) - var(--spot-pad)),calc(var(--spot-y) - var(--spot-pad)) );transition: transform 0.2s ease,inline-size 0.2s ease,block-size 0.2s ease}@media (prefers-reduced-motion: reduce){.ui-spotlight__hole{transition: none}}.ui-spotlight--ring .ui-spotlight__hole{outline: 2px solid var(--accent);outline-offset: 0}.ui-tour-note{background: var(--panel);border: 1px solid var(--line);border-radius: var(--radius-md);box-shadow: var(--shadow-raised);color: var(--text);display: grid;gap: var(--space-sm);max-inline-size: 22rem;padding: var(--space-md);pointer-events: auto}.ui-tour-note__step{color: var(--text-dim);font-family: var(--mono);font-size: var(--text-2xs);letter-spacing: 0;text-transform: uppercase}.ui-tour-note__title{color: var(--text);font-size: var(--text-lg);font-weight: 600;margin: 0}.ui-tour-note__body{color: var(--text-soft);margin: 0}.ui-tour-note__actions{display: flex;gap: var(--space-sm);justify-content: flex-end}@media (forced-colors: active){.ui-spotlight__hole{outline: 2px solid CanvasText}}}

package/dist/css/state.css

@@ -0,0 +1 @@
+@layer bronto{.ui-state{--state-tone: var(--text-dim);align-items: center;display: inline-flex;font-size: var(--text-sm);gap: 0.4rem}.ui-state::before{background: var(--state-tone);border-radius: 50%;block-size: 0.5rem;content: '';flex: none;inline-size: 0.5rem;print-color-adjust: exact}.ui-state__label{color: var(--text)}.ui-state__detail{color: var(--text-dim);font-size: var(--text-2xs)}.ui-state--busy::before{animation: uiStatePulse 1.1s ease-in-out infinite}@keyframes uiStatePulse{50%{opacity: 0.3}}@media (prefers-reduced-motion: reduce){.ui-state--busy::before{animation: none}}.ui-state--saving{--state-tone: var(--accent)}.ui-state--saved{--state-tone: var(--success)}.ui-state--queued{--state-tone: var(--text-dim)}.ui-state--offline{--state-tone: var(--warning)}.ui-state--stale{--state-tone: var(--warning)}.ui-state--conflict{--state-tone: var(--danger)}.ui-state--error{--state-tone: var(--danger)}.ui-state--locked{--state-tone: var(--text-dim)}.ui-state--reviewed{--state-tone: var(--success)}.ui-state--needs-review{--state-tone: var(--warning)}.ui-syncbar{align-items: center;border-block-end: 1px solid var(--line);display: flex;flex-wrap: wrap;gap: var(--space-sm) var(--space-md);justify-content: space-between;padding-block: var(--space-xs)}@media (forced-colors: active){.ui-state::before{background: CanvasText}}}

package/dist/css/workbench.css

@@ -0,0 +1 @@
+@layer bronto{.ui-inspector{background: var(--panel);border: 1px solid var(--line);border-radius: var(--radius-md);display: grid;gap: var(--space-sm);padding: var(--space-md)}.ui-inspector__header{align-items: baseline;border-block-end: 1px solid var(--line);display: flex;gap: var(--space-sm);justify-content: space-between;padding-block-end: var(--space-xs)}.ui-inspector__body{display: grid;gap: var(--space-2xs)}.ui-property{align-items: baseline;display: grid;gap: var(--space-sm);grid-template-columns: minmax(6rem,38%) 1fr}.ui-property__label{color: var(--text-dim);font-family: var(--mono);font-size: var(--text-2xs);letter-spacing: var(--tracking-wide);text-transform: uppercase}.ui-property__value{color: var(--text);font-size: var(--text-sm);min-inline-size: 0}.ui-selectionbar{align-items: center;background: var(--panel-strong);border: 1px solid var(--line-strong);border-radius: var(--radius-md);box-shadow: var(--shadow-raised);display: flex;flex-wrap: wrap;gap: var(--space-sm) var(--space-md);justify-content: space-between;padding: 0.5rem 0.85rem}.ui-selectionbar__count{color: var(--text);font-family: var(--mono);font-size: var(--text-sm)}.ui-selectionbar__actions{display: flex;flex-wrap: wrap;gap: var(--space-xs)}}

package/docs/adr/0003-theme-model.md

@@ -77,10 +77,13 @@ early-warning that the Lc 36 regression would have tripped.
 - Re-tuning dark token *values* changes the default rendered output in dark mode
   → the dark Playwright visual baselines must be regenerated in the pinned Linux
   container (`visual-baselines.yml`). Kept in 0.4.1 per the maintainer's call.
-- The dark palette is written in three places (the `@media` block, the
-  `[data-theme]` block, and the `cssVars.dark` JS mirror), guarded by
-  `check:tokens`. Any dark edit is a three-way edit; deduping by generating
-  `tokens.css` from the JS model is a tracked follow-up.
+- The dark palette was originally written in three places (the `@media` block,
+  the `[data-theme]` block, and the `cssVars.dark` JS mirror). **Resolved in
+  0.4.2:** `tokens/index.js` (`cssVars`) is now the single source, and the four
+  `:root` palette blocks of `css/tokens.css` are generated from it
+  (`scripts/gen-tokens-css.mjs`); the two dark blocks are identical by
+  construction, so a dark edit is a one-place edit, still guarded by
+  `check:tokens`.
 - `data-surface` joins `data-theme`/`data-bronto-skin`/`data-density`/
   `data-contrast` as a documented root-level attribute (theming.md). The kitchen
   sink ships a unified picker (theme × colorway × surface) so the full axis set

package/docs/annotations.md

@@ -0,0 +1,345 @@
+# SVG annotations
+
+`@ponchia/ui/css/annotations.css` is an opt-in SVG annotation layer for charts,
+reports, and analytical figures. It follows the same grammar as
+d3-annotation: a **subject** marks the thing being discussed, a **connector**
+points away from it, and a **note** carries the visible explanation.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/annotations.css';
+```
+
+Use it with any SVG renderer. Bronto supplies classes and tiny geometry helpers;
+it does not own chart scales, mutate the DOM, or provide draggable edit mode.
+
+```js
+import {
+  annotationParts,
+  annotationTransform,
+  axisThresholdPath,
+  bracketSubjectPath,
+  circleSubjectPath,
+  connectorLine,
+  evidenceMarkerPath,
+  notePlacement,
+  noteTransform,
+} from '@ponchia/ui/annotations';
+
+const transform = annotationTransform({ x: 180, y: 72 });
+const subject = circleSubjectPath({ radius: 18 });
+const connector = connectorLine({
+  dx: 88,
+  dy: -42,
+  subject: { type: 'circle', radius: 18, radiusPadding: 4 },
+});
+const parts = annotationParts({
+  x: 180,
+  y: 72,
+  dx: 88,
+  dy: -42,
+  subject: { type: 'circle', radius: 18, radiusPadding: 4 },
+});
+const note = notePlacement({
+  x: 180,
+  y: 72,
+  width: 96,
+  height: 44,
+  bounds: { x: 0, y: 0, width: 360, height: 180 },
+  preferred: 'right',
+});
+```
+
+## Markup model
+
+Author annotation groups at the subject anchor. Use `dx` / `dy` as the note
+offset, matching d3-annotation's mental model.
+
+```html
+<svg viewBox="0 0 360 180" role="img" aria-labelledby="chart-title chart-desc">
+  <title id="chart-title">Annotated delivery chart</title>
+  <desc id="chart-desc">A callout marks the delivery peak.</desc>
+
+  <g
+    class="ui-annotation ui-annotation--circle ui-annotation--accent"
+    transform="translate(180, 72)"
+  >
+    <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.424L88,-42" />
+    <g class="ui-annotation__note" transform="translate(88, -42)">
+      <path class="ui-annotation__note-line" d="M0,0H76" />
+      <text class="ui-annotation__title" y="-8">Peak</text>
+      <text class="ui-annotation__label" y="12">Delivery spike</text>
+    </g>
+  </g>
+</svg>
+```
+
+The visible note text should also be represented in the figure caption,
+`<desc>`, fallback table, or surrounding prose when the figure is complex.
+Use `aria-hidden="true"` only for decorative annotations.
+
+## Variants and motion
+
+Use one variant class per annotation group. Variants describe the visual
+grammar, not data semantics:
+
+| Variant | Use |
+| --- | --- |
+| `ui-annotation--label` | Direct label with no connector. |
+| `ui-annotation--callout` | Plain point-to-note callout. |
+| `ui-annotation--elbow` | Dogleg connector around dense marks. |
+| `ui-annotation--curve` | Softer connector for paths or flows. |
+| `ui-annotation--circle` | Circular subject around a point or local cluster. |
+| `ui-annotation--rect` | Rectangular subject around a bar, block, or region. |
+| `ui-annotation--threshold` | Horizontal or vertical limit rule. |
+| `ui-annotation--badge` | Compact numbered or categorical mark. |
+| `ui-annotation--bracket` | Range span on one axis. |
+| `ui-annotation--band` | Interval, confidence band, or risk window. |
+| `ui-annotation--slope` | Trend or slope segment. |
+| `ui-annotation--compare` | Before/after or A/B grouping. |
+| `ui-annotation--cluster` | Several nearby outliers. |
+| `ui-annotation--axis` | Axis milestone or reference tick. |
+| `ui-annotation--timeline` | Event pin on a timeline. |
+| `ui-annotation--evidence` | Proof, source, or evidence marker. |
+
+Tones are `accent`, `muted`, `success`, `warning`, `danger`, and `info`.
+Status tones (`success`, `warning`, `danger`, `info`) are only for annotations
+that carry that status meaning.
+
+Motion is opt-in and respects `prefers-reduced-motion`:
+
+| Motion class | Effect |
+| --- | --- |
+| `ui-annotation--draw` | Connectors draw in once; subjects reveal without losing dashed variant styling. |
+| `ui-annotation--reveal` | Note fades into place. |
+| `ui-annotation--pulse` | Subject or badge pulses gently. |
+| `ui-annotation--focus` | Static emphasis with a stronger subject stroke. |
+
+The class recipe mirrors this surface:
+
+```js
+ui.annotation({ variant: 'bracket', tone: 'info', motion: 'draw' });
+// "ui-annotation ui-annotation--bracket ui-annotation--info ui-annotation--draw"
+```
+
+## Geometry helpers
+
+The helper module returns SVG strings only. It does not know about scales,
+selections, DOM nodes, or frameworks.
+
+| Helper | Returns |
+| --- | --- |
+| `annotationTransform({ x, y })` | Group transform for the subject anchor. |
+| `noteTransform({ dx, dy, align, valign, width, height })` | Note transform from the subject anchor, with optional alignment. |
+| `notePlacement({ x, y, width, height, bounds, preferred })` | Bounded note offset, alignment and transform for one annotation. |
+| `declutterLabels(items, { gap, min, max })` | Adjusted centres for `items` (`[{ pos, size }]`) so labels don't overlap along one axis (order-preserving). |
+| `directLabels(items, { axis, cross, gap, min, max, shape })` | Decluttered label points **and** a leader path per item: `[{ x, y, anchor, key, d }]`. |
+| `circleSubjectPath({ radius })` | Circle subject path. |
+| `rectSubjectPath({ x, y, width, height, padding })` | Rect subject path. |
+| `thresholdPath({ x1, y1, x2, y2 })` | Arbitrary threshold/rule path. |
+| `axisThresholdPath({ orientation, value, start, end })` | Horizontal or vertical axis-aligned threshold. |
+| `bracketSubjectPath({ x1, y1, x2, y2, depth })` | Dogleg bracket path. |
+| `bandSubjectPath({ x, y, width, height, padding })` | Band or interval path. |
+| `slopeSubjectPath({ x1, y1, x2, y2 })` | Trend segment path. |
+| `comparisonBracePath({ x1, y1, x2, y2, depth })` | Comparison brace path. |
+| `outlierClusterPath({ points, radius })` | Repeated circle subjects for a cluster. |
+| `timelineEventPath({ size, direction })` | Event pin marker path. |
+| `evidenceMarkerPath({ x, y, width, height, padding })` | Centered square/rect evidence marker path. |
+| `connectorLine({ dx, dy, subject })` | Straight connector, trimmed against circle/rect subjects. |
+| `connectorElbow({ dx, dy, subject })` | D3-like dogleg connector. |
+| `connectorCurve({ dx, dy, subject })` | Deterministic cubic connector. |
+| `connectorEndDot({ x, y, radius })` | Dot marker path. |
+| `connectorEndArrow({ x1, y1, x2, y2, size })` | Arrow marker path. |
+| `annotationParts(options)` | Convenience object with `transform`, `subject`, `connector`, and `note`. |
+
+`declutterLabels` is a deliberately small, deterministic **1-D** declutter for
+direct labels or axis ticks — sort, push overlaps apart by `size + gap`, slide
+to fit under `max`. It is **not** a general 2-D collision solver: if more labels
+are requested than the axis can hold, the overflow is yours to resolve (fewer
+labels, a longer axis, or rotation). It returns numbers; you own the scale and
+the DOM.
+
+`directLabels` is the **direct-labeling** companion: it declutters labels along
+one axis _and_ draws the leader from each true anchor to its placed label,
+reusing the connector kernel. Each `items[i]` is `{ anchor: {x, y}, size, key? }`
+in figure coordinates; labels declutter along `axis` (`'y'` = a vertical column,
+the default) and sit at the fixed `cross` coordinate. It returns, in input
+order, the placed label point `{ x, y }`, the echoed `anchor`/`key`, and the
+leader path `d` (`shape`: `straight` · `elbow` · `curve`). Like everything here
+it owns no scales, no DOM, and no 2-D placement — map data → figure coordinates
+first, then drop each `d` into a `<path class="ui-annotation__connector">` and
+position the label at `{ x, y }`:
+
+```js
+import { directLabels } from '@ponchia/ui/annotations';
+
+// anchors are data points already projected into the figure's SVG coords
+const labels = directLabels(
+  points.map((p) => ({ anchor: p, size: 18, key: p.id })),
+  { axis: 'y', cross: width - 8, gap: 6, min: 12, max: height - 12 },
+);
+// labels[i] → { x, y, anchor, key, d }
+```
+
+All numeric inputs must be finite. Negative radius, width, height, padding, and
+marker size throw `RangeError`; non-finite values throw `TypeError`. Path
+numbers are rounded to three decimals with trailing zeros removed so snapshots
+and unit tests stay stable.
+
+`notePlacement()` is intentionally small: it places one note inside explicit SVG
+bounds using a preferred side (`right`, `left`, `top`, or `bottom`) and falls
+back to another side or a clamped note transform. It is not a collision solver
+for a whole chart. For dense annotation sets, pre-compute positions or author a
+mobile-specific SVG.
+
+## Density and responsive rules
+
+Annotations are strongest when they explain the few things a reader would miss.
+As a default, keep a single chart to three to five visible callouts. Use direct
+labels for stable context, one accent callout for the main insight, and status
+tones only for genuine status.
+
+Dense SVGs should not shrink until the notes become unreadable. Use one of
+these patterns:
+
+- Keep the chart wide in a horizontally scrollable figure and provide fallback
+  table text.
+- Author a simpler mobile SVG with fewer annotations.
+- Move low-priority annotation text into the caption or fallback table on small
+  screens.
+
+## Recipes
+
+### Label
+
+Use `ui-annotation--label` for direct labels when the subject is already clear.
+
+```html
+<g class="ui-annotation ui-annotation--label ui-annotation--muted" transform="translate(112, 48)">
+  <g class="ui-annotation__note">
+    <text class="ui-annotation__title">Baseline</text>
+    <text class="ui-annotation__label" y="16">Previous quarter</text>
+  </g>
+</g>
+```
+
+### Circle callout
+
+Use a circle subject when the referenced point or local cluster matters.
+
+```html
+<g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(180, 72)">
+  <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.424L88,-42" />
+  <g class="ui-annotation__note" transform="translate(88, -42)">
+    <path class="ui-annotation__note-line" d="M0,0H84" />
+    <text class="ui-annotation__title" y="-8">Spike</text>
+    <text class="ui-annotation__label" y="12">Investigate change</text>
+  </g>
+</g>
+```
+
+### Rect callout
+
+Use a rect subject for a band, bar, table region, or evidence block inside an
+SVG figure.
+
+```html
+<g class="ui-annotation ui-annotation--rect ui-annotation--warning" transform="translate(206, 92)">
+  <path class="ui-annotation__subject" d="M-34,-16H34V16H-34Z" />
+  <path class="ui-annotation__connector" d="M34,-16L72,-46" />
+  <g class="ui-annotation__note" transform="translate(72, -46)">
+    <path class="ui-annotation__note-line" d="M0,0H96" />
+    <text class="ui-annotation__title" y="-8">Watch</text>
+    <text class="ui-annotation__label" y="12">Lower confidence</text>
+  </g>
+</g>
+```
+
+### Threshold
+
+Use `ui-annotation--threshold` when a horizontal or vertical rule is the
+subject.
+
+```html
+<g class="ui-annotation ui-annotation--threshold ui-annotation--danger" transform="translate(0, 96)">
+  <path class="ui-annotation__subject" d="M36,0L324,0" />
+  <path class="ui-annotation__connector" d="M240,0L282,-32" />
+  <g class="ui-annotation__note" transform="translate(282, -32)">
+    <text class="ui-annotation__title">Limit</text>
+    <text class="ui-annotation__label" y="16">Do not exceed</text>
+  </g>
+</g>
+```
+
+### Badge
+
+Use badges for compact numbered or categorical markers. Do not rely on the badge
+color alone; pair it with visible text, a caption, or a table row.
+
+```html
+<g class="ui-annotation ui-annotation--badge ui-annotation--info" transform="translate(72, 84)">
+  <circle class="ui-annotation__badge" r="12" />
+  <text class="ui-annotation__title" text-anchor="middle" dominant-baseline="central">1</text>
+</g>
+```
+
+## Chart figure recipe
+
+Inside a report, keep the existing chart structure: caption, legend or direct
+labels, annotated SVG, and fallback data. A useful annotated figure should show
+more than one annotation family when the story needs it: direct labels for
+stable references, threshold annotations for limits, circle/rect subjects for
+specific data, and badge markers for compact index points.
+
+```html
+<figure class="ui-report__figure ui-chart ui-print-exact" role="group" aria-labelledby="annotated-chart">
+  <figcaption id="annotated-chart" class="ui-chart__caption">
+    Fig 2 - Weekly throughput, annotated at the peak
+  </figcaption>
+  <svg viewBox="0 0 360 160" role="img" aria-labelledby="throughput-title throughput-desc">
+    <title id="throughput-title">Weekly throughput with a peak callout</title>
+    <desc id="throughput-desc">Annotations mark the baseline, limit and highest research week.</desc>
+    <line x1="36" y1="112" x2="324" y2="112" stroke="var(--line)" />
+    <rect x="88" y="42" width="72" height="70" fill="var(--chart-1)" />
+    <rect x="188" y="70" width="72" height="42" fill="var(--chart-2)" />
+    <g class="ui-annotation ui-annotation--label ui-annotation--muted" transform="translate(36, 132)">
+      <g class="ui-annotation__note">
+        <text class="ui-annotation__title">Baseline</text>
+        <text class="ui-annotation__label" y="16">Previous quarter</text>
+      </g>
+    </g>
+    <g class="ui-annotation ui-annotation--threshold ui-annotation--danger" transform="translate(0, 66)">
+      <path class="ui-annotation__subject" d="M36,0L324,0" />
+      <path class="ui-annotation__connector" d="M272,0L304,-28" />
+      <g class="ui-annotation__note" transform="translate(234, -52)">
+        <text class="ui-annotation__title">Limit</text>
+        <text class="ui-annotation__label" y="16">Watch capacity</text>
+      </g>
+    </g>
+    <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(124, 42)">
+      <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="M16,-8L76,-36" />
+      <g class="ui-annotation__note" transform="translate(76, -36)">
+        <path class="ui-annotation__note-line" d="M0,0H80" />
+        <text class="ui-annotation__title" y="-8">Peak</text>
+        <text class="ui-annotation__label" y="12">Research high</text>
+      </g>
+    </g>
+  </svg>
+  <div class="ui-chart__fallback">
+    <div class="ui-table-wrap">
+      <table class="ui-table ui-table--dense">
+        <caption>Annotated chart source data</caption>
+        <thead><tr><th>Week</th><th class="is-num">Hours</th></tr></thead>
+        <tbody><tr><td>Week 4</td><td class="is-num">18</td></tr></tbody>
+      </table>
+    </div>
+  </div>
+</figure>
+```
+
+Status tones (`success`, `warning`, `danger`, `info`) are only for annotations
+that carry that status meaning. Use `accent` for the primary insight and
+`muted` for secondary callouts.

package/docs/architecture.md

@@ -0,0 +1,202 @@
+# Architecture & Decisions
+
+Status: accepted · 2026-05-15 · applies from v0.2.0
+
+> **Separate ADRs.** Larger, self-contained decisions live under
+> [`docs/adr/`](./adr/):
+>
+> - [ADR-0001 — Color system: governed evolution beyond monochrome](./adr/0001-color-system.md)
+>   (accepted; steps 1–8 implemented in 0.4.0) — the five-tier color
+>   constitution, the `check:color-policy`/`check:skins`/`check:charts`
+>   gates, opt-in colorways, data-viz, APCA advisory reporting, and the
+>   OKLCH core accent ramp.
+
+## Context
+
+`@ponchia/ui` is the shared design layer for several projects on
+different stacks: Astro, SvelteKit, and an
+open-ended set of future apps (React, Solid, Qwik, plain HTML, server-rendered
+templates). The question driving this document: is plain CSS the right
+universal substrate, or should the framework ship per-framework components?
+
+## Decision
+
+**Plain, class-based CSS is the canonical and only universal layer.** It is
+the single artifact every target consumes natively with zero adapter. A
+per-framework component library would make every non-chosen framework a
+second-class citizen and multiply the maintenance surface for the same button.
+
+The known gaps of a pure-CSS framework — contract visibility, a home for
+unavoidable JS, and distribution — are addressed as **thin, optional layers
+on top of the CSS, none of which require a framework commitment**:
+
+```
+@ponchia/ui
+├── css/         canonical universal layer (the framework)          [required]
+├── tokens/      design tokens as JS/JSON, for JS/canvas/tooling     [optional]
+├── classes/     typed class-name contract + recipe builders         [optional]
+├── behaviors/   vanilla, SSR-safe JS for stateful widgets           [optional]
+├── connectors/  pure SVG leader-line geometry kernel (no DOM)        [optional]
+├── annotations/ pure SVG callout geometry (builds on connectors)     [optional]
+├── glyphs/      dot-matrix glyph registry/renderers                 [optional]
+├── react/       thin React hooks over behaviors                     [optional peer]
+├── solid/       thin Solid primitives over behaviors                [optional peer]
+└── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+```
+
+### Consequences of each layer
+
+- **css/** — wrapped in a single `@layer bronto`. Any un-layered CSS in a
+  consumer wins the cascade without specificity wars or `!important`. This is
+  a deliberate behavioural change vs. unlayered v0.1.0; consumers pin a tag
+  so it ships only on the next version bump.
+- **Fonts** — `@font-face` moved out of `tokens.css` into `css/fonts.css`
+  with URLs relative to the package (`../fonts/*`), so font hosting is
+  decoupled from the token layer and resolves through bundlers or static
+  serving without an absolute `/fonts` assumption.
+- **tokens/** — `index.js` (`cssVars`) is the single source of truth for token
+  values. The four `:root` palette blocks of `css/tokens.css` are **generated**
+  from it (`scripts/gen-tokens-css.mjs`), as are the JSON artifacts (`index.json`,
+  `tokens.dtcg.json`, `resolved.json`). So the dark palette is authored once,
+  not in three places (the two CSS dark blocks are now identical by
+  construction), resolving the duplication ADR-0003 flagged. The CSS-only
+  presets (density / contrast / OLED) stay hand-authored below a marker and are
+  preserved across regeneration. `scripts/check-tokens.mjs` fails CI if
+  `css/tokens.css` drifts from the model.
+- **classes/** — `cls` is the flat registry; recipes only emit from it;
+  `scripts/check-classes.mjs` enforces a bidirectional match with the
+  stylesheet's `.ui-*` selectors. The class contract cannot silently rot.
+- **behaviors/** — vanilla, dependency-free, side-effect-free on import,
+  SSR-safe. Chosen over Web Components (SSR/hydration friction with Astro
+  islands and SvelteKit) and over per-framework packages (maintenance
+  multiplier). Revisit Web Components only if stateful widgets accumulate.
+  `index.js` is a barrel; each behavior lives in its own module
+  (`dialog.js`, `combobox.js`, …) over a shared `internal.js` of DOM helpers,
+  so the public import surface is unchanged.
+- **glyphs/** — static bitmap data and SSR-safe render helpers. The
+  256-cell DOM renderers are for display and solid inline icons; the `.ui-icon`
+  mask renderer is for dense icon-at-scale use.
+- **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
+  They do not define markup, own state, or fork behavior logic; they only run
+  the vanilla initializers on mount and cleanup on unmount/dispose.
+
+## Drift control
+
+Every data mirror is backed by a check wired into `npm run check`, run by CI
+on every push/PR and again by `release.yml` before publish (see "Release
+gating" below), so a version that fails any invariant never reaches npm.
+
+| Invariant                                       | Enforced by         |
+| ----------------------------------------------- | ------------------- |
+| exports / import graph / `files` consistent     | `check-exports.mjs` |
+| `tokens.css` ⇄ `tokens/index.js` ⇄ `.json`      | `check-tokens.mjs`  |
+| `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
+| `classes`/`tokens` `.d.ts` ⇄ JS runtime (exact) | `check-dts.mjs`     |
+| `annotations`/`connectors` hand-written `.d.ts` ⇄ exports | `check-helpers-dts.mjs` |
+| legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
+| `tokens.dtcg.json` ⇄ token model                | `check-dtcg.mjs`    |
+| color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
+| `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
+| every shipped colorway accent meets its WCAG floor | `check-contrast.mjs` |
+| `dataviz.css`/`charts.json`/`charts.d.ts` ⇄ `tokens/charts.js` · CVD-distinguishable · opt-in | `check-charts.mjs` |
+| `shiki/nothing.json` valid + on rationed palette | `check-shiki.mjs`  |
+| `dist/*.css` == fresh build of `css/` + budget  | `check-dist.mjs`    |
+| published tarball == intended `files` only      | `check-pack.mjs`    |
+| published `.d.ts` compile + reject typos        | `tsc` (`check:types`) |
+| CSS style/correctness                           | Stylelint           |
+| non-CSS source style                            | Prettier (`check:format`) |
+
+`check-dist` is the most supply-chain-critical row: `dist/bronto.css` is
+the default `exports["."]` consumers actually load, so its byte-equality
+to a fresh build of `css/` is what makes the committed bundle trustworthy.
+The `check-dist` size ceiling (`BUDGET` in `build-dist.mjs`) is calibrated
+to the current bundle with deliberate headroom — it is the consumer-facing
+payload contract, raised only intentionally with a CHANGELOG note.
+`check:types` compiles the published declarations against
+`test/types.test-d.ts`, whose `@ts-expect-error`s would fail to compile
+if the generated literal `cls`/token types stopped rejecting typos —
+so the *value* of the generated `.d.ts` is itself gated, not just their
+freshness (`check-dts`).
+
+## Release gating
+
+`release.yml` (on a pushed `v*` tag) is a five-job DAG, serialized by a
+`concurrency: release-publish` group so two tags can't race the dist-tag
+pointer:
+
+- `validate` — read-only: `npm run check` + tag↔version match. `check`
+  includes `check:release`; for a prerelease tag the base version's
+  CHANGELOG section need only exist (`## Unreleased — x.y.z` is fine) —
+  only a stable release must carry a dated heading.
+- `e2e` — Playwright (visual + axe a11y, both themes, cross-engine) in
+  the pinned `mcr.microsoft.com/playwright` container.
+- `examples` — `needs: validate`: builds the downstream example
+  apps against the **packed tarball**, mirroring CI. Catches a broken
+  published surface (exports map / missing file / unresolved subpath)
+  that `check:pack`'s file-allowlist inspection cannot — so the release
+  path runs the same consumer smoke as merge-to-main.
+- `publish-npm` — `needs: [validate, e2e, examples]`: `npm publish` with
+  provenance. Runs in the `npm-publish` **Environment** (required-reviewer
+  protection), so after the gates pass the run pauses for a manual approval
+  in the Actions UI before anything reaches npm — a guard against an
+  accidental tag push publishing. Dist-tag is derived from the tag: stable
+  (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any hyphenated
+  identifier) → `next`, so the default `npm i @ponchia/ui` never moves onto
+  an unstable build (opt in with `@ponchia/ui@next`).
+- `release-notes` — `needs: publish-npm`: a GitHub Release for visibility
+  (transitively gated on a successful publish, hence on the gates above);
+  prerelease tags are flagged so they aren't surfaced as "Latest". The Release
+  **body is the curated `CHANGELOG.md` section** for the tag
+  (`scripts/changelog-section.mjs`), not GitHub's auto-generated PR list — one
+  source of truth, surfaced where readers look.
+
+Because the documented install path is the npm package, **the npm publish
+is a real gate**: if `validate`, `e2e`, *or* `examples` fails,
+`publish-npm` never runs, the version never reaches the registry, and
+consumers never resolve it.
+(Corollary: a flaky `e2e` blocks releases — that is deliberate; fix the
+flake, don't bypass the gate.) Permissions are least-privilege per job
+(only `release-notes` gets `contents: write`; only `publish-npm` gets
+`id-token: write` for provenance).
+
+GitHub still serves the raw tag tarball `archive/refs/tags/vX.Y.Z.tar.gz`
+for any tag, ungated — that path is legacy/fallback, deliberately *not* the
+documented install, so it is no longer the safeguard-critical surface.
+Process still applies: bump `package.json`, land on `main`, go green, tag.
+
+## Decision — distribution: npm public `@ponchia/ui`
+
+Decided 2026-05-15. The framework is consumed by a growing set of
+heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, vanilla),
+several deploying via third-party CI. The only option where onboarding a new
+frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
+public**, and it uniquely also closes the release-gating gap (publish *is*
+the gate). GitHub Packages was rejected: it requires auth to install even
+public packages, i.e. an `.npmrc` + token on every frontend and CI runner —
+the exact friction to avoid. The raw tag tarball is kept as an ungated
+legacy/fallback only.
+
+The npm scope `@bronto` is not ownable, so the package name is
+**`@ponchia/ui`**. Naming layers, intentionally distinct:
+
+- **npm package**: `@ponchia/ui` (registry identity).
+- **CSS cascade layer**: `@layer bronto` and `data-bronto-*` behavior
+  attributes (the design-system namespace — unchanged; renaming gains
+  nothing and risks consumer overrides).
+- **Workspace / brand**: "Bronto" (repo `Ponchia/bronto-ui`) — unchanged.
+
+This split is deliberate; the README states it so the apparent mismatch is
+explained, not surprising.
+
+### Post-publish checklist
+
+- Confirm npm `latest` points at the tagged version and the package page shows
+  provenance.
+- Run `npm pack --dry-run --json` locally or from CI logs and confirm the
+  intended file count/payload.
+- Build the packed examples matrix (vanilla, Astro, SvelteKit, React, Solid, Qwik)
+  from the tarball, not a workspace link.
+- Confirm the GitHub Release body matches the curated changelog section.
+- If a bad package is published, deprecate that exact version on npm, publish a
+  patched version, and link the deprecation note to the changelog/security
+  advisory as appropriate.