@graphysdk/react-renderer 0.0.1-plugins.9 → 1.8.1-beta.1786024899180

package/dist/index.d.ts

@@ -1,78 +1,98 @@
-import { AnimationPlaybackOptions } from 'motion/react';
-import { AnnotationDef } from '@graphysdk/viz-engine';
-import { AnnotationZOrder } from '@graphysdk/viz-engine';
+import { AnchorPlacement } from '@graphysdk/viz-engine';
 import { AppearanceConfig } from '@graphysdk/viz-engine';
+import { BrandMarkVariant } from '@graphysdk/viz-engine';
 import { CartesianCoordSystem } from '@graphysdk/viz-engine';
+import { ColorScheme } from '@graphysdk/viz-engine';
 import { Command } from '@graphysdk/viz-engine';
+import { CommandStackSnapshot } from '@graphysdk/viz-engine';
+import { CompiledLayer } from '@graphysdk/viz-engine';
 import { CompiledLayerFor } from '@graphysdk/viz-engine';
+import { CompiledPanel } from '@graphysdk/viz-engine';
 import { CompiledSpec } from '@graphysdk/viz-engine';
-import { CompilerInput } from '@graphysdk/viz-engine';
+import { Component } from 'react';
+import { ComponentType } from 'react';
 import { CoordSystem } from '@graphysdk/viz-engine';
+import { CreateGraphyBuilderOptions } from '@graphysdk/viz-engine';
 import { CSSProperties } from 'react';
 import { CustomPalettesInput } from '@graphysdk/viz-engine';
 import { Data } from '@graphysdk/viz-engine';
+import { DispatchOptions } from '@graphysdk/viz-engine';
+import { EditTarget } from '@graphysdk/viz-engine';
+import { ErrorInfo } from 'react';
 import { FontSpec } from '@graphysdk/viz-engine';
+import { FormattedAxis } from '@graphysdk/viz-engine';
+import { FormattedHeadline } from '@graphysdk/viz-engine';
+import { FormattedLegend } from '@graphysdk/viz-engine';
 import { Geom } from '@graphysdk/viz-engine';
-import { GeomIdentity } from '@graphysdk/viz-engine';
 import { GeomName } from '@graphysdk/viz-engine';
 import { GraphLayout } from '@graphysdk/viz-engine';
-import { GraphTheme } from '@graphysdk/viz-engine';
-import { HighlightStrategy } from '@graphysdk/viz-engine';
+import { GraphyBuilder } from '@graphysdk/viz-engine';
+import { HeadlineMeasurer } from '@graphysdk/viz-engine';
 import { HoverHit } from '@graphysdk/viz-engine';
 import { HoverState } from '@graphysdk/viz-engine';
+import { IntroStaggerOrder } from '@graphysdk/viz-engine';
 import { JSX } from 'react/jsx-runtime';
+import { LayerIntroPlan } from '@graphysdk/viz-engine';
+import { LayoutEdge } from '@graphysdk/viz-engine';
 import { LineStyleType } from '@graphysdk/viz-engine';
 import { Locale } from '@graphysdk/viz-engine';
 import { MeasuredText } from '@graphysdk/viz-engine';
-import { MotionValue } from 'motion/react';
 import { Observation } from '@graphysdk/viz-engine';
-import { PanelHitTester } from '@graphysdk/viz-engine';
+import { Plugin as Plugin_2 } from '@graphysdk/viz-engine';
+import { PointerRegion } from '@graphysdk/viz-engine';
 import { PolarCoordSystem } from '@graphysdk/viz-engine';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
-import { RefCallback } from 'react';
-import { ResolvedTarget } from '@graphysdk/viz-engine';
-import { Stat } from '@graphysdk/viz-engine';
+import { Rect } from '@graphysdk/viz-engine';
+import { Ref } from 'react';
+import { RefObject } from 'react';
+import { RenderHitTester } from '@graphysdk/viz-engine';
+import { ResolvedHeadlineSize } from '@graphysdk/viz-engine';
+import { SourceContent } from '@graphysdk/viz-engine';
+import { Spec } from '@graphysdk/viz-engine';
+import { SpecInput } from '@graphysdk/viz-engine';
+import { StoreApi } from 'zustand';
 import { SVGProps } from 'react';
-import { SwatchShape } from '@graphysdk/viz-engine';
+import { TextContent } from '@graphysdk/viz-engine';
 import { TextMeasurer } from '@graphysdk/viz-engine';
 import { TooltipContent } from '@graphysdk/viz-engine';
-import { TooltipRow } from '@graphysdk/viz-engine';
-import { TransformStrategy } from '@graphysdk/viz-engine';
+import { VizDiagnostic } from '@graphysdk/viz-engine';
 
 /**
- * The drawing surface a custom annotation paints into (ADR-035): a panel-positioned [0,1] frame.
- * `targets` are the resolved coordinates in **top-left [0,1]**; `area` carries the panel's pixel size
- * for the cases [0,1] cannot express (text extents, fixed-length leaders); `params` is the kind's typed
- * params. The draw function returns static nodes — annotations have no hover or tooltip.
+ * Props for the AxisLabel slot — the axis title of every axis (e.g. "Revenue"), overridable via
+ * `slots.AxisLabel`. `labelRects` are SVG-local, keyed by edge. The tick band is a separate slot — see
+ * `AxisTicks`.
  */
