@ponchia/ui 0.4.0 → 0.5.0

package/README.md

@@ -3,12 +3,12 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~73kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~76kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first, framework-agnostic UI framework built on token-driven restraint — monochrome by default, one rationed accent, dot-matrix display type, hairline borders. Color is _tiered_: we don't decorate with it, we signal with it. The "Nothing"-inspired look is the default skin, not the architecture — opt-in colorways (amber CRT · phosphor green · e-ink), a dot-matrix icon set, and a colourblind-safe data-viz palette prove the one knob is real. Zero runtime dependencies; re-brand the whole thing with one CSS variable.**
+**A CSS-first design system for interfaces that explain themselves.** Works in plain HTML, every modern framework, and print/PDF — there's no component runtime to adopt. The look is a deliberate stance: a neutral monochrome canvas with **one _rationed_ accent** (colour _signals_, it never decorates), dot-matrix display type and hairline borders, re-skinnable from a single `--accent` knob (opt-in amber-CRT · phosphor-green · e-ink colorways). And beyond the standard component set it ships an opt-in **analytical & report layer** — SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text marks, a colourblind-safe data-viz palette and a static/PDF report grammar — for dashboards and LLM-authored reports. Zero runtime dependencies; re-brand the whole thing with one CSS variable.
 
 ### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
@@ -20,6 +20,8 @@ The demo is the kitchen sink — every component, light/dark, RTL, live theming.
 
 `@ponchia/ui` ships its design as **CSS**, not components. You drop in one stylesheet and style with semantic `ui-*` classes; an optional thin layer of typed class-name recipes and SSR-safe vanilla behaviors sits on top for the few things that genuinely need JS (theme persistence, dialogs, toasts, disclosure). The guiding principle is **color is rationed, structure carries meaning** — layout, type weight and the hairline do the work before a hue does, and the accent is a spotlight, not a paint bucket. Because everything lives in a single `@layer bronto`, your own un-layered CSS overrides the framework with no specificity fight and no `!important`.
 
+It ships a complete, accessible **standard component set** — but that's not where it competes. Its differentiator is an opt-in **analytical & communication layer** for interfaces that make complex work legible: annotations, legends, connectors, marks, a guided-focus spotlight, lifecycle/system-state and source-provenance vocabularies, and a static/PDF report grammar. Each owns only its visual grammar and pure geometry — no chart engine, no state, no hit-testing. See **[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)** for the thesis.
+
 ## Install
 
 ```bash
@@ -34,7 +36,7 @@ Or drop it in with no build step, straight from a CDN:
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~73 kB raw / ~13 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~76 kB raw / ~13 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -79,7 +81,7 @@ toast('Saved', { tone: 'success' });   // body-anchored stack, no markup needed
 
 Behaviors cover theme persistence, disclosure, dropdown menus, native-`<dialog>` modals/drawers, tabs, combobox, form validation, table sort, carousel and toasts — wired by `data-bronto-*` attributes.
 
-**5. (Optional) display glyphs — a 43-glyph dot-matrix icon set:**
+**5. (Optional) display glyphs — a 48-glyph dot-matrix icon set:**
 
 ```js
 import { renderGlyph } from '@ponchia/ui/glyphs';