-export declare interface AnnotationDrawInput<TParams extends object = object> {
-    targets: readonly ResolvedTarget[];
-    area: {
-        width: number;
-        height: number;
-    };
-    params: TParams;
+export declare interface AxisLabelSlotProps {
+    formattedAxes: FormattedAxis[];
+    labelRects: Partial<Record<LayoutEdge, Rect>>;
 }
 
 /**
- * A custom annotation's render half. `type` resolves it for a compiled annotation; `zOrder` is the
- * kind's default slot (background paints before geoms, foreground after) — overridable per instance;
- * `draw` is a React render function that may reuse the render kit (theme tokens, `toPercent`, value
- * readers) but never participates in hover.
+ * Props for the AxisTicks slot — the tick lines and tick labels of every axis, overridable via
+ * `slots.AxisTicks`. `tickRects` are SVG-local, keyed by edge. The axis title is a separate slot — see
+ * `AxisLabel`.
  */
-export declare interface AnnotationPlugin {
-    type: string;
-    zOrder: AnnotationZOrder;
-    draw: (input: AnnotationDrawInput) => ReactNode;
+export declare interface AxisTicksSlotProps {
+    formattedAxes: FormattedAxis[];
+    tickRects: Partial<Record<LayoutEdge, Rect>>;
 }
 
-/** The render half an author supplies to {@link defineAnnotationRenderer} — everything but `type`. */
-declare interface AnnotationRenderHalf<TParams extends object> {
-    zOrder: AnnotationZOrder;
-    draw: (input: AnnotationDrawInput<TParams>) => ReactNode;
+/** Made with Graphy provenance badge — capsule + glyph + system-face copy. */
+export declare const BrandMark: ({ visual, placement }: BrandMarkProps) => JSX.Element;
+
+declare interface BrandMarkProps {
+    visual: Exclude<BrandMarkVisual, 'hidden'>;
+    placement: 'footer' | 'header';
 }
 
-export { AnnotationZOrder }
+/**
+ * How the badge paints at the current frame size:
+ * - `full` — glyph + "Made with Graphy" pill
+ * - `mini` — circular glyph capsule (also the under-200 px ladder step)
+ * - `hidden` — flag off, or frame below the minimum footprint
+ */
+export declare type BrandMarkVisual = 'full' | 'mini' | 'hidden';
 
 /**
  * Browser text measurer backed by OffscreenCanvas.
@@ -129,59 +149,79 @@ export declare class CanvasTextMeasurer implements TextMeasurer {
 }
 
 /**
- * Hover-overlay dot drawn at a non-primary hit's `(x, y)`: a single circle at reduced opacity
- * so it reads as secondary. Used for any companion hit — same-layer sibling (e.g. another
- * series at the primary X) or cross-layer related.
+ * The compiled layer a renderer's handlers receive. A built-in renderer keyed to a `GeomName` gets
+ * its param-narrowed `CompiledLayerFor<G>`; a custom renderer (`G = string`) is downstream of
+ * serialisation, never sees the plugins array, and reads the base {@link CompiledLayer} dynamically.
  */
-export declare const CompanionDot: ({ hit }: CompanionDotProps) => JSX.Element;
-
-declare interface CompanionDotProps {
-    hit: HoverHit;
-}
+declare type CompiledLayerOf<G extends GeomName | string> = G extends GeomName ? CompiledLayerFor<G> : CompiledLayer;
 
-export declare type CoordKind = CoordSystem['type'];
+declare type CoordKind = CoordSystem['type'];
 
 /** Maps a coord-kind discriminator to the corresponding `CoordSystem` member. */
 declare type CoordSystemFor<C extends CoordKind> = C extends 'cartesian' ? CartesianCoordSystem : C extends 'polar' ? PolarCoordSystem : never;
 
-export declare const darkTheme: string;
-
 /**
- * Binds a custom annotation's render half to its imported compile-half {@link AnnotationDef}: the kind
- * name (`def.type`) and the params type (`def.defaultParams`) are read from `def`, so the half never
- * re-declares them and cannot disagree with the definition — the construction-level handshake mirroring
- * `defineGeomRenderer`. `draw` receives the resolved targets with `params` typed from the def.
+ * Ergonomic entry point for a React app: pass `plugins` once and get back a {@link GraphyKit} — the
+ * typed builder plus a `GraphProvider` that already carries them. Pure sugar over the primitives
+ * (`createGraphyBuilder`, `<GraphProvider plugins>`); use those directly for headless or advanced
+ * wiring. The `const` type parameter captures the `plugins` tuple literally, so `kit.geom.<customName>`
+ * is typed.
  */
-export declare function defineAnnotationRenderer<TParams extends object>(def: AnnotationDef<TParams>, half: AnnotationRenderHalf<TParams>): AnnotationPlugin;
+export declare function createGraphyKit<const P extends readonly Plugin_2[] = []>(options?: CreateGraphyBuilderOptions<P>): GraphyKit<P>;
 
 /**
- * Type-narrowing constructor for a plugin. Each plugin file declares its `(geom, coord)` pair and its
- * `highlightStrategy` inline; TypeScript infers `G`/`C`/`S` from the object literal — handlers then
- * receive `CompiledLayerFor<G>` / `CoordSystemFor<C>` with no `as` casts. Whether `getOverlayAnchor` is
- * required follows from the declared `highlightStrategy` via {@link GeomPluginForStrategy}. A custom geom
- * supplies its params type `TParams` (e.g. by annotating `render`'s input) to type `layer.params`.
+ * Per-chart Zustand store for what is selected. Nothing in the geom paint path reads it, so a
+ * selection change repaints no geoms and re-runs no layout.
  *
- * Returns the broad `GeomPlugin` type (with the type parameters erased) so all plugins fit into one
- * registry. The cast inside this helper is safe because the registry routes every call to the plugin
- * keyed by `(geom, coord)`.
+ * `setSelection` holds the current state when the incoming selection is structurally equal to it: a
+ * target is rebuilt from whatever was clicked rather than handed back, so only a structural check
+ * keeps a repeated click on the same thing from notifying every subscriber.
+ */
+declare const createSelectionStore: () => StoreApi<SelectionStoreState>;
+
+/** vanilla-extract class that binds the dark token values; set it on any ancestor to flip to dark. */
+export declare const darkTheme: string;
+
+/** Default paint for the footer region — caption, source line, and optional footer-anchored badge. */
+export declare const DefaultFooter: ({ ref, footerRect, mode, caption, isCaptionVisible, source, isSourceVisible, brandMark, }: FooterSlotProps) => JSX.Element | null;
+
+/** Default paint for the grid region — per-tick gridlines, drawn inside the panel frame rect. */
+export declare const DefaultGrid: ({ axes, panel, panelFrameRect, panelRect }: GridSlotProps) => JSX.Element;
+
+/** Default paint for the header region — title, subtitle, and optional header-anchored badge. */
+export declare const DefaultHeader: ({ ref, headerRect, mode, title, isTitleVisible, subtitle, isSubtitleVisible, brandMark, }: HeaderSlotProps) => JSX.Element | null;
+
+/** The built-in glyph for each {@link SwatchShape}. */
+export declare const DefaultSwatch: ({ shape, color, lineType, width, height, }: Omit<SwatchSlotProps, "surface" | "label">) => JSX.Element;
+
+/**
+ * Default tooltip body. Paints the box, header, and rows from the formatted {@link content}, and
+ * resolves each row's swatch shape off its geom's render contract for the active coord system.
+ * Positioning lives in the {@link Tooltip} wrapper, never here.
  */
-export declare function defineGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams = PluginParams<G>>(plugin: GeomPluginForStrategy<G, C, S, TParams>): GeomPlugin;
+export declare const DefaultTooltip: ({ content }: TooltipSlotProps) => JSX.Element;
 
 /**
- * Binds a geom's render half to its imported compile-half {@link Geom} definition: the geom name
- * (`def.type`), the highlight strategy (`def.highlightStrategy`), and the params type
- * (`def.defaultParams`) are all read from `def`, so the half never re-declares them and cannot disagree
- * with the definition — the construction-level handshake. Whether `getOverlayAnchor` is required follows
- * from the def's declared `highlightStrategy`, and `render`/`renderHover` receive `layer.params` typed
- * from the def with no annotation. Built-in plugins keep {@link defineGeomPlugin}; reach for this only to
- * pair a custom geom's two halves.
+ * Dual-target renderer binding, keyed on whether the first argument is a compile definition or a built-in
+ * geom name:
  *
- * Returns the broad {@link GeomPlugin} (type parameters erased) so every plugin fits one registry; the
- * cast is the same variance bypass {@link defineGeomPlugin} performs, safe because the registry routes
- * each call by `(geom, coord)`.
+ * - **Whole new geom** — `defineGeomRenderer(definition, contract)` pairs the render contract with its
+ *   compile definition, producing a {@link GeomRendererDefinition}. Registering the result registers both
+ *   sides: the compile definition is reachable at `.definition` and the geom name is read from it, so the
+ *   two halves cannot drift.
+ * - **Render-only override** — `defineGeomRenderer('bar', contract)` rebinds only the paint half of an
+ *   existing built-in, producing a {@link ResolvedGeomRenderer} that carries no `.definition`. The built-in
+ *   compile half keeps running (nothing re-seeds the compile registry); only the render registry changes.
+ *   The name is constrained to {@link GeomName}, so a by-name override of an unknown built-in is a
+ *   compile-time error. To restyle a *custom* geom, rebind its definition (which you hold) via the first form.
  */
-export declare function defineGeomRenderer<Def extends Geom, C extends CoordKind>(def: Def, half: GeomRenderHalf<Def, C>): GeomPlugin;
+export declare function defineGeomRenderer<Definition extends Geom<unknown>>(definition: Definition, contract: GeomRenderContract): GeomRendererDefinition & {
+    readonly definition: Definition;
+};
+
+export declare function defineGeomRenderer<G extends GeomName>(geom: G, contract: GeomRenderContract): ResolvedGeomRenderer;
 
+/** Dev-only compile-cache inspector; render inside a `<GraphProvider>`. See {@link DevToolsPanelProps}. */
 export declare const DevToolsPanel: ({ width, style, className }?: DevToolsPanelProps) => JSX.Element;
 
 /**
@@ -198,84 +238,320 @@ export declare interface DevToolsPanelProps {
     className?: string;
 }
 
-export declare const emToPx: (em: number, textScale: number) => number;
+/** Props the renderer passes to the editor layer filling the `EditorSurface` slot. */
+export declare interface EditorSurfaceSlotProps {
+    /** The frame's content box — the element the layer measures, listens on and aligns its chrome to. */
+    frameElement: HTMLElement;
+    /** The panel's rect within that box, so chrome positioned from `layout` shares its origin. */
+    panelRect: Rect;
+}
+
+declare const FONT_STYLES: readonly ["normal", "italic", "oblique"];
 
 /**
- * Whether a region is large enough to carry a label: both dimensions must clear their minimum. Works in
- * any single consistent space — pass unit dimensions with unit thresholds, or pixels with pixel
- * thresholds. A space-filling geom (treemap) culls labels with it so a tile too small to fit text stays
- * unlabelled rather than overflowing.
+ * A CSS length keeping its unit so measurement can treat it like CSS paint does: em scales with
+ * `textScale` (see `emToPx`), px stays absolute.
  */
-export declare function fitsLabel(width: number, height: number, minWidth: number, minHeight: number): boolean;
+export declare interface FontLength {
+    value: number;
+    unit: 'px' | 'em';
+}
 
-/** A geom's declared highlight composition strategy, or `null` when it opts out of highlighting. */
-declare type GeomHighlightStrategy = HighlightStrategy | null;
+/** A CSS `font-style` keyword accepted by a measured font token override. */
+export declare type FontStyle = (typeof FONT_STYLES)[number];
 
 /**
- * Self-contained module owning everything a single `(geom, coord)` composition needs to paint
- * and respond to hover. Plugins are dispatched via the registry keyed on `(geom, coord)` —
- * the registry guarantees the input shapes match the plugin's identity.
- *
- * Generic by default: a plugin parameterised as `GeomPlugin<'bar', 'cartesian'>` declares
- * narrow input types so its handlers receive `CompiledLayerFor<'bar'>` /
- * `CartesianCoordSystem` directly, no runtime checks. Use {@link defineGeomPlugin} to build
- * one — the helper centralizes the variance cast so individual plugin files stay free of
- * `as` assertions.
- *
- * The public shape is a flat `NoOverlayAnchor | OverlayAnchor` union so call sites can
- * invoke `plugin.render(...)` against `CompiledLayerFor<GeomIdentity>` without each call site
- * having to discriminate. Per-plugin enforcement of `getOverlayAnchor` happens at the
- * {@link defineGeomPlugin} boundary via {@link GeomPluginForStrategy}, keyed on the plugin's own
- * declared `highlightStrategy` — so a custom geom is gated by what it declares, not a name lookup.
+ * A structured override of a measured font token. Omitted fields keep the token's default (which
+ * still cascades from the leaf tokens, e.g. `fontSizeXs`), so `{ weight: 600 }` changes only the
+ * weight.
  */
-export declare type GeomPlugin<G extends string = GeomIdentity, C extends CoordKind = CoordKind> = NoOverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>> | OverlayAnchorGeomPlugin<G, C, GeomHighlightStrategy, PluginParams<G>>;
+export declare interface FontTokenOverride {
+    family?: string;
+    weight?: number;
+    style?: FontStyle;
+    size?: FontLength;
+    /** Unitless multiplier; sizes HTML line boxes (legend band). Canvas measurement ignores it. */
+    lineHeight?: number;
+}
 
-declare interface GeomPluginBase<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> {
-    geom: G;
+/**
+ * Props for the Footer slot, overridable via `slots.Footer` on `GraphRenderer`. Caption editing in
+ * `editable` mode is internal to this default; an override replacing the region opts out of it.
+ */
+export declare interface FooterSlotProps {
+    /** Forward this to the region's outer element — the layout measures the rendered DOM to reserve its space. */
+    ref?: React.Ref<HTMLDivElement>;
+    footerRect: Rect;
+    mode?: GraphMode;
+    caption: TextContent | null;
+    isCaptionVisible: boolean;
+    source: SourceContent | null;
+    isSourceVisible: boolean;
+    /**
+     * Resolved badge visual for footer placement. `hidden` when the mark is off, below the min
+     * footprint, or configured for header placement.
+     */
+    brandMark: BrandMarkVisual;
+}
+
+/** A custom geom `renderHoverCompanions` handler's input: the layer plus the primary and related hover hits. */
+export declare type GeomHoverCompanionsRendererInput = HoverCompanionsRenderInput;
+
+/** Page-relative cursor coordinates the push-path tooltip anchors to. */
+export declare interface GeomHoverCursor {
+    clientX: number;
+    clientY: number;
+}
+
+/**
+ * Pushes a hovered observation key into the central hover, or clears this layer's hover with `null`.
+ * A non-null key requires a `cursor` — the overlay intercepts the pointer events the cursor-follow
+ * tooltip would otherwise read, so the anchor can only come from the geom's own handler. Consumed by
+ * {@link InteractiveOverlayApi.pushHover} and returned by `useGeomHover`.
+ */
+export declare interface GeomHoverPush {
+    (key: string, cursor: GeomHoverCursor): void;
+    (key: null): void;
+}
+
+/** A custom geom `renderHover` handler's input: the hovered layer plus the primary/group/related hover hits. */
+export declare type GeomHoverRendererInput = HoverRenderInput;
+
+/** A custom geom `getOverlayAnchor` handler's input: the layer, coord system, and the matched observation. */
+export declare type GeomOverlayAnchorRendererInput = OverlayAnchorInput;
+
+/** An overlay-hosted geom's paint function — receives the guaranteed overlay wiring on `input.overlay`. */
+export declare type GeomOverlayRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomOverlayRenderInput<G, C>) => ReactNode;
+
+/**
+ * The input an overlay-hosted render (`{ fn, options: { overlay: true } }`) receives: the standard render
+ * input plus a guaranteed {@link InteractiveOverlayApi}. The renderer always supplies it, so the geom's
+ * render uses `overlay` unconditionally — it never decides where it is mounted, only what it paints.
+ */
+export declare interface GeomOverlayRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
+    overlay: InteractiveOverlayApi;
+}
+
+/**
+ * A geom's `render`: either a plain panel-SVG paint function, or an overlay-hosted one paired with
+ * `options` — so a geom that must paint into the interactive overlay declares
+ * `{ fn, options: { overlay: true } }` without a second render entry point. The
+ * renderer decides where each is mounted; the geom only decides what it paints. `render` is the single
+ * paint declaration either way.
+ */
+export declare type GeomRender<G extends GeomName | string = string, C extends CoordKind = CoordKind> = GeomRenderFn<G, C> | {
+    fn: GeomOverlayRenderFn<G, C>;
+    options: GeomRenderOptions;
+};
+
+/**
+ * The render side of a geom: everything a single `(geom, coord)` composition needs to render and
+ * respond to hover. Generic over the geom name and coord kind, so a built-in renderer parameterised
+ * as `GeomRenderContract<'bar', 'cartesian'>` receives param-narrowed inputs (`CompiledLayerFor<'bar'>`,
+ * `CartesianCoordSystem`), while the default `<string, CoordKind>` instantiation is the base/custom
+ * contract a plugin author writes against. The geom's name, highlight strategy, and `params` type are
+ * NOT restated here — they are read off the compile definition this contract is bound to (see
+ * {@link defineGeomRenderer}). This is the single declaration of a geom's render contract; the built-in
+ * narrow form below and the base/custom form (`geom-renderer.ts`) are both instantiations of it.
+ */
+export declare interface GeomRenderContract<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    /** The coord system this contract paints under. A geom may bind one contract per coord. */
     coord: C;
+    swatchShape?: SwatchShape;
+    /**
+     * The hover-guide mode this `(geom, coord)` draws when it is the hovered layer (a
+     * {@link HoverGuideMode}). Omit it — or contribute `null` — to draw no guide (the geom's mark is its
+     * own highlight). A declared mode the composition can't realise draws nothing: a polar bar's `'band'`
+     * fills a wedge, but a pie/donut (no category band) resolves to an empty one. `resolveHoverGuideMode`
+     * reads the hovered layer's mode to pick the one guide the chart draws.
+     */
+    guideMode?: HoverGuideMode | null;
+    /**
+     * The geom's paint. A plain function paints into the panel SVG; the `{ fn, options: { overlay: true } }`
+     * form paints into a screen-aligned portal above the central capture layer for a live/drag-driven geom
+     * that owns its pointer events (force-directed), with the wiring on `input.overlay`.
+     */
+    render: GeomRender<G, C>;
     /**
-     * The geom's highlight composition strategy — the same value its compile-half declares. Drives the
-     * `getOverlayAnchor` requirement at the {@link defineGeomPlugin} boundary, so the render contract is
-     * derived from a declared strategy rather than a closed geom-name lookup.
+     * Optional repaint of the matched subset for the highlight overlay. Omit it and the highlight layer
+     * falls back to {@link render}. A geom overrides it when the plain column-grouped render would
+     * misrepresent a matched subset — a bar repaints each matched observation as an isolated stack segment
+     * (from its compiled stack role), so a lone mid-stack match keeps its square-edged silhouette and
+     * single-width border instead of regrouping into a standalone rounded bar.
      */
-    highlightStrategy: S;
-    guideMode: HoverGuideMode | null;
-    render: (input: GeomRenderInput<G, C, TParams>) => ReactNode;
-    renderHover: (input: HoverRenderInput<G, C, TParams>) => ReactNode;
-    renderHoverCompanions: (input: HoverCompanionsRenderInput<G, TParams>) => ReactNode;
+    renderHighlight?: (input: HighlightRenderInput<G, C>) => ReactNode;
+    renderHover: (input: HoverRenderInput<G, C>) => ReactNode;
+    renderHoverCompanions: (input: HoverCompanionsRenderInput<G>) => ReactNode;
     /**
-     * Optional: paints the tooltip body when one of this geom's observations is the primary hit. The
-     * renderer keeps the positioned, themed card and calls this for its contents only; returning `null`
-     * falls through to the default body. The input carries the engine-built {@link TooltipContent} (feed
-     * it to `TooltipBody` to reproduce the default) and the raw `primary.observation`.
+     * Render-side spatial query for a `'render-hit-test'` layer whose geometry is precomputed into the
+     * compiled spec (sankey ribbons, treemap tiles, voronoi cells). A
+     * **factory**: given the render input it returns the per-cursor {@link RenderHitTester};
+     * the renderer memoizes the factory on `layer.data`, so the read runs once per data change and the
+     * per-move query allocates nothing. The author writes no hook; the renderer registers the tester on its
+     * behalf. The cursor arrives in panel-local `[0,1]` with a top-left origin — the frame the geom paints
+     * in. Returns the declared identity key of the observation under the cursor, or `null` for a miss.
      */
-    renderTooltip?: (input: TooltipRenderInput<G, C, TParams>) => ReactNode;
+    hitTest?: (input: GeomRenderInput<G, C>) => RenderHitTester;
+    /** Panel-space anchor for a matched observation; required when the def highlights via overlay-anchor. */
+    getOverlayAnchor?: (input: OverlayAnchorInput<G, C>) => OverlayAnchor | null;
 }
 
 /**
- * Picks the plugin shape required for a plugin's own declared `highlightStrategy`. Only the
- * `'overlay-anchor'` strategy demands the anchor reader; `'observation-rerender'` and `null` (no
- * highlight) both resolve to {@link NoOverlayAnchorGeomPlugin}.
- *
- * Used by {@link defineGeomPlugin} to enforce the strategy→shape coupling at plugin-definition
- * sites — `observation-rerender` plugins cannot declare `getOverlayAnchor`, `overlay-anchor` ones must
- * — for any geom name, built-in or custom, with no closed geom-name lookup.
+ * A render contract paired with the compile definition it paints for. The engine recovers the definition
+ * structurally from `.definition` (React-free), and the renderer reads the geom name from the same
+ * definition — so the compile and render sides are one declaration consumed twice, never two matched by
+ * a string.
  */
-declare type GeomPluginForStrategy<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> = S extends 'overlay-anchor' ? OverlayAnchorGeomPlugin<G, C, S, TParams> : NoOverlayAnchorGeomPlugin<G, C, S, TParams>;
+export declare interface GeomRendererDefinition extends ResolvedGeomRenderer {
+    /** The compile definition this renderer paints for. Held by reference — the single source of identity. */
+    readonly definition: Geom<unknown>;
+}
 
-/**
- * The render half an author supplies to {@link defineGeomRenderer}: every field of a plugin except the
- * two its imported compile-half definition already declares — `geom` and `highlightStrategy`.
- * `getOverlayAnchor` is gated on the def's declared strategy via {@link GeomPluginForStrategy}, so the
- * render contract is bound to the definition rather than re-declared.
- */
-declare type GeomRenderHalf<Def extends Geom, C extends CoordKind> = Omit<GeomPluginForStrategy<Def['type'] & string, C, Def['highlightStrategy'], Def['defaultParams']>, 'geom' | 'highlightStrategy'>;
+/** A custom geom render handler's input — the base instantiation of the typed built-in inputs. */
+export declare type GeomRendererInput = GeomRenderInput;
 
-export declare interface GeomRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
-    layer: CompiledLayerFor<G, TParams>;
+/** A geom's panel-SVG paint function — the plain `render` form. */
+export declare type GeomRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomRenderInput<G, C>) => ReactNode;
+
+declare interface GeomRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    layer: CompiledLayerOf<G>;
     coordSystem: CoordSystemFor<C>;
     isAnimated: boolean;
     formattingLocale: Locale;
+    intro?: LayerIntroPlan | null;
+}
+
+/**
+ * Hosting options for an overlay render. The presence of the object form already declares overlay hosting;
+ * `overlay: true` makes the call site read explicitly (and leaves room for further hosting options later).
+ */
+export declare interface GeomRenderOptions {
+    /**
+     * Mount this render's output in a screen-aligned portal above the central capture layer, rather than in
+     * the panel SVG — for a live or drag-driven geom that must own its pointer events (force-directed). The
+     * renderer then supplies {@link GeomOverlayRenderInput.overlay}.
+     */
+    overlay: true;
+}
+
+export declare interface GraphAnimationProps {
+    /**
+     * Settings for the intro animation played on first mount. `false` disables it, `true` forces it on,
+     * an object overrides individual intro settings. Defaults on.
+     */
+    intro?: boolean | Partial<IntroAnimationOptions>;
+}
+
+/** Write access to the graph's spec: applying {@link Command}s and closing the runs they form. */
+export declare interface GraphCommands {
+    /** Applies a command to the provider's live spec. */
+    dispatch: (command: Command, options?: DispatchOptions) => void;
+    /**
+     * Closes a run of `{ transient: true }` dispatches and fires `onChange` once for it. Call it when
+     * the gesture ends — pointer up, blur. Forgetting only delays the notification rather than
+     * corrupting undo: the run covers one {@link EditTarget}, and the next committed dispatch, undo,
+     * redo or external change closes it.
+     */
+    seal: () => void;
+}
+
+/**
+ * The single place a chart surfaces an error in place — instead of unwinding the page to a blank
+ * screen. Two failure modes converge here: a non-throwing **compile failure** the host passes via
+ * {@link GraphErrorBoundaryProps.forcedErrors}, and a **render-throw** from a renderer component that
+ * this boundary catches. Both render the same {@link GraphErrorPanel}, so there is exactly one panel
+ * call site rather than one per failure mode.
+ */
+export declare class GraphErrorBoundary extends Component<GraphErrorBoundaryProps, GraphErrorBoundaryState> {
+    state: GraphErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): GraphErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(prevProps: GraphErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
+declare interface GraphErrorBoundaryProps {
+    children: ReactNode;
+    /**
+     * Compile failures to surface in place, rendered through the same panel as a caught render-throw
+     * so a chart has one predictable place for its errors.
+     */
+    forcedErrors?: VizDiagnostic[] | null;
+    /**
+     * When any key changes after a caught render-throw, the boundary clears it and
+     * retries — so a fixed spec recovers. */
+    resetKeys?: readonly unknown[];
+    /**
+     * Called with a single-element list when a child throws during render
+     * (not for `forcedErrors`, which the host already reported).
+     */
+    onError?: (errors: VizDiagnostic[]) => void;
+}
+
+declare interface GraphErrorBoundaryState {
+    caughtDiagnostic: VizDiagnostic | null;
+}
+
+/**
+ * Shared in-place fallback for a chart that failed to compile or render. Shows each diagnostic's
+ * `code`, `message`, and `suggestion` — richer than a bare error message — so an end user can file
+ * a useful report and a developer can see what to fix. Theme-independent: it can render before the
+ * theme provider mounts.
+ */
+export declare const GraphErrorPanel: ({ errors }: GraphErrorPanelProps) => JSX.Element;
+
+declare interface GraphErrorPanelProps {
+    /** The compile failure(s). The first headlines; any remaining are listed beneath it. */
+    errors: VizDiagnostic[];
+}
+
+/**
+ * Imperative handle on a graph, for an app's key handling, toolbar or menu bar mounted above the
+ * tree the hooks can reach. Obtained through {@link GraphProviderProps.handleRef}.
+ */
+export declare interface GraphHandle {
+    /** Write access to the graph's spec, the same surface {@link useGraphCommands} serves inside the tree. */
+    commands: GraphCommands;
+    /**
+     * Registers a listener fired on every change to the graph; returns the unsubscribe. With
+     * {@link GraphHandle.getCompiled} it is what `useSyncExternalStore` needs, so a surface outside the
+     * graph's tree stays in step with it. Subscribing before the graph compiles is valid.
+     */
+    subscribe: (onGraphChange: () => void) => () => void;
+    /** The graph's compiled spec as of now, or `null` before its first successful compile. */
+    getCompiled: () => CompiledSpec | null;
+    /**
+     * Reverse the most recent command. Returns whether the chart took the step, so a caller driving
+     * this from a keystroke can leave the key to the app when the chart has nothing to undo or the
+     * older spec no longer compiles.
+     */
+    undo: () => boolean;
+    /** Re-apply the most recently undone command. Returns whether the chart took the step. */
+    redo: () => boolean;
+    /** What the chart holds selected as of now; empty when nothing is. */
+    getSelection: () => readonly EditTarget[];
+    /** Replace what the chart holds selected. */
+    setSelection: (next: readonly EditTarget[]) => void;
+    /** Registers a listener fired on every change to the selection; returns the unsubscribe. */
+    subscribeSelection: (onSelectionChange: () => void) => () => void;
+}
+
+/** Undo/redo controls plus the command stack's own snapshot, which a history UI reads. */
+export declare type GraphHistory = CommandStackSnapshot & {
+    /** Reverses the most recent command; returns whether the chart took the step, as {@link GraphHandle.undo}. */
+    undo: () => boolean;
+    /** Re-applies the most recently undone command; returns whether the chart took the step, as {@link GraphHandle.undo}. */
+    redo: () => boolean;
+};
+
+export declare interface GraphHistoryShortcutsOptions {
+    /**
+     * What to listen on. Defaults to `window`; an element — or a ref holding one — scopes the chords
+     * to a subtree, and `null` binds nothing.
+     */
+    target?: EventTarget | RefObject<EventTarget | null> | null;
+    /** Set to `false` to unbind without moving the call out of the component. Defaults to `true`. */
+    enabled?: boolean;
 }
 
 /**
@@ -287,32 +563,37 @@ export declare type GraphMode = 'readonly' | 'editable';
 
 /**
  * Owns the compiled spec for a graph and exposes it via {@link useCompiledSelector}, plus a
- * `dispatch` for applying {@link Command}s. Wraps the chart in {@link GraphErrorBoundary} so an
- * invalid spec surfaces its error in place instead of unwinding the surrounding app — every chart
- * gets this isolation for free, with no per-chart boundary to author.
+ * `dispatch` for applying {@link Command}s. Both failure modes — a non-throwing compile failure and a
+ * render-throw from a renderer component — converge on a single {@link GraphErrorBoundary} that shows
+ * the error in place, so a broken chart never blanks the page.
  */
-export declare const GraphProvider: (props: GraphProviderProps) => JSX.Element;
+export declare const GraphProvider: ({ data, input, plugins, formattingLocale, handleRef, onChange, onError, onWarnings, customPalettes, colorScheme, themeOverrides, children, }: GraphProviderProps) => JSX.Element;
 
-declare interface GraphProviderProps {
+/** Props for {@link GraphProvider}: the data and spec input to compile, plus color scheme, locale and plugin wiring. */
+export declare interface GraphProviderProps {
     data: Data;
-    input: CompilerInput;
+    input: SpecInput;
+    /**
+     * Custom geoms, stats, and transforms (and their render halves) registered for this graph. Seeds
+     * the compiler and builds the per-provider render resolver from one array. Construction-time config,
+     * frozen at mount — change the registered set by remounting (React `key`); `data`/`input`/`colorScheme`
+     * stay reactive.
+     */
+    plugins?: readonly Plugin_2[];
     formattingLocale?: Locale;
-    onChange?: (next: CompilerInput) => void;
-    theme?: GraphTheme;
+    /**
+     * Filled with this graph's {@link GraphHandle}, for callers mounted outside the provider where the
+     * hooks can't reach. `useGraphHistoryShortcuts` binds the undo/redo chords to one.
+     */
+    handleRef?: Ref<GraphHandle>;
+    onChange?: (next: SpecInput) => void;
+    /** Fires with the compile failure(s) whenever a compile/recompile/dispatch produces errors. */
+    onError?: (errors: VizDiagnostic[]) => void;
+    /** Fires with any warnings a successful compile produced. */
+    onWarnings?: (warnings: VizDiagnostic[]) => void;
+    colorScheme?: ColorScheme;
     themeOverrides?: ThemeOverrides;
     customPalettes?: CustomPalettesInput;
-    /** Custom geom definitions, injected per-instance into the compiler (override built-ins by name). */
-    geoms?: readonly Geom[];
-    /** Custom stat definitions (`defineStat`), injected per-instance into the compiler (override built-ins by `type`). */
-    stats?: readonly Stat[];
-    /** Custom transform strategies (`defineTransform`), injected per-instance (override built-ins by `transformType`). */
-    transforms?: readonly TransformStrategy[];
-    /** Custom geom render plugins, injected per-instance (override built-ins by `(geom, coord)`). */
-    plugins?: readonly GeomPlugin[];
-    /** Custom annotation render plugins, injected per-instance and resolved by annotation `type` (ADR-035). */
-    annotationPlugins?: readonly AnnotationPlugin[];
-    /** Stable chart id. Stamped onto the rendered root as `data-graphy-id`; enables the editor bridge. */
-    id?: string;
     children: ReactNode;
 }
 
@@ -322,17 +603,20 @@ declare interface GraphProviderProps {
  * no `config` prop: every consumer must wrap with `<GraphProvider>` so commands can operate
  * on the live spec.
  */
-export declare const GraphRenderer: ({ sizing, onResize, ...props }: GraphRendererProps) => JSX.Element;
+export declare const GraphRenderer: ({ slots, sizing, onResize, ...rest }: GraphRendererProps) => JSX.Element;
 
-/** Props for {@link GraphRenderer}: container sizing, interaction toggles, and display mode. */
+/** Props for {@link GraphRenderer}: container sizing, interaction toggles and per-region slot overrides. */
 export declare interface GraphRendererProps {
     /** Controls how the graph responds to its container size. Defaults to filling the parent container. */
     sizing?: GraphSizing;
     /** Callback invoked when the graph's container is resized. Fires in every sizing mode. */
     onResize?: ResizeObserverOnResize;
     isAnimated?: boolean;
+    animation?: GraphAnimationProps;
     showTooltips?: boolean;
     mode?: GraphMode;
+    /** Per-region component overrides. Unspecified regions render their default. */
+    slots?: GraphSlots;
 }
 
 /** Controls how the graph claims space in its container. */
@@ -356,13 +640,118 @@ export declare type GraphSizing = {
     aspectRatio: number;
 };
 
-export declare interface HoverCompanionsRenderInput<G extends string = GeomName, TParams = PluginParams<G>> {
-    layer: CompiledLayerFor<G, TParams>;
+/**
+ * Region overrides for `GraphRenderer`. A slot replaces how one region paints; the viz-engine `Spec`
+ * still owns whether a region exists and what data it receives, and an override gets the same
+ * render-ready props as its default.
+ *
+ * Layout-safe regions (`Header`, `Footer`, `Tooltip`, `Grid`, `Swatch`, `EditorSurface`) are bare
+ * components — DOM-measured, reserving no edge space or painting inside a box the layout already sized.
+ * Layout-coupled regions (`AxisTicks`, `AxisLabel`, `Legend`, `Headline`) are
+ * {@link SlotOverride}s that also declare their reserved size via `measure`, else paint and the
+ * reserved band desync. The tick and title bands are separate slots so overriding one leaves the other
+ * on its default.
+ */
+export declare interface GraphSlots {
+    Header?: ComponentType<HeaderSlotProps>;
+    Footer?: ComponentType<FooterSlotProps>;
+    Tooltip?: ComponentType<TooltipSlotProps>;
+    Grid?: ComponentType<GridSlotProps>;
+    Swatch?: ComponentType<SwatchSlotProps>;
+    /**
+     * The chart's editor layer, mounted over the frame in `mode="editable"`. Only
+     * `@graphysdk/react-renderer/editable` exports something that fills it, so a read-only embed bundles
+     * no editing code.
+     */
+    EditorSurface?: ComponentType<EditorSurfaceSlotProps>;
+    Legend?: SlotOverride<LegendSlotProps, (legend: FormattedLegend, ctx: SlotMeasureContext) => number>;
+    Headline?: SlotOverride<HeadlineSlotProps, HeadlineMeasurer>;
+    AxisTicks?: SlotOverride<AxisTicksSlotProps, (axis: FormattedAxis, ctx: SlotMeasureContext) => number>;
+    AxisLabel?: SlotOverride<AxisLabelSlotProps, (axis: FormattedAxis, ctx: SlotMeasureContext) => number>;
+}
+
+/**
+ * A plugin-bound authoring kit: the typed `geom`/`stat`/`transform`/`scale`/`coord` factories plus
+ * `createSpec`/`pipe`, and a `GraphProvider` pre-bound to the same `plugins` — so what can be written
+ * and what can render derive from one array and cannot diverge. Generic over the `plugins` tuple so
+ * the typed per-plugin builder methods (`geom.<name>`, …) flow through to the React entry point.
+ */
+export declare interface GraphyKit<P extends readonly Plugin_2[] = readonly Plugin_2[]> extends GraphyBuilder<P> {
+    GraphProvider: (props: Omit<GraphProviderProps, 'plugins'>) => ReactElement;
+}
+
+/**
+ * Props for the Grid slot, overridable via `slots.Grid` on `GraphRenderer`. `panelRect` is in
+ * SVG-local coordinates.
+ */
+export declare interface GridSlotProps {
+    axes: FormattedAxis[];
+    panel: CompiledPanel;
+    panelFrameRect: GraphLayout['panelFrame'];
+    panelRect: GraphLayout['panel'];
+}
+
+/**
+ * Props for the Header slot, overridable via `slots.Header` on `GraphRenderer`. Title editing in
+ * `editable` mode is internal to this default; an override replacing the region opts out of it.
+ */
+export declare interface HeaderSlotProps {
+    /** Forward this to the region's outer element — the layout measures the rendered DOM to reserve its space. */
+    ref?: React.Ref<HTMLDivElement>;
+    headerRect: Rect;
+    mode?: GraphMode;
+    title: TextContent | null;
+    isTitleVisible: boolean;
+    subtitle: TextContent | null;
+    isSubtitleVisible: boolean;
+    /**
+     * Resolved badge visual for header placement. `hidden` when the mark is off, below the min
+     * footprint, or configured for footer placement.
+     */
+    brandMark: BrandMarkVisual;
+}
+
+/** Props for the Headline slot, overridable via `slots.Headline` on `GraphRenderer`. */
+export declare interface HeadlineSlotProps {
+    headline: FormattedHeadline;
+    rect: Rect;
+    resolvedSize: ResolvedHeadlineSize;
+    /** Leading strip items to paint; the rest are hidden because they would overflow the band. */
+    visibleItemCount: number;
+}
+
+/**
+ * The input a geom's {@link GeomRenderContract.renderHighlight} receives: the matched-subset layer plus
+ * the panel rect, so a geom that repaints matched observations in absolute panel pixels (bars drawing
+ * isolated stack segments) has the frame it needs. A superset of {@link GeomRenderInput}, so a geom that
+ * doesn't override `renderHighlight` still paints through the plain `render`.
+ */
+declare interface HighlightRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
+    panelRect: GraphLayout['panel'];
+    /** The full layer `layer` was filtered from — for context the subset can't see, like a stack's silhouette. */
+    sourceLayer: CompiledLayerOf<G>;
+}
+
+declare interface HoverCompanionsRenderInput<G extends GeomName | string = string> {
+    layer: CompiledLayerOf<G>;
     primary: HoverHit;
     related: HoverHit[];
 }
 
-export declare type HoverGuideMode = 'continuous' | 'bar';
+/**
+ * The shape of positional guide the `HoverGuide` draws for a hovered observation, contributed per
+ * `(geom, coord)` renderer via `guideMode`:
+ *
+ * - `'band'` — a rectangle over the hovered category's band on the main axis (bars).
+ * - `'crosshair'` — a rule at the hovered value: a straight line under cartesian, a centre-to-rim spoke
+ *   under polar (line and area).
+ *
+ * A renderer that omits `guideMode` draws no guide (scatter points). A declared `'band'` still draws
+ * nothing where the composition has no category band — a pie/donut resolves to an empty wedge. The chart
+ * draws the guide of whichever layer the cursor resolves to, so a combo shows a band over a hovered bar
+ * and a crosshair over a hovered line; see `resolveHoverGuideMode`.
+ */
+declare type HoverGuideMode = 'crosshair' | 'band';
 
 /**
  * Hosts the hover store + engine for the surrounding `<GraphProvider>`. Subscribes only to the
@@ -375,8 +764,8 @@ declare interface HoverProviderProps {
     children: ReactNode;
 }
 
-export declare interface HoverRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
-    layer: CompiledLayerFor<G, TParams>;
+declare interface HoverRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    layer: CompiledLayerOf<G>;
     coordSystem: CoordSystemFor<C>;
     primary: HoverHit;
     group: HoverHit[];
@@ -387,41 +776,77 @@ export declare interface HoverRenderInput<G extends string = GeomName, C extends
 declare interface HoverSlice {
     hover: HoverState;
     /**
-     * Whether the pointer is over the chart's interactive surface. Drives the tooltip's open/close at
-     * the enter/leave boundary. Held as state (not a ref) because that transition must re-render the
-     * tooltip; the cursor *position* stays a ref (see `HoverContextValue.cursorRef`) so pointer-rate
-     * moves reposition through floating-ui without re-rendering.
+     * Box the tooltip anchors against while the pointer is over a pinned anchor, in client
+     * coordinates. `null` during normal cursor hover, when the tooltip follows the cursor.
+     */
+    tooltipAnchor: TooltipAnchor | null;
+    /**
+     * Chrome hit regions the tracker tests before the geom hit-test, highest priority first. Whoever
+     * paints over the plot publishes its area here so hover detection stays in one pointer pipeline.
      */
-    isPointerInside: boolean;
+    pointerRegions: readonly PointerRegion[];
+    /** A gesture owns the pointer: the tracker runs no query, so nothing recomputes behind it. */
+    isPointerSuspended: boolean;
 }
 
 declare interface HoverStoreActions {
     setHoverState: (next: HoverState) => void;
-    setPointerInside: (value: boolean) => void;
+    setTooltipAnchor: (next: TooltipAnchor | null) => void;
+    /**
+     * Replaces one publisher's regions. Keying by publisher lets several features hold regions at once
+     * without clobbering each other; an empty list retracts the publisher entirely.
+     */
+    publishPointerRegions: (publisher: string, regions: readonly PointerRegion[]) => void;
+    setPointerSuspended: (next: boolean) => void;
 }
 
+/** State of the hover store: the current {@link HoverState} plus its setter. */
 declare type HoverStoreState = HoverSlice & HoverStoreActions;
 
-/** Lightens a hex colour by mixing it toward white by `amount` (`0` keeps the colour, `1` is white). */
-export declare function lighten(hex: string, amount: number): string;
-
-export declare const lightTheme: string;
-
 /**
- * Mixes a hex colour toward another by `amount` in `[0, 1]` (`0` keeps `hex`, `1` returns `towardHex`),
- * channel-wise in sRGB. Returns an `rgb(...)` string. Used for within-group shading where leaves share a
- * group hue and vary only in lightness.
+ * The overlay wiring handed to an overlay-hosted render via {@link GeomOverlayRenderInput.overlay}. The
+ * geom writes only its simulation, marks, and drag handlers; the renderer owns the on-screen rect
+ * measurement, the portal alignment, and the push wiring.
  */
-export declare function mixColor(hex: string, towardHex: string, amount: number): string;
+export declare interface InteractiveOverlayApi {
+    /** Feeds the hovered observation's identity key into the unified hover store — the push path. */
+    pushHover: GeomHoverPush;
+    /** The panel's on-screen rect in client pixels, so the overlay can place its marks. */
+    panelRect: ScreenRect;
+}
+
+declare interface IntroAnimationOptions {
+    /** Whether the entrance plays at all */
+    enabled: boolean;
+    /** Multiplier applied to every entrance duration and stagger delay. */
+    durationScale: number;
+    /** Whether geoms that support staggered entrance (bars) enter staggered rather than all at once. */
+    stagger: boolean;
+    /** The order staggered point geoms enter in. Bars and slices always enter in visual order. */
+    staggerOrder: IntroStaggerOrder;
+    /** Total geom count across all layers above which the entrance is skipped entirely. */
+    maxAnimatedGeoms: number;
+}
+
+/** Props for the Legend slot, overridable via `slots.Legend` on `GraphRenderer`. */
+export declare interface LegendSlotProps {
+    formattedLegends: FormattedLegend[];
+    rects: Partial<Record<LayoutEdge, Rect>>;
+    textScale: number;
+}
+
+/** Scales the color's HSL lightness up by `amount` (0–1). */
+export declare const lightenCss: (colorString: string, amount: number) => string;
+
+/** vanilla-extract class that binds the light token values; the default theme. */
+export declare const lightTheme: string;
 
 /**
- * Plugin shape for geoms that don't compute an overlay anchor — either `'observation-rerender'`
- * geoms (matched rows re-render in place) or geoms that opt out of highlighting entirely
- * (`null` strategy). The renderer never asks these plugins for an anchor, so the property is forbidden.
+ * The element font tokens JS measurement reproduces. Overridden structurally
+ * ({@link FontTokenOverride}); the CSS variable's shorthand is serialized from the same object
+ * measurement reads, so paint and layout move together.
  */
-declare interface NoOverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
-    getOverlayAnchor?: never;
-}
+export declare type MeasuredFontTokenKey = 'fontDataLabel' | 'fontStackTotal' | 'fontCategoryLabel' | 'fontTickLabel' | 'fontAxisLabel' | 'fontLegendLabel' | 'fontGoalLineLabel';
 
 /**
  * Anchor point in normalized [0,1] coord-space where a highlight overlay marker
@@ -432,88 +857,140 @@ export declare interface OverlayAnchor {
     y: number;
 }
 
-declare interface OverlayAnchorGeomPlugin<G extends string, C extends CoordKind, S extends GeomHighlightStrategy, TParams> extends GeomPluginBase<G, C, S, TParams> {
-    /** Returns the panel-space anchor for a matched observation. */
-    getOverlayAnchor: (input: OverlayAnchorInput<G, C, TParams>) => OverlayAnchor | null;
-}
-
-export declare interface OverlayAnchorInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
-    layer: CompiledLayerFor<G, TParams>;
+declare interface OverlayAnchorInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    layer: CompiledLayerOf<G>;
     coordSystem: CoordSystemFor<C>;
     observation: Observation;
 }
 