@@ -89,7 +91,7 @@ el.innerHTML = renderGlyph('search', { label: 'Search' });  // role="img"
 // import { initDotGlyph } from '@ponchia/ui/behaviors'; initDotGlyph();
 ```
 
-Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lock, home/user/heart/star/spark — rendered on the same `.ui-dotmatrix` primitive and re-skinned by the `--field-dot*` tokens (no SVG, no font). Default dot look is for **display** sizes; pass **`{ solid: true }`** to fuse the cells into a crisp pixel glyph that works as an **inline icon down to ~16px**.
+Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lock, home/user/heart/star/spark and circle-family marks are rendered on the same `.ui-dotmatrix` primitive and re-skinned by the `--field-dot*` tokens. Default dot look is for **display** sizes; pass **`{ solid: true }`** to fuse the cells into a crisp pixel glyph that works as an **inline icon down to ~16px**. For dense lists/tables, `renderGlyph(name, { render: 'mask' })` emits one `.ui-icon` element backed by an internal CSS mask.
 
 ## What's in the box
 
@@ -100,8 +102,10 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
 - **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
+- **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, sections, findings, evidence, figures, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
-- **Glyphs** — `@ponchia/ui/glyphs`, a 43-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons), no SVG/font.
+- **Glyphs** — `@ponchia/ui/glyphs`, a 48-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
 - **Colorways** _(opt-in)_ — `data-bronto-skin="amber-crt | phosphor-green | e-ink"`: a root-level recolour of the one accent (OKLCH, per-theme, contrast-gated), never in the default bundle.
 - **Data-viz** _(opt-in)_ — a colourblind-safe chart palette (`--chart-*` + dot-matrix pattern fills, resolved hex in `charts.json`), gated under simulated protan/deutan/tritan vision. Charts only, never UI chrome.
 
@@ -116,7 +120,7 @@ Everything accent-colored derives from a single `--accent` variable via `color-m
 .promo  { --accent: #16a34a; }   /* …or just this section green */
 ```
 
-Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the "Nothing" look is the **default skin, not the architecture**.
+Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the default monochrome look is **one skin, not the architecture**.
 
 **One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
 
@@ -128,7 +132,7 @@ Not an afterthought — a gate. Every contractual token pairing has a declared W
 
 ## Works with anything
 
-The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React and Solid there are also **optional thin bindings** — `@ponchia/ui/react` and `@ponchia/ui/solid` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js` are optional peer deps, so the core stays zero-dependency.
+The CSS is the framework, so it works with React, Svelte/SvelteKit, Astro, Vue, Solid, Qwik or plain HTML — there's no component runtime to adopt. The optional `classes` and `behaviors` entrypoints pull in **no** UI framework and are SSR-safe. For React, Solid and Qwik there are also **optional thin bindings** — `@ponchia/ui/react`, `@ponchia/ui/solid` and `@ponchia/ui/qwik` wrap the behaviors as hooks (`useDialog`, `useToast`, …); `react`/`solid-js`/`@builder.io/qwik` are optional peer deps, so the core stays zero-dependency.
 
 Per-framework getting-started guides + runnable example apps live in the repo:
 
@@ -137,41 +141,47 @@ Per-framework getting-started guides + runnable example apps live in the repo:
 | Vanilla / Vite / plain HTML | [vanilla.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/vanilla.md) | [`examples/vanilla-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/vanilla-vite) |
 | Astro | [astro.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/astro.md) | [`examples/astro`](https://github.com/Ponchia/bronto-ui/tree/main/examples/astro) |
 | SvelteKit | [sveltekit.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/sveltekit.md) | [`examples/sveltekit`](https://github.com/Ponchia/bronto-ui/tree/main/examples/sveltekit) |
-| React / Solid (snippet) | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | — |
+| React | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/react-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/react-vite) |
+| Solid | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/solid-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/solid-vite) |
+| Qwik | [react-solid.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/getting-started/react-solid.md) | [`examples/qwik-vite`](https://github.com/Ponchia/bronto-ui/tree/main/examples/qwik-vite) |
 | Tailwind / cascade-layer interop | [tailwind.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/interop/tailwind.md) | — |
 
 ## Extras
 
 - **Tokens as data** — `import tokens, { themeColor, cssVars } from '@ponchia/ui/tokens'` (plus `tokens.json`, W3C DTCG `tokens.dtcg.json`, and `tokens/resolved.json` — concrete hex per theme for canvas/SVG/MapLibre).
-- **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json'` (resolved hex per theme; series 1 = your accent) and the opt-in `@ponchia/ui/css/dataviz.css`.
+- **Chart colours for dashboards** — `import charts from '@ponchia/ui/charts.json' with { type: 'json' }` in Node ESM, or the same path through a bundler JSON import (resolved hex per theme; series 1 = your accent) plus the opt-in `@ponchia/ui/css/dataviz.css`.
+- **Static reports for LLMs** — add `@ponchia/ui/css/report.css` for report structure and print utilities; pair with `@ponchia/ui/css/dataviz.css` only when the report contains charts. Full cookbook: `docs/reporting.md`.
+- **Modern-platform motion** — overlays (modal/drawer/popover), toasts and the `<details>` accordion animate **in and out** with zero JS (`@starting-style` + `allow-discrete`, `::details-content` + `interpolate-size`). Progressive-enhancement extras: `.ui-scroll-progress` / `.ui-scroll-reveal` (scroll-driven, no JS) and `.ui-vt` for View Transitions. All degrade to a static end-state and respect `prefers-reduced-motion`. For smooth **cross-document** navigations, add the document-global one-liner to your own top-level (unlayered) CSS: `@view-transition { navigation: auto; }`.
 - **Editor IntelliSense** — point VS Code at the shipped custom-data file so every token autocompletes in `var(--…)`:
   ```json
   { "css.customData": ["node_modules/@ponchia/ui/classes/vscode.css-custom-data.json"] }
   ```
-- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/theming.md`, `docs/contrast.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
+- **For AI coding agents** — the package ships `llms.txt` at its root plus `docs/reference.md`, `docs/usage.md`, `docs/reporting.md`, `docs/theming.md`, `docs/contrast.md`, `docs/stability.md`, the color constitution `docs/adr/0001-color-system.md` and the `CHANGELOG` inside the tarball, so an offline agent has the full API and rationale without guessing.
 
-> The package root is **CSS-only**: `@import '@ponchia/ui'` in CSS, never `import '@ponchia/ui'` in JS. The JS entrypoints are the explicit subpaths `/tokens`, `/classes`, `/behaviors`, `/glyphs`.
+> The package root is **CSS-only**. Use `@import '@ponchia/ui'` in CSS, or `import '@ponchia/ui'` only as a CSS side-effect import in a CSS-aware bundler (Vite, Astro, SvelteKit, webpack). Do not import the package root from Node/runtime JS. JS entrypoints are explicit subpaths: `/tokens`, `/classes`, `/behaviors`, `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, and `/charts`.
+> JS subpaths are **ESM-only**. CommonJS consumers should use dynamic
+> `import('@ponchia/ui/behaviors')`.
 
 ## Browser support
 
-Evergreen only. The framework relies on cascade layers, `:has()`, `color-mix()`, CSS logical properties and native `<dialog>`. Floor: **Chrome/Edge 111+, Safari 16.4+, Firefox 121+** (early 2023 onward). No build-time fallback ships; pin an older tag if you need below this.
+Recent-evergreen, by design. The framework targets the modern web platform — cascade layers, `:has()`, `color-mix()`/`oklch()`, logical properties, native `<dialog>`, and the 2026 interaction primitives (`@starting-style`, `transition-behavior: allow-discrete`, `light-dark()`). Floor: **Chrome/Edge 125+, Safari 18+, Firefox 129+** (early–mid 2025). No fallback ships below this — pin an older tag if you need it. See [ADR-0002](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0002-scope-and-2026-baseline.md) for the scope/greenfield rationale.
 
 ## Versioning
 
-Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.4.0` (and equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
+Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.5.0` (and equivalently `^0.5.0`) resolves to `>=0.5.0 <0.6.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
 
-Contractual (changes are breaking): the `--accent` derivation and token **names**, the `.ui-*` class and recipe names, the `data-bronto-*` attributes, and each behavior's cleanup contract. Not contractual (may change any release): token **values** (visual tuning) and internal leaf-file / `@layer` boundaries.
+Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the full public-surface matrix.
 
 Release candidates publish to the `next` dist-tag, never to `latest` — opt in with `npm i @ponchia/ui@next` to try an upcoming version early. A plain `npm i @ponchia/ui` only ever resolves a stable release.
 
 ## Links
 
 - **[Live demo](https://ponchia.github.io/bronto-ui/)** · **[Theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)**
-- **[Class reference](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)** · **[Usage guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)** · **[Theming](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)** · **[Contrast](https://github.com/Ponchia/bronto-ui/blob/main/docs/contrast.md)** · **[Color system (ADR-0001)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**
+- **[Class reference](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)** · **[Usage guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)** · **[Theming](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)** · **[Contrast](https://github.com/Ponchia/bronto-ui/blob/main/docs/contrast.md)** · **[Color system (ADR-0001)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)** · **[Scope & 2026 baseline (ADR-0002)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0002-scope-and-2026-baseline.md)**
 - **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** · **[Roadmap](https://github.com/Ponchia/bronto-ui/blob/main/ROADMAP.md)** · **[Contributing](https://github.com/Ponchia/bronto-ui/blob/main/CONTRIBUTING.md)**
 
 ## License
 
 [MIT](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE) © Ponchia.
 
-The bundled **Doto** font (`fonts/*.ttf`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.
+The bundled **Doto** font (`fonts/*.woff2`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.

package/annotations/index.d.ts

@@ -0,0 +1,280 @@
+/** @ponchia/ui — SVG annotation geometry helpers. */
+
+export interface AnnotationPoint {
+  x: number;
+  y: number;
+}
+
+export interface AnnotationOffset {
+  dx: number;
+  dy: number;
+}
+
+export type AnnotationConnectorType = 'callout' | 'elbow' | 'curve';
+export type AnnotationAlign = 'start' | 'middle' | 'end';
+export type AnnotationValign = 'top' | 'middle' | 'bottom';
+export type AxisOrientation = 'horizontal' | 'vertical';
+export type TimelineDirection = 'up' | 'down' | 'left' | 'right';
+
+export interface CircleSubject {
+  type: 'circle';
+  radius: number;
+  radiusPadding?: number;
+}
+
+export interface RectSubject {
+  type: 'rect';
+  width: number;
+  height: number;
+  x?: number;
+  y?: number;
+  padding?: number;
+}
+
+export type ConnectorSubject = CircleSubject | RectSubject;
+
+export interface ConnectorOptions extends AnnotationOffset {
+  subject?: ConnectorSubject;
+}
+
+export interface CircleSubjectOptions {
+  radius: number;
+}
+
+export interface RectSubjectOptions {
+  width: number;
+  height: number;
+  x?: number;
+  y?: number;
+  padding?: number;
+}
+
+export interface ThresholdOptions {
+  x1?: number;
+  y1?: number;
+  x2: number;
+  y2: number;
+}
+
+export interface AxisThresholdOptions {
+  orientation?: AxisOrientation;
+  value?: number;
+  start?: number;
+  end: number;
+}
+
+export interface BracketSubjectOptions {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  depth?: number;
+}
+
+export interface BandSubjectOptions {
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+  padding?: number;
+}
+
+export interface SlopeSubjectOptions {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+export interface ComparisonBraceOptions {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  depth?: number;
+}
+
+export interface OutlierClusterOptions {
+  points: AnnotationPoint[];
+  radius?: number;
+}
+
+export interface TimelineEventOptions {
+  size?: number;
+  direction?: TimelineDirection;
+}
+
+export interface EvidenceMarkerOptions {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  padding?: number;
+}
+
+export interface ConnectorEndDotOptions extends AnnotationPoint {
+  radius?: number;
+}
+
+export interface ConnectorEndArrowOptions {
+  x1?: number;
+  y1?: number;
+  x2: number;
+  y2: number;
+  size?: number;
+}
+
+export interface NoteTransformOptions {
+  dx?: number;
+  dy?: number;
+  x?: number;
+  y?: number;
+  align?: AnnotationAlign;
+  valign?: AnnotationValign;
+  width?: number;
+  height?: number;
+}
+
+export interface AnnotationBounds {
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+}
+
+export interface NotePlacementOptions {
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+  bounds: AnnotationBounds;
+  padding?: number;
+  gap?: number;
+  preferred?: 'right' | 'left' | 'top' | 'bottom';
+}
+
+export interface NotePlacement {
+  dx: number;
+  dy: number;
+  align: AnnotationAlign;
+  valign: AnnotationValign;
+  transform: string;
+}
+
+export type AnnotationPartsSubject =
+  | CircleSubject
+  | RectSubject
+  | ({ type: 'threshold' } & ThresholdOptions)
+  | ({ type: 'bracket' } & BracketSubjectOptions)
+  | ({ type: 'band' } & BandSubjectOptions)
+  | ({ type: 'slope' } & SlopeSubjectOptions)
+  | ({ type: 'compare' } & ComparisonBraceOptions)
+  | ({ type: 'cluster' } & OutlierClusterOptions)
+  | ({ type: 'axis' } & AxisThresholdOptions)
+  | ({ type: 'timeline' } & TimelineEventOptions)
+  | ({ type: 'evidence' } & EvidenceMarkerOptions);
+
+export interface AnnotationPartsOptions {
+  type?: AnnotationConnectorType;
+  x?: number;
+  y?: number;
+  dx?: number;
+  dy?: number;
+  subject?: AnnotationPartsSubject;
+}
+
+export interface AnnotationParts {
+  transform: string;
+  subject: string;
+  connector: string;
+  note: string;
+}
+
+export declare function annotationTransform(point?: Partial<AnnotationPoint>): string;
+export declare function noteTransform(options?: NoteTransformOptions): string;
+export declare function notePlacement(options: NotePlacementOptions): NotePlacement;
+export declare function circleSubjectPath(options: CircleSubjectOptions): string;
+export declare function rectSubjectPath(options: RectSubjectOptions): string;
+export declare function thresholdPath(options: ThresholdOptions): string;
+export declare function axisThresholdPath(options: AxisThresholdOptions): string;
+export declare function bracketSubjectPath(options: BracketSubjectOptions): string;
+export declare function bandSubjectPath(options: BandSubjectOptions): string;
+export declare function slopeSubjectPath(options: SlopeSubjectOptions): string;
+export declare function comparisonBracePath(options: ComparisonBraceOptions): string;
+export declare function outlierClusterPath(options: OutlierClusterOptions): string;
+export declare function timelineEventPath(options?: TimelineEventOptions): string;
+export declare function evidenceMarkerPath(options?: EvidenceMarkerOptions): string;
+export declare function connectorEndDot(options: ConnectorEndDotOptions): string;
+export declare function connectorEndArrow(options: ConnectorEndArrowOptions): string;
+export declare function connectorLine(options: ConnectorOptions): string;
+export declare function connectorElbow(options: ConnectorOptions): string;
+export declare function connectorCurve(options: ConnectorOptions): string;
+export declare function annotationParts(options?: AnnotationPartsOptions): AnnotationParts;
+
+export interface DeclutterLabelItem {
+  /** Desired centre coordinate along the axis. */
+  pos: number;
+  /** The label's extent along the axis. */
+  size: number;
+}
+export interface DeclutterLabelsOptions {
+  /** Minimum gap kept between adjacent labels. Default 0. */
+  gap?: number;
+  /** Lower bound of the axis. Default -Infinity. */
+  min?: number;
+  /** Upper bound of the axis. Default Infinity. */
+  max?: number;
+}
+/**
+ * 1-D label declutter: nudge overlapping labels apart, order-preserving and
+ * deterministic. Returns the adjusted centre per input item (input order). Not
+ * a general 2-D collision solver.
+ */
+export declare function declutterLabels(
+  items: DeclutterLabelItem[],
+  opts?: DeclutterLabelsOptions,
+): number[];
+
+export interface DirectLabelItem {
+  /** The true data point the label refers to (figure coordinates). */
+  anchor: AnnotationPoint;
+  /** The label's extent along the layout axis. */
+  size: number;
+  /** Optional identifier, echoed back on the matching output (input order). */
+  key?: string | number;
+}
+export interface DirectLabelsOptions {
+  /** Axis the labels declutter along. 'y' = a vertical column. Default 'y'. */
+  axis?: 'x' | 'y';
+  /** Fixed coordinate on the other axis where the label column/row sits. Default 0. */
+  cross?: number;
+  /** Minimum gap kept between adjacent labels. Default 0. */
+  gap?: number;
+  /** Lower bound of the layout axis. Default -Infinity. */
+  min?: number;
+  /** Upper bound of the layout axis. Default Infinity. */
+  max?: number;
+  /** Leader-line shape. Default 'straight'. */
+  shape?: 'straight' | 'elbow' | 'curve';
+}
+export interface DirectLabel {
+  /** Placed label point — the leader's label-side end. */
+  x: number;
+  y: number;
+  /** The echoed input anchor. */
+  anchor: AnnotationPoint;
+  /** The echoed input key, if any. */
+  key?: string | number;
+  /** SVG path for the leader (anchor → label point); '' if they coincide. */
+  d: string;
+}
+/**
+ * Direct labeling: declutter labels along one axis and draw a leader from each
+ * anchor to its placed label (reusing the connector kernel). Deterministic and
+ * pure — no scales, no DOM, no 2-D placement. Output feeds a
+ * `<path class="ui-annotation__connector">` plus a label at `{x, y}`.
+ */
+export declare function directLabels(
+  items: DirectLabelItem[],
+  opts?: DirectLabelsOptions,
+): DirectLabel[];