-export { PanelHitTester }
-
 /**
- * Portals an interactive overlay to `document.body`, fixed over the given panel rect at the documented
- * top `z-index`. Owns only the placement and chrome; the simulation canvas it wraps paints inside. Sized
- * to the rect with `pointerEvents: 'none'` so gaps fall through to the chart — the overlay's own marks
- * re-enable pointer events to capture drags.
+ * Drops the selected targets `spec` no longer holds, and hands back the same list when it holds all
+ * of them — a selection that survived a command must not churn its subscribers.
+ *
+ * Validated against the spec rather than compiled output: the compiler silently drops annotations it
+ * cannot place, and a target whose annotation failed to resolve has to stay selected for the user to
+ * be able to repair it.
  */
-export declare function PanelOverlayPortal({ rect, children }: {
-    rect: PanelScreenRect;
-    children: ReactNode;
-}): ReactNode;
+export declare const pruneSelection: (selection: readonly EditTarget[], spec: Spec) => readonly EditTarget[];
 
-/** The panel's on-screen rectangle in page-relative pixels — the frame a portalled overlay aligns to. */
-export declare interface PanelScreenRect {
-    left: number;
-    top: number;
+export { RenderHitTester }
+
+/** Fires on each deduped size change — the shape of `GraphRenderer`'s `onResize` callback. */
+export declare type ResizeObserverOnResize = (state: ResizeObserverState) => void;
+
+/** The observed element's content-box size in CSS pixels, rounded to integers. */
+export declare interface ResizeObserverState {
     width: number;
     height: number;
+    /** True until the first ResizeObserver measurement lands. */
+    isDefault: boolean;
 }
 
+/** Frame-size ladder: hidden below 120×80, mini below 200 wide (or when variant is mini). */
+export declare const resolveBrandMarkVisual: (enabled: boolean, frameSize: {
+    width: number;
+    height: number;
+}, variant?: BrandMarkVariant) => BrandMarkVisual;
+
 /**
- * Walks a kind-tagged geom-layout dataset (the output of `createMarkTable`), yielding each observation paired
- * with its discriminant `kind`. The render half switches on `kind` to build its per-kind marks, instead
- * of re-reading the kind column inline in every plugin. `Kind` narrows the discriminant to the geom's own
- * union (e.g. `'node' | 'link'`) for an exhaustive switch.
+ * A render contract with its resolved geom name attached — the shape the per-provider resolver returns
+ * and every render site consumes. Both a built-in `GeomRenderer` and a custom {@link GeomRendererDefinition}
+ * conform to it, so the consumers paint built-ins and customs through one type.
  */
-export declare function partitionByKind<Kind extends string = string>(data: Iterable<Observation>, kindColumn: string): Generator<{
-    kind: Kind;
-    observation: Observation;
-}>;
+export declare interface ResolvedGeomRenderer extends GeomRenderContract {
+    /** The geom name this renderer paints — the resolver dispatches on it. */
+    geom: string;
+}
 
-/** The compiled-layer params a plugin's handlers see — built-ins default from the geom name; a custom geom supplies its own. */
-declare type PluginParams<G extends string> = CompiledLayerFor<G>['params'];
+/** An element's on-screen rect in client coordinates — what a fixed-position overlay aligns to. */
+export declare interface ScreenRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
 
-/**
- * Hover-overlay dot drawn at the primary hit's `(x, y)`: colored disc with a thicker white
- * border and an outer white ring offset by a 1px gap. Radius is data-driven so bubble charts
- * whose size channel carries data don't distort under hover.
- */
-export declare const PrimaryDot: ({ hit, ...rest }: PrimaryDotProps) => JSX.Element;
+declare interface SelectionSlice {
+    /**
+     * The {@link EditTarget}s the graph holds selected. A list even though nothing selects more than
+     * one target: widening it later would break the handle, the panel contract and every consumer at
+     * once.
+     */
+    selection: readonly EditTarget[];
+}
 
-declare interface PrimaryDotProps {
-    hit: HoverHit;
-    'data-testid'?: string;
+/** The vanilla zustand store `GraphProvider` holds; consumers read it via `useGraphSelection`. */
+export declare type SelectionStore = ReturnType<typeof createSelectionStore>;
+
+declare interface SelectionStoreActions {
+    setSelection: (next: readonly EditTarget[]) => void;
+    clearSelection: () => void;
 }
 
-export declare type ResizeObserverOnResize = (state: ResizeObserverState) => void;
+/** State of the selection store: what the graph holds selected plus the actions replacing it. */
+export declare type SelectionStoreState = SelectionSlice & SelectionStoreActions;
 
-export declare interface ResizeObserverState {
-    width: number;
-    height: number;
-    /** True until the first ResizeObserver measurement lands. */
-    isDefault: boolean;
+/**
+ * Passed as the second argument to a layout-coupled slot's `measure`, so it can size its band from
+ * real text metrics — the same Canvas-backed measurer the built-in measurers use — rather than
+ * constructing its own. A `measure` whose size is unrelated to text can ignore it.
+ */
+export declare interface SlotMeasureContext {
+    /** Measures a string at a given font; returns `{ width, height, ascent, descent }` in CSS pixels. */
+    measureText: TextMeasurer['measureText'];
+    /** Active text-scale multiplier; multiply an em size by this to get the pixel size to measure at. */
+    textScale: number;
 }
 
-export { ResolvedTarget }
+/**
+ * A layout-coupled slot: the region's `render` paired with the `measure` the layout uses to reserve
+ * its space. `measure` mirrors the matching `LayoutMeasurer` method, so paint and reserved space can't
+ * disagree. Give it a stable reference — a `measure` whose identity changes each render takes effect on
+ * the next paint but doesn't retrigger layout.
+ */
+export declare interface SlotOverride<Props, Measure> {
+    /** The component that paints the region. */
+    render: ComponentType<Props>;
+    /**
+     * Returns the region's reserved size. Receives the region's formatted data plus a
+     * {@link SlotMeasureContext} (`measureText`, `textScale`) for sizing from real text metrics.
+     */
+    measure: Measure;
+}
 
 /**
- * Shared shape glyph used by both the tooltip and the legend.
+ * The vocabulary of legend/tooltip/headline marks the {@link Swatch} can paint. A geom picks the one
+ * that best evokes its on-canvas mark via `swatchShape` on its render contract (see
+ * {@link GeomRenderContract}); it is a render concern, so the engine never resolves it.
+ *
+ * - `square` — a filled rect (bars)
+ * - `line` — a horizontal stroke (lines)
+ * - `area` — a filled region with a stroke accent (areas)
+ * - `circle` — a filled dot (points)
+ * - `slice` — a pie / donut wedge (polar bars)
  */
-export declare const Swatch: ({ shape, color, lineType, width, height, }: SwatchProps) => JSX.Element;
+export declare type SwatchShape = 'square' | 'line' | 'circle' | 'area' | 'slice';
 
-declare interface SwatchProps {
+/**
+ * Props for the Swatch slot (`slots.Swatch` on `GraphRenderer`). An override must paint inside the
+ * `width` × `height` box it receives.
+ *
+ * Switch on `shape`, `surface` or `label` and delegate the rest to
+ * {@link DefaultSwatch}.
+ */
+export declare interface SwatchSlotProps {
     shape: SwatchShape;
     color: string;
+    surface: SwatchSurface;
+    label?: string;
     lineType?: LineStyleType;
     width?: number;
     height?: number;
 }
 
+/** The UI surface a swatch is painted on. Lets a Swatch slot restyle one surface and delegate the rest. */
+export declare type SwatchSurface = 'legend' | 'tooltip' | 'headline' | 'callout' | 'rule-label';
+
 /**
  * Creates a font-ready, cached text measurer and shares it with descendants via context.
  * Renders nothing until the measurer resolves, so consumers reading the context always
@@ -538,171 +1015,215 @@ declare interface TextMeasurerProviderProps {
     measurer?: TextMeasurer;
 }
 
+/** The name of a single theme token. */
 export declare type ThemeKey = keyof ThemeValues;
 
-export declare type ThemeOverrides = Partial<ThemeValues>;
+/**
+ * A partial set of token values layered over a base theme — the shape of the `themeOverrides`
+ * prop. Measured font tokens take a {@link FontTokenOverride}; every other token takes its CSS
+ * string value.
+ */
+export declare type ThemeOverrides = Partial<Omit<ThemeValues, MeasuredFontTokenKey>> & {
+    [Key in MeasuredFontTokenKey]?: FontTokenOverride;
+};
 
-export declare const ThemeProvider: ({ theme, themeOverrides, appearance, children }: ThemeProviderProps) => JSX.Element;
+/** Resolves the base theme plus per-graph `themeOverrides` into token values and publishes them to the subtree. */
+export declare const ThemeProvider: ({ colorScheme, themeOverrides, appearance, children }: ThemeProviderProps) => JSX.Element;
 
 declare interface ThemeProviderProps {
     appearance: AppearanceConfig;
-    theme: GraphTheme;
+    colorScheme: ColorScheme;
     themeOverrides?: ThemeOverrides;
     children: ReactNode;
 }
 
+/** Every theme token mapped to its resolved CSS string value. */
 export declare type ThemeValues = Record<keyof typeof vars, string>;
 
 /**
- * The default tooltip body — the optional header and one row per hovered observation, with the
- * in-place primary-row highlight. Presentational and engine-decoupled: it renders a
- * {@link TooltipContent} and nothing else, so the built-in `Tooltip` and a custom geom's
- * `renderTooltip` paint the same rows. The positioned, themed card around it stays the renderer's.
+ * Where a pinned callout asks the tooltip to anchor: the marker point in client coordinates, plus
+ * the direction the mini sits, so the tooltip expands over the mini the way it was placed.
  */
-export declare const TooltipBody: ({ content }: TooltipBodyProps) => JSX.Element;
-
-declare interface TooltipBodyProps {
-    content: TooltipContent;
-}
-
-/** Page-relative cursor position the tooltip anchors to. `null` when the pointer is outside the chart. */
-export declare interface TooltipCursor {
-    clientX: number;
-    clientY: number;
+declare interface TooltipAnchor {
+    x: number;
+    y: number;
+    placement: AnchorPlacement;
+    /**
+     * Annotation the anchor belongs to, so the tooltip can resolve a comment's text by id. Absent when
+     * a geom overlay anchors to the cursor instead.
+     */
+    annotationId?: string;
 }
 
-/**
- * Input a plugin's {@link GeomPluginBase.renderTooltip} receives when one of its observations is the
- * primary hit. `content` is the body the built-in tooltip would render — feed it to `TooltipBody` to
- * reproduce the default — while `primary.observation` carries the geom's own columns for a bespoke
- * layout. The card around the body (positioning, theme) stays the renderer's.
- */
-export declare interface TooltipRenderInput<G extends string = GeomName, C extends CoordKind = CoordKind, TParams = PluginParams<G>> {
+/** Props for the Tooltip slot, overridable via `slots.Tooltip` on `GraphRenderer`. Positioning stays built in. */
+export declare interface TooltipSlotProps {
+    /** Render-ready tooltip body, already formatted by the viz-engine runtime. */
     content: TooltipContent;
-    layer: CompiledLayerFor<G, TParams>;
-    coordSystem: CoordSystemFor<C>;
-    primary: HoverHit;
-    group: HoverHit[];
-    related: ReadonlyMap<string, HoverHit[]>;
 }
 
 /**
- * One tooltip row — swatch, label, value, with the optional in-place highlight. Exposed so a custom
- * geom's `renderTooltip` can map `content.rows` itself and interleave its own content between rows,
- * rather than rendering the whole {@link TooltipBody} as an opaque block.
+ * A nested SVG that establishes a `[0, 1]` unit coordinate space (top-left origin) stretched to fill
+ * the geom panel. A layout geom paints its geometry in raw unit coords so paint and hit-test never re-project against each
+ * other. `preserveAspectRatio="none"` maps the unit square onto the (usually non-square) panel exactly.
  */
-export declare const TooltipRowView: ({ row, shouldHighlight }: TooltipRowViewProps) => JSX.Element;
+export declare const UnitSpaceSvg: ({ children, ...rest }: UnitSpaceSvgProps) => ReactNode;
 
-declare interface TooltipRowViewProps {
-    row: TooltipRow;
-    shouldHighlight: boolean;
+declare interface UnitSpaceSvgProps extends Omit<SVGProps<SVGSVGElement>, 'viewBox' | 'preserveAspectRatio'> {
+    children: ReactNode;
 }
 
-export declare const toPercent: (value: number) => string;
-
 /**
- * Converts a normalized [0,1] x-coordinate to viewBox coordinate (identity transform).
- * Used inside nested SVGs with viewBox="0 0 1 1".
+ * Subscribes to a derived slice of the compiled spec. The subscription only fires when the
+ * selector's result changes by reference, so combined with the compiler's per-stage memoization
+ * this skips re-renders whenever the selected slice is unchanged.
+ *
+ * @example
+ * ```ts
+ * const layers = useCompiledSelector((compiled) => compiled.layers);
+ * const xAxis = useCompiledSelector((compiled) => compiled.guides.axes[0]);
+ * ```
  */
-export declare function toViewBoxX(normalized: number): number;
+export declare const useCompiledSelector: <Selected>(selector: (compiled: CompiledSpec) => Selected) => Selected;
 
 /**
- * Converts a normalized [0,1] y-coordinate to viewBox coordinate (Y-inverted).
- * SVG y=0 is at the top, but data y=0 is at the bottom, so we invert.
- * Used inside nested SVGs with viewBox="0 0 1 1".
+ * Tracks an element's on-screen rect, so that a fixed-position overlay can sit exactly over it in pixel
+ * space. `screenRect` is `null` until the first measurement lands, and drops back to `null` whenever the
+ * element collapses to nothing.
+ *
+ * The element's own size changes go through the shared {@link useResizeObserver} lifecycle; this hook adds
+ * the screen-position concerns the observer can't see — viewport scroll/resize move the element's screen
+ * position without resizing it. Every trigger is coalesced into at most one `getBoundingClientRect` per
+ * animation frame, so a burst of scroll events forces a single reflow rather than one per event. Only a
+ * changed rect updates state, so a settled overlay does not re-render every frame.
  */
-export declare function toViewBoxY(normalized: number): number;
+export declare function useElementScreenRect<T extends Element = SVGRectElement>(): {
+    measureRef: (node: T | null) => void;
+    screenRect: ScreenRect | null;
+};
 
 /**
- * An `<svg>` preset for painting geom-layout geometry in panel `[0,1]` unit space: `viewBox="0 0 1 1"`,
- * `preserveAspectRatio="none"` (so unit coordinates stretch to fill the panel exactly, the way a bar
- * chart's bars do), and `overflow: visible`.
+ * Registers a layout geom's render-side hit tester so a `'render-hit-test'` layer inherits central hover
+ * and the built-in tooltip — the path `bar` takes — with no pointer overlay of its own. The pull path.
  *
- * Chrome gotcha (documented once here, so geoms don't rediscover it): with a sub-unit `viewBox`, native
- * SVG fill hit-testing is unreliable at this scale — which is why geom-layout geoms answer a numeric
- * `useGeomHitTest` query instead of relying on pointer events landing on these shapes. Paint here; hit-test
- * through the engine.
+ * The cursor passed to the tester is panel-local `[0, 1]`, top-left origin — the frame the geom paints in.
  */
-export declare const UnitSpaceSvg: ({ children, style, ...rest }: SVGProps<SVGSVGElement>) => ReactNode;
+export declare function useGeomHitTest(layerId: string, tester: RenderHitTester): void;
 
 /**
- * Returns an `index → colour` resolver over the chart's default categorical palette — the same
- * `DEFAULT_COLOR_PALETTE` the compiler bakes into a colour-encoded layer — so a custom geom that
- * assigns its own colour indices draws from the chart's palette instead of inventing a private one.
- * Colours therefore match what a sibling layer's colour scale would produce, and follow the engine's
- * palette rather than a hardcoded array.
+ * The push half of the render-hit-test keystone, for a geom whose geometry keeps changing after it is
+ * drawn (a live simulation) and so owns its own pointer surface above the central capture layer. The
+ * geom's pointer handlers call the returned setter with the hovered observation's `identityKey`; the
+ * engine resolves it through the same `byKey` lookup the pull path uses, so the geom inherits the tooltip
+ * and `renderHover`. Since the overlay intercepts the pointer events, the tooltip is anchored at the
+ * supplied cursor. Pass `null` to clear. Geoms with geometry fixed once drawn use `useGeomHitTest`.
  *
- * Out of scope (ADR-034 open question #4): declaring a colour *aesthetic* with its own scale + legend,
- * or honouring a per-spec custom palette. This primitive only ensures the colours match the default.
+ * Escape hatch: an interactive geom should instead declare an overlay-hosted `render`
+ * (`{ fn, options: { overlay: true } }`), which the renderer portals into a screen-aligned overlay and
+ * hands a ready `pushHover` via `input.overlay`. Reach for this hook only when that form is not enough.
  */
-export declare function useCategoricalColor(): (index: number) => string;
+export declare function useGeomHover(layerId: string): GeomHoverPush;
 
 /**
- * Subscribes to a derived slice of the compiled spec. The subscription only fires when the
- * selector's result changes by reference, so combined with the compiler's per-stage memoization
- * this skips re-renders whenever the selected slice is unchanged.
+ * Returns the graph's command controls.
  *
  * @example
- * ```ts
- * const layers = useCompiledSelector((compiled) => compiled.layers);
- * const xAxis = useCompiledSelector((compiled) => compiled.guides.axes[0]);
+ * ```tsx
+ * const { dispatch, seal } = useGraphCommands();
+ *
+ * const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+ *    const command = new SetAppearanceCornerRadiusCommand({ cornerRadius: event.target.valueAsNumber });
+ *    dispatch(command, { transient: true });
+ * };
+ *
+ * const handlePointerUp = () => seal();
+ *
+ * <input type="range" onChange={handleChange} onPointerUp={handlePointerUp}
+ * />
  * ```
  */
-export declare const useCompiledSelector: <Selected>(selector: (compiled: CompiledSpec) => Selected) => Selected;
+export declare const useGraphCommands: () => GraphCommands;
 
 /**
- * Registers a geom-layout geom's render-side hit-test for its layer, so the central hover engine routes
- * the cursor to it — the geom inherits the built-in hover, tooltip, and (in time) accessibility
- * instead of hand-rolling a pointer overlay. The geom declares `spatialKind: 'render-hit-test'`; this
- * hook supplies the matching closure.
+ * The graph a surface edits: the handle it was given, or one synthesized from the `<GraphProvider>`
+ * it sits inside. An explicit handle wins, so a surface nested inside one chart can still edit
+ * another. Returns `null` for a surface that is neither.
  *
- * The `tester` receives the cursor in panel `[0, 1]` with a top-left origin (the frame the geom
- * paints in) and returns the declared identity key of the observation under it, or `null`. It may
- * close over freshly computed geometry each render — a stable wrapper reads the latest through a ref,
- * so the registration effect runs once per layer rather than every render.
+ * A host writing its own editing UI needs this and nothing else from us, which is why it sits here
+ * rather than beside the panel: reaching a chart is not itself an editing concern.
  */
-export declare function useGeomHitTest(layerId: string, tester: PanelHitTester): void;
+export declare const useGraphHandle: (handle?: GraphHandle) => GraphHandle | null;
 
 /**
- * The push counterpart to `useGeomHitTest`, for a geom-layout geom that owns its own pointer surface — a
- * live simulation whose interactive overlay intercepts pointer events before the central capture
- * layer sees them, so the engine cannot pull a hit. The geom already knows which observation is under
- * the cursor and pushes its declared identity key; the engine resolves it to the same unified
- * `HoverState` the pull path produces, and the cursor is forwarded so the central tooltip tracks.
+ * Subscribes to the graph's undo history. Every command that reaches the chart — a renderer's own
+ * inline edit, a host panel's dispatch, an agent's streamed command — is undoable through it.
  *
- * Returns a stable `setHovered(key, cursor?)`: a key with the page-relative cursor opens the tooltip
- * on that observation; `null` clears it.
+ * @example
+ * ```tsx
+ * const { undo, canUndo, undoDescription } = useGraphHistory();
+ * <button disabled={!canUndo} title={undoDescription ?? undefined} onClick={undo}>Undo</button>
+ * ```
  */
-export declare function useGeomHover(layerId: string): (key: string | null, cursor?: TooltipCursor) => void;
-
-export declare const useGraphCommandDispatcher: () => ((command: Command) => void);
+export declare const useGraphHistory: () => GraphHistory;
 
 /**
- * Subscribe to a slice of the hover state from inside a `HoverProvider`.
+ * Binds ⌘/Ctrl+Z, ⌘/Ctrl+Shift+Z and Ctrl+Y to a graph's undo history for as long as the calling
+ * component is mounted, driving the {@link GraphHandle} a `<GraphProvider handleRef>` fills.
+ *
+ * Going through the ref rather than the context means it can be called from wherever the app's key
+ * handling lives — typically above the provider, out of reach of the hooks.
+ *
+ * @example
+ * ```tsx
+ * const EditableChart = () => {
+ *   const handleRef = useRef<GraphHandle>(null);
+ *   useGraphHistoryShortcuts(handleRef);
+ *
+ *   return (
+ *     <GraphProvider input={input} data={data} handleRef={handleRef}>
+ *       <GraphRenderer mode="editable" />
+ *     </GraphProvider>
+ *   );
+ * };
+ * ```
+ *
+ * A chord the app or an inline editor already handled is left alone, as is one typed into a text
+ * control and one the chart declines — nothing to step, or an older spec the loaded data can no
+ * longer render. An app-level undo sharing the page keeps those.
  */
-export declare function useHoverState<T>(selector: (state: HoverStoreState) => T): T;
+export declare const useGraphHistoryShortcuts: (handleRef: RefObject<GraphHandle | null>, options?: GraphHistoryShortcutsOptions) => void;
 
 /**
- * Tracks the on-screen rect of the element the returned `ref` is attached to, across container resize and
- * page scroll. Only a live-simulation geom needs this (ADR-034 decision 4): it paints and hit-tests
- * render-side every frame, so its interactive overlay must sit above the chart in pixel space. Every other
- * geom-layout geom routes hover through the engine (decision 2) and never tracks a screen rect.
+ * Subscribes to what the graph holds selected, from inside a `<GraphProvider>`. The store is
+ * per-chart and shared with {@link GraphHandle}, so a surface outside the tree and one inside it
+ * always agree on what is selected. A surface outside the tree writes through the handle's
+ * `setSelection`; the canvas overlay writes to the same store off the context.
+ *
+ * @example
+ * ```tsx
+ * const selection = useGraphSelection();
+ * const selected = selection.length === 1 ? selection[0] : null;
+ * ```
  */
-export declare function usePanelScreenRect(): {
-    ref: RefCallback<Element>;
-    rect: PanelScreenRect | null;
-};
+export declare const useGraphSelection: () => readonly EditTarget[];
 
 /**
- * Animates SVG path transitions using `d3-interpolate-path` for smooth morphing
- * when data points are added or removed (Framer Motion doesn't support this natively).
+ * The graph's compiled spec, re-read whenever the graph changes, or `null` before its first
+ * successful compile.
  *
- * Based on: https://github.com/framer/motion/issues/451#issuecomment-761302824
+ * Returns the whole spec: `useSyncExternalStore` compares snapshots by reference, so a selector
+ * building a fresh object per call would re-render forever. Derive slices at the call site.
+ */
+export declare const useHandleCompiled: (handle: GraphHandle) => CompiledSpec | null;
+
+/**
+ * Subscribe to a slice of the hover state from inside a `HoverProvider`.
  */
-export declare const useSvgPathMorph: (pathDefinition: string, config: AnimationPlaybackOptions) => MotionValue<string>;
+export declare function useHoverState<T>(selector: (state: HoverStoreState) => T): T;
 
+/** Returns the {@link TextMeasurer} from context; throws outside a `<TextMeasurerProvider>`. */
 export declare const useTextMeasurer: () => TextMeasurer;
 
+/** CSS custom-property references for every theme token; read at paint sites as `vars.tooltipBackground`, etc. */
 export declare const vars: {
     white: `var(--${string})`;
     black: `var(--${string})`;
@@ -751,9 +1272,6 @@ export declare const vars: {
     graphBackground: `var(--${string})`;
     gridLineColor: `var(--${string})`;
     originLineColor: `var(--${string})`;
-    targetLineColor: `var(--${string})`;
-    targetLineMarkerColor: `var(--${string})`;
-    targetLineLabelTextColor: `var(--${string})`;
     legendBackground: `var(--${string})`;
     legendBorderColor: `var(--${string})`;
     legendFocusOutlineColor: `var(--${string})`;
@@ -769,9 +1287,34 @@ export declare const vars: {
     arrowAnnotationStickerOutlineColor: `var(--${string})`;
     arrowAnnotationStickerOutlineColorInverse: `var(--${string})`;
     annotationFrameBorderColor: `var(--${string})`;
-    annotationMenuTriggerIconColor: `var(--${string})`;
+    editMenuTriggerIconColor: `var(--${string})`;
     heatmapEmptyTileBackground: `var(--${string})`;
     dataLabelOutsideBackground: `var(--${string})`;
+    dataLabelTextColor: `var(--${string})`;
+    dataLabelInsideTextColor: `var(--${string})`;
+    stackTotalTextColor: `var(--${string})`;
+    stackTotalBackground: `var(--${string})`;
+    stackTotalStroke: `var(--${string})`;
+    gridLineWidth: `var(--${string})`;
+    gridLineDash: `var(--${string})`;
+    gridLineDotted: `var(--${string})`;
+    tooltipBorderRadius: `var(--${string})`;
+    tooltipBorderWidth: `var(--${string})`;
+    tooltipPaddingBlock: `var(--${string})`;
+    tooltipPaddingInline: `var(--${string})`;
+    tooltipRowGap: `var(--${string})`;
+    tooltipShadow: `var(--${string})`;
+    editorControlHeight: `var(--${string})`;
+    tickLabelOffset: `var(--${string})`;
+    legendItemGap: `var(--${string})`;
+    legendSwatchGap: `var(--${string})`;
+    legendSwatchWidth: `var(--${string})`;
+    legendSwatchHeight: `var(--${string})`;
+    legendPillPaddingInline: `var(--${string})`;
+    legendPillPaddingBlock: `var(--${string})`;
+    legendPillBorderWidth: `var(--${string})`;
+    headlineRowGap: `var(--${string})`;
+    headlineItemGap: `var(--${string})`;
     canvasDefault: `var(--${string})`;
     canvasBlue: `var(--${string})`;
     canvasCyan: `var(--${string})`;
@@ -800,6 +1343,7 @@ export declare const vars: {
     zIndexToolbar: `var(--${string})`;
     zIndexToolbarTooltip: `var(--${string})`;
     zIndexToolbarPopover: `var(--${string})`;
+    zIndexEditorPopover: `var(--${string})`;
     toolbarBackgroundColor: `var(--${string})`;
     toolbarButtonBackgroundColor: `var(--${string})`;
     toolbarButtonBackgroundColorHovered: `var(--${string})`;
@@ -813,10 +1357,6 @@ export declare const vars: {
     tooltipPrimaryRowColor: `var(--${string})`;
     hoverGuideLineColor: `var(--${string})`;
     hoverGuideFillColor: `var(--${string})`;
-    hoveredBarBorderColor: `var(--${string})`;
-    hoveredPointRingColor: `var(--${string})`;
-    pointStrokeColor: `var(--${string})`;
-    stackedBarHoverBorderColor: `var(--${string})`;
     fontFamilyDefault: `var(--${string})`;
     fontFamilyHeading: `var(--${string})`;
     fontWeightRegular: `var(--${string})`;
@@ -850,6 +1390,7 @@ export declare const vars: {
     fontAxisLabel: `var(--${string})`;
     fontDataLabel: `var(--${string})`;
     fontStackTotal: `var(--${string})`;
+    fontCategoryLabel: `var(--${string})`;
     fontLegendLabel: `var(--${string})`;
     fontSeriesLabel: `var(--${string})`;
     fontTooltipLabel: `var(--${string})`;
@@ -895,6 +1436,12 @@ export declare const vars: {
     fontTextEditorLink: `var(--${string})`;
     fontHighlightModeTitle: `var(--${string})`;
     fontHighlightModeSubtitle: `var(--${string})`;
+    fontEditorControlLabel: `var(--${string})`;
+    fontEditorControlValue: `var(--${string})`;
+    fontEditorSectionTitle: `var(--${string})`;
+    fontEditorCaption: `var(--${string})`;
 };
 
+export { VizDiagnostic }
+
 export { }