insomni-plot 0.1.0-alpha.0

package/src/grammar/mount.ts

@@ -0,0 +1,2112 @@
+// ---------------------------------------------------------------------------
+// WebGPU mount — owns the renderer, atlas, layers, and rAF loop
+// ---------------------------------------------------------------------------
+// `chart.mount(canvas, opts?)` returns a `MountedPlot<T>` that owns the
+// per-canvas rendering loop (Renderer2D, GlyphAtlas, three layers, RAF tick,
+// ResizeObserver, visibility pause). The intent is that 90% of users never
+// touch any of the lower-level pieces. The remaining 10% can:
+//
+//   - bring their own Renderer2D / GlyphAtlas / layers (`opts.renderer`, etc.)
+//   - drive sizing manually (`opts.width`/`height`, `opts.autoResize: false`)
+//   - swap the spec at runtime (`handle.update(...)`) or rebuild via a closure
+//   - reach into `handle.renderer` / `handle.atlas` / `handle.axisLayer` etc.
+//   - opt out of the rAF loop entirely (`opts.autoFrame: false`) and call
+//     `handle.update()` themselves from a host loop
+//
+// The mount is sync. If you need to bootstrap a device, do it once with
+// `await initGPU()` and pass the result in.
+
+import {
+  type CacheHint,
+  type Color,
+  createFrame,
+  createInteractionManager,
+  createInvalidator,
+  createLayer,
+  createSVGRenderer,
+  createRenderer,
+  type Frame,
+  type FrameRect,
+  type FrameTiming,
+  type GlyphAtlas,
+  type InteractionManager,
+  type Invalidator,
+  type Layer,
+  type Layer as V1Layer,
+  loadSystemFont,
+  SdfGlyphAtlas,
+} from "insomni";
+import type {
+  BrushConfig,
+  Chart,
+  ContextMenuConfig,
+  CrosshairConfig,
+  InteractionsConfig,
+  LegendInteractionConfig,
+  MountedPlot,
+  MountPlotOptions,
+  SelectionConfig,
+  TooltipConfig,
+  TransitionsConfig,
+} from "./chart.ts";
+import { createGrammarTransitions, type GrammarTransitions } from "./interactions/transitions.ts";
+import { resolveMotion } from "./theme.ts";
+import {
+  DEFAULT_CHART_HEIGHT,
+  DEFAULT_CHART_WIDTH,
+  DEFAULT_PAN_BOUNDS,
+  DEFAULT_Y_FIT_PADDING,
+} from "./constants.ts";
+import type { HoveredHit } from "./geoms/types.ts";
+import { createGrammarBrush, type GrammarBrush } from "./interactions/brush.ts";
+import { createGrammarCrosshair, type GrammarCrosshair } from "./interactions/crosshair.ts";
+import { createGrammarHitLayer, type GrammarHitLayer } from "./interactions/hit-layer.ts";
+import { createGrammarLegend, type GrammarLegend } from "./interactions/legend.ts";
+import { createGrammarContextMenu, type GrammarContextMenu } from "./interactions/menu.ts";
+import { createGrammarSelection, type GrammarSelection } from "./interactions/selection.ts";
+import {
+  createSeriesReadout,
+  type AttachedSeriesReadout,
+  type AttachSeriesReadoutOptions,
+  type SeriesReadoutInternal,
+} from "./interactions/series-readout.ts";
+import { createGrammarTooltip, type GrammarTooltip } from "./interactions/tooltip.ts";
+import { currentData, runPipeline, type ChartConfig } from "./pipeline.ts";
+import {
+  attachRangePresets as attachRangePresetsHelper,
+  type AttachedRangePresets,
+  type AttachRangePresetsOptions,
+} from "./attach-presets.ts";
+import {
+  createAttachedBrush,
+  type AttachBrushOptions,
+  type AttachedBrush,
+  type AttachedBrushInternal,
+} from "./attach-brush.ts";
+import { createDataViewport, type DataViewport } from "../viewport.ts";
+import { bindDataViewport, type DataViewportBinding } from "../interactions.ts";
+import type { Coord } from "./coord.ts";
+import type { PanZoomConfig } from "./chart.ts";
+import { resolveAes, type Aes } from "./aes.ts";
+import { shallowObjectEqual } from "./equality.ts";
+import type { DataPanBoundsOptions } from "../viewport.ts";
+import type { AxisSelection } from "../interactions.ts";
+import { readNumericDomain, readContinuousType, type PositionScaleOptions } from "./scales.ts";
+import { isSignal, signal, type Signal } from "insomni/reactivity";
+import { recordCpu, recordGpu } from "./profiling.ts";
+import { GPU_DIM_GEOM_KINDS, type EmphasisResolver } from "./geoms/emphasis.ts";
+import { createEmphasisDriver, type EmphasisDriver } from "./emphasis-driver.ts";
+
+// ---------------------------------------------------------------------------
+// Render-orchestration contract (P5 — core z-aware cache + damage migration)
+// ---------------------------------------------------------------------------
+// Plot is a thin DAMAGE SOURCE for the core renderer. It no longer runs its own
+// CPU-bake state machine; instead it emits ordered layers (`zIndex` bands) with
+// `cache` HINTS and lets the core's per-frame cache policy decide bake-vs-live,
+// composite order, and damage tracking. The behavior contract:
+//
+//   • PAN / ZOOM (interaction in flight): every static layer's `cache` is
+//     flipped to "never" (see `applyInteractionCacheHints`). A pan recompiles
+//     the geoms each frame → the layer's pack version changes → an "auto" bake
+//     would re-bake (texture create + bake pass) EVERY frame, which is strictly
+//     worse than drawing live. So during a gesture all layers draw LIVE and each
+//     frame is a cheap full re-raster.
+//   • SETTLE (gesture ends): hints restore to "auto"; the core's policy bakes
+//     the now-static stack ONCE on the next full frame, after which pan-idle
+//     hovers ride the cached fast path. A (re)bake forces that frame full
+//     automatically (core contract) so there is no stale-composite window.
+//   • HOVER tooltip / crosshair / point-halo: overlay-only change → `drawOverlay`
+//     re-emits the overlay layer and issues `render(currentLayers(), { regions })`
+//     — a scissored, OIT-aware partial repaint of just the damaged rect(s). The
+//     overlay layer is `cache:"never"` and sits in the trailing z-band, so the
+//     baked marks/axis/hud composite UNDER it correctly (core T-ZBAKE z-runs).
+//   • DATA / SCALE / VIEW change: a normal `render(currentLayers(), { viewKey })`
+//     with no regions → full frame by construction. `viewKey` folds the visible
+//     domain so a pan-driven domain shift also forces full (the core's camera
+//     never moves for ui-space layers).
+//
+// Plot NEVER calls `cacheLayer`/`uncacheLayer` and NEVER passes `fullFrame:true`
+// — the core's view fingerprint + force-full-after-bake logic owns that decision.
+// When `partialRedraw` is off, every layer is `cache:"never"` and the renderer
+// is non-persistent (pure-live fallback, byte-equivalent to the classic path).
+
+// `GPU_DIM_GEOM_KINDS` — the set of geom kinds whose dim-others hover treatment
+// rides the core's animated emphasis uniform — now lives in `./geoms/emphasis.ts`
+// alongside the key-namespacing helpers (imported above) so the geom-tagging
+// code and the mount agree on one source of truth.
+
+/**
+ * Internal entry. `chart.mount(canvas, opts)` calls this with its frozen
+ * config + the user-provided mount options.
+ */
+export function mountChart<T>(
+  config: ChartConfig<T>,
+  canvas: HTMLCanvasElement,
+  opts: MountPlotOptions<T> = {},
+): MountedPlot<T> {
+  // -----------------------------------------------------------------------
+  // Resolve external pieces — ownership rules:
+  //   - we only `destroy()` what we created.
+  //   - any of {renderer, atlas, layers} can be brought from outside.
+  //   - if you bring a renderer you also own its lifecycle / setBackground /
+  //     onFrameTiming wiring; we leave them alone.
+  // -----------------------------------------------------------------------
+
+  const ownedRenderer = !opts.renderer;
+  const ownedLayers = !opts.layers;
+
+  // Damage-tracked partial redraw. Only when we own *both* the renderer (so we
+  // can give it a persistent backbuffer) and the layers (so we can bake the
+  // marks layer to a texture). Otherwise it silently degrades to the classic
+  // full-frame path. `partial` gates every persistent-mode branch below;
+  // when false the code path is byte-identical to before.
+  const wantPartial = opts.partialRedraw ?? true;
+  // Warn only when partial redraw was *explicitly* requested but can't run
+  // because the caller brought their own renderer/layers. When it's just the
+  // default, silently degrade to the classic full-frame path (no warning).
+  if (opts.partialRedraw === true && (!ownedRenderer || !ownedLayers)) {
+    console.warn(
+      "insomni-plot: `partialRedraw` requires the mount to own both its renderer and layers; " +
+        "it is ignored when an external `renderer` or `layers` is supplied.",
+    );
+  }
+  const partial = wantPartial && ownedRenderer && ownedLayers;
+
+  // -----------------------------------------------------------------------
+  // Z-bands + cache hints (P5 migration)
+  // -----------------------------------------------------------------------
+  // Explicit flat-z bands make the composite order self-documenting and robust
+  // to `currentLayers()` reordering. Bands leave gaps so caller `extraLayers`
+  // (below/above marks) slot in between without colliding:
+  //   axis = 0, below-geom = 10,11,…, marks = 100, above-geom = 110,111,…,
+  //   hud = 200, overlay = 300.
+  const Z_AXIS = 0;
+  const Z_BELOW_BASE = 10;
+  const Z_MARKS = 100;
+  const Z_ABOVE_BASE = 110;
+  const Z_HUD = 200;
+  const Z_OVERLAY = 300;
+
+  // Cache hint for the STATIC layers (axis / below / marks / above / hud). When
+  // `partial` is off we run pure-live (every layer "never", renderer
+  // non-persistent), byte-equivalent to the classic full-frame path. The
+  // overlay layer is ALWAYS "never": its cursor shapes change every frame and it
+  // must stay live so it composites OVER the baked static stack (trailing z-band
+  // + live → core T-ZBAKE stacks bakes under it). `staticCacheHint` flips to
+  // "never" during a pan/zoom gesture (see `applyInteractionCacheHints`).
+  // `CacheHint` is the public union ("auto"|"always"|"never"), re-exported from
+  // the `insomni` barrel.
+  const staticCacheHint: CacheHint = partial ? "auto" : "never";
+
+  // device source: opts > config. Only required when we have to create a renderer ourselves.
+  const device = opts.device ?? config.device;
+  if (ownedRenderer && !device) {
+    throw new Error(
+      "chart.mount(canvas) needs a `device`. Pass `{ device }` in plot({...}) or in mount opts, " +
+        "or pass an existing `renderer`.",
+    );
+  }
+
+  // DPR — explicit > window. Re-read on every resize tick (DPR can change
+  // when dragging a window between displays).
+  const initialDpr = opts.dpr ?? readDpr();
+
+  // -----------------------------------------------------------------------
+  // Renderer
+  // -----------------------------------------------------------------------
+
+  // v3 `FrameTiming` carries v1 back-compat alias getters (`cpuMs`/`renderNs`/
+  // `computeNs`), so these reads work unchanged. `renderNs`/`computeNs` are
+  // non-null bigints on v3 (no GPU timestamp query — they are CPU analogs).
+  const onFrameTiming = (t: FrameTiming) => {
+    recordCpu("render-cpu", t.cpuMs);
+    recordGpu("render-pass", 0, Number(t.renderNs));
+    recordGpu("compute-passes", 0, Number(t.computeNs));
+    opts.onFrameTiming?.(t);
+  };
+
+  // v3: `createRenderer` auto-assembles shader + pipelines (+ OIT, default on).
+  // `persistent` + `onFrameTiming` live under `config`; the DPR is applied via
+  // `setDpr` below (the renderer never reads `window.devicePixelRatio` itself).
+  const renderer =
+    opts.renderer ??
+    createRenderer(device!, canvas, {
+      dpr: initialDpr,
+      config: { onFrameTiming, persistent: partial },
+    });
+
+  // Background — explicit override > config.background > theme.background.
+  // Only set when we own the renderer; an external renderer is the caller's
+  // responsibility.
+  if (ownedRenderer) {
+    renderer.setBackground(opts.background ?? config.background ?? config.theme.background);
+  }
+
+  // -----------------------------------------------------------------------
+  // Atlas
+  // -----------------------------------------------------------------------
+
+  // v3 externalizes the glyph atlas (D1=Hybrid): the renderer no longer owns a
+  // default font or `atlasFor`. We build an MSDF/SDF atlas from a system font
+  // and hand it to `createLayer({ atlas })`. A caller-supplied `externalAtlas`
+  // is used immediately and short-circuits the system-font load.
+  let atlas: GlyphAtlas | undefined = config.externalAtlas ?? undefined;
+
+  // -----------------------------------------------------------------------
+  // Layers
+  // -----------------------------------------------------------------------
+
+  // When we own the layers and already have an atlas (caller-supplied), mint
+  // them with it up front. Otherwise mint atlas-less layers — shapes render
+  // immediately; text is enabled once the system-font atlas resolves and we
+  // remint below. External layers are used verbatim.
+  let axisLayer =
+    opts.layers?.axis ??
+    createLayer({ space: "ui", atlas, zIndex: Z_AXIS, cache: staticCacheHint, label: "axis" });
+  let marksLayer =
+    opts.layers?.marks ??
+    createLayer({ space: "ui", atlas, zIndex: Z_MARKS, cache: staticCacheHint, label: "marks" });
+  let hudLayer =
+    opts.layers?.hud ??
+    createLayer({ space: "ui", atlas, zIndex: Z_HUD, cache: staticCacheHint, label: "hud" });
+  // Cursor-driven overlays (tooltip / crosshair / brush / menu) live on their
+  // own layer above the hud. It is ALWAYS `cache:"never"`: its cursor shapes
+  // change every overlay frame, so it draws LIVE and — sitting in the trailing
+  // z-band (Z_OVERLAY) above the baked static stack — composites correctly OVER
+  // the baked marks/axis/hud (core T-ZBAKE: leading-run bakes composite UNDER
+  // live geometry). Repainted via `regions` in `drawOverlay` (damage-tracked).
+  // `oitExempt`: the overlay skips the bounded-K OIT A-buffer and draws
+  // post-resolve on top — over dense transparent marks its fragments (appended
+  // last) would otherwise be the first dropped on per-pixel budget overflow,
+  // rendering the tooltip ghost-faint.
+  let overlayLayer =
+    opts.layers?.overlay ??
+    createLayer({
+      space: "ui",
+      atlas,
+      zIndex: Z_OVERLAY,
+      cache: "never",
+      label: "overlay",
+      oitExempt: true,
+    });
+
+  // Default font — `Layer.pushText` requires the layer to carry a glyph atlas.
+  // When we own the layers AND no external atlas was supplied, kick off the
+  // system-font load, build an SDF atlas, and remint the layers with it as soon
+  // as it resolves. External layers / atlas are the caller's responsibility.
+  // `fontReady` gates the first draw. We are ready immediately when we don't own
+  // the layers (caller wired text) or already hold an atlas (external).
+  let fontReady = !ownedLayers || atlas !== undefined;
+  // Declared early so the font-load `.then` can short-circuit when the mount
+  // is destroyed before the promise resolves — otherwise we'd allocate fresh
+  // layers and invalidate the loop on a torn-down chart.
+  let disposed = false;
+  if (ownedLayers && atlas === undefined) {
+    void loadSystemFont("sans-serif").then((font) => {
+      if (disposed) return;
+      atlas = new SdfGlyphAtlas(device!, font);
+      axisLayer = createLayer({
+        space: "ui",
+        atlas,
+        zIndex: Z_AXIS,
+        cache: staticCacheHint,
+        label: "axis",
+      });
+      marksLayer = createLayer({
+        space: "ui",
+        atlas,
+        zIndex: Z_MARKS,
+        cache: staticCacheHint,
+        label: "marks",
+      });
+      hudLayer = createLayer({
+        space: "ui",
+        atlas,
+        zIndex: Z_HUD,
+        cache: staticCacheHint,
+        label: "hud",
+      });
+      overlayLayer = createLayer({
+        space: "ui",
+        atlas,
+        zIndex: Z_OVERLAY,
+        cache: "never",
+        label: "overlay",
+        oitExempt: true,
+      });
+      fontReady = true;
+      inv.invalidate();
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Loop state
+  // -----------------------------------------------------------------------
+
+  const inv: Invalidator = createInvalidator(true);
+
+  // Damage-tracked partial-redraw state (only meaningful when `partial`).
+  //
+  // Dual-flag scheme: `inv.dirty` means "a full frame is needed" — every
+  // existing `inv.invalidate()` keeps that meaning, so the default for any
+  // unclassified change is a (correct) full frame. `overlayDirty` is the
+  // separate, weaker signal that *only* the cursor overlays moved; it drives
+  // the cheap per-rect repaint. A pending full frame always wins.
+  let overlayDirty = false;
+  // Overlay-layer content bounds (CSS px) from the previous frame, so the next
+  // overlay frame can erase the old footprint as well as paint the new one.
+  let lastOverlayRect: FrameRect | null = null;
+  // Pan-tax settle detection (partial mode only). Tracks whether the previous
+  // `tick()` saw an active pan/zoom/fling. When it flips true → false we force
+  // one final `drawFull()` so the now-settled axis/hud/marks layers re-bake
+  // before any cheaper overlay-only frame composites against a live-but-gone
+  // sprite. Drag-end alone fires no `onChange` when fling is disabled, so this
+  // is the only thing guaranteeing the settle re-bake.
+  let wasInteracting = false;
+  // Debug annotation (P5-T1, decision D7) — the caller's INTENT for the next full
+  // frame, surfaced next to the core's own decision in the frame inspector. A
+  // weak classification latch: callers that know their cause (setData/update →
+  // "data-changed", resize → "resize", settle → "settle-rebake") set this before
+  // `inv.invalidate()`; `drawFull` reads it (overridden by "pan-zoom" when a
+  // gesture is live), then resets to "invalidate" for any unclassified change.
+  // Read only on the (already-non-zero-cost) full-frame path; core ignores it
+  // when the probe is disabled, so it is byte-irrelevant to rendering.
+  let pendingFullReason = "invalidate";
+  function requestOverlay(): void {
+    // Classic path has no partial frames — fall back to a normal full redraw.
+    if (partial) overlayDirty = true;
+    else inv.invalidate();
+  }
+  // Invalidator handed to the cursor overlays (tooltip / crosshair / brush /
+  // menu). Inherits everything from `inv` but routes `invalidate()` to an
+  // overlay-only repaint; `dispose()` is a no-op because the mount owns `inv`.
+  const overlayInv: Invalidator = Object.assign(Object.create(inv) as Invalidator, {
+    invalidate: () => requestOverlay(),
+    dispose: () => {},
+  });
+
+  const autoFrame = opts.autoFrame !== false;
+  const pauseOnHidden = opts.pauseOnHidden !== false;
+  const autoResize = opts.autoResize ?? (opts.width === undefined && opts.height === undefined);
+
+  // Working dimensions (CSS pixels).
+  let width = opts.width ?? config.width ?? (canvas.clientWidth || DEFAULT_CHART_WIDTH);
+  let height = opts.height ?? config.height ?? (canvas.clientHeight || DEFAULT_CHART_HEIGHT);
+  let dpr = initialDpr;
+  let backgroundOverride: Color | null = opts.background ?? null;
+
+  // Builder source — user can pass either a static `Chart<T>` (the one this
+  // mount was attached to) or a closure that rebuilds on each invalidation.
+  // We always re-resolve to a `ChartConfig<T>` in the draw path.
+  let activeConfig: ChartConfig<T> = config;
+  let builder: (() => Chart<T>) | null = opts.build ?? null;
+
+  // Reactive data: subscribe if the active config's data is a signal. We
+  // re-resolve this every time activeConfig changes (in `update`).
+  let unsubscribeData: (() => void) | null = null;
+  let dataSnapshot: readonly T[] = currentData(activeConfig.data);
+  function bindDataSignal(): void {
+    unsubscribeData?.();
+    unsubscribeData = null;
+    dataSnapshot = currentData(activeConfig.data);
+    if (isSignal<readonly T[]>(activeConfig.data)) {
+      unsubscribeData = (activeConfig.data as Signal<readonly T[]>).subscribe((next) => {
+        dataSnapshot = next;
+        resetEmphasisForData(); // clear stale index-derived emphasis (Fix C)
+        pendingFullReason = "data-changed";
+        inv.invalidate();
+      });
+    }
+  }
+  bindDataSignal();
+
+  // -----------------------------------------------------------------------
+  // Pan / zoom — DataViewport + binding, when enabled
+  // -----------------------------------------------------------------------
+
+  const panZoomCfg = resolvePanZoom(opts.panZoom);
+  let panZoomViewport: DataViewport<number, number> | null = null;
+  let panZoomBinding: DataViewportBinding | null = null;
+  let panZoomUnsub: (() => void) | null = null;
+  let yFitPadding: number | null = null;
+  const attachedPresets = new Set<AttachedRangePresets>();
+  const attachedSeriesReadouts = new Set<SeriesReadoutInternal>();
+  // Snapshot of the latest pipeline scales — series-readout needs the color
+  // scale to resolve swatches for non-constant color channels.
+  let latestScales: import("./geoms/types.ts").ScaleBundle | null = null;
+  // Latest hover-focus decorators (point halo + bring-to-front). Captured each
+  // full compile; replayed into the overlay layer on hover so local focus
+  // treatment costs an overlay re-bake, not a marks recompute.
+  let latestHoverDecorators: readonly import("./geoms/types.ts").GeomHoverDecorator[] = [];
+  if (panZoomCfg) {
+    const xDom = readNumericDomain(activeConfig.scaleOverrides.x, "x");
+    const yDom = readNumericDomain(activeConfig.scaleOverrides.y, "y");
+    const xType = readContinuousType(activeConfig.scaleOverrides.x);
+    const yType = readContinuousType(activeConfig.scaleOverrides.y);
+    panZoomViewport = createDataViewport<number, number>({
+      frame: createFrame({ x: 0, y: 0, width, height }),
+      x: { type: xType, domain: xDom },
+      y: { type: yType, domain: yDom },
+      minZoom: panZoomCfg.minZoom,
+      maxZoom: panZoomCfg.maxZoom,
+      panBounds: panZoomCfg.panBounds,
+    });
+    // Route pan/zoom through the active coord. For Cartesian this is a
+    // direct passthrough (byte-identical to `viewport.panBy`/`zoomAt`); for
+    // polar / radial it decomposes drag deltas into rotation + radial
+    // translation and restricts zoom to the radius scale. The wrapper uses
+    // prototype inheritance so every other DataViewport member (state,
+    // visibleXDomain, absoluteFrame, etc.) flows through untouched.
+    const coordViewport = wrapViewportThroughCoord(
+      panZoomViewport,
+      () => activeConfig.coord,
+      () => inv.invalidate(),
+    );
+    panZoomBinding = bindDataViewport(coordViewport, canvas, {
+      pan: panZoomCfg.pan,
+      zoom: panZoomCfg.zoom,
+    });
+    panZoomUnsub = panZoomViewport.onChange(() => inv.invalidate());
+    yFitPadding = panZoomCfg.yFitPadding;
+  }
+  const clipMarks = opts.clipMarks ?? true;
+
+  // -----------------------------------------------------------------------
+  // Interactions — manager + grammar tooltip wiring
+  // -----------------------------------------------------------------------
+
+  // -----------------------------------------------------------------------
+  // Transitions — animated channel lerp on data/scale change
+  // -----------------------------------------------------------------------
+
+  const transitionsCfg = resolveTransitionsCfg(opts.transitions);
+  let grammarTransitions: GrammarTransitions | null = null;
+  const transitionKey =
+    transitionsCfg && transitionsCfg.key
+      ? (datum: T, index: number) => String(transitionsCfg.key!(datum, index))
+      : undefined;
+  if (transitionsCfg !== false) {
+    const m = config.theme.motion;
+    const resolvedMotion = resolveMotion(m, m.data);
+    grammarTransitions = createGrammarTransitions({
+      duration:
+        transitionsCfg.duration !== undefined
+          ? transitionsCfg.duration / 1000
+          : resolvedMotion.durationMs / 1000,
+      easing: resolvedMotion.easing,
+      invalidator: inv,
+    });
+  }
+
+  // Track the previous data reference to detect changes.
+  let prevDataRef: readonly unknown[] | null = null;
+  // Track the previous scaleOverrides object to detect explicit scale-domain
+  // changes (e.g. `chart.scale("y", { domain: [...] })`). Identity compare per
+  // channel works because `chart.scale()` produces a new sub-object only for
+  // the changed channel; unchanged channels retain identity.
+  let prevScaleOverrides: ChartConfig<T>["scaleOverrides"] | null = null;
+
+  const interactionsCfg = resolveInteractions(opts.interactions);
+  let manager: InteractionManager | null = null;
+  let hitLayer: GrammarHitLayer | null = null;
+  let grammarTooltip: GrammarTooltip | null = null;
+  let grammarCrosshair: GrammarCrosshair | null = null;
+  let grammarSelection: GrammarSelection | null = null;
+  let grammarBrush: GrammarBrush | null = null;
+  // Imperative brush attached via `MountedPlot.attachBrush`. Mutually exclusive
+  // with `grammarBrush` — `attachBrush` throws if either is already live.
+  let attachedBrush: AttachedBrushInternal | null = null;
+  let grammarLegend: GrammarLegend | null = null;
+  let grammarContextMenu: GrammarContextMenu | null = null;
+  // Hover state — published as a signal on the public handle so chart users
+  // can react (custom annotations, side-panel detail views) and so future
+  // animated transitions can drive off it. Populated synchronously from
+  // tooltip's onHover; null when nothing's hovered.
+  const hoverSignal: Signal<HoveredHit | null> = signal<HoveredHit | null>(null);
+  // Last hit the hover subscriber acted on, so a per-pointer-move re-fire on the
+  // same row is deduped (skip redundant emphasis/overlay work). The dim/halo
+  // animation itself is driven by the GPU emphasis uniform below, not a CPU
+  // from/to lerp.
+  let lastHoverHit: HoveredHit | null = null;
+  // Pending hoverSignal.set(null) handle for the swap-grace debounce. Held at
+  // module scope of the closure so the tooltip's onHover callback can cancel
+  // it on the next non-null hit.
+  let pendingHoverNullHandle: number | null = null;
+  // Cursor-tracking cleanup for tooltip pointerPos. Set when the tooltip is
+  // created, called during dispose.
+  let cleanupCursorTracking: (() => void) | null = null;
+
+  // Shared helper: apply a hover hit (or clear) to hoverSignal + crosshair.
+  // Used by both the mouse-hover onHover path (with its grace-window debounce)
+  // and the touch-tap onPress path (which calls this directly).
+  function applyHover(next: HoveredHit | null): void {
+    hoverSignal.set(next);
+    updateCrosshairBoundsFor(next ? { x: next.x, y: next.y } : null);
+    grammarCrosshair?.setPosition(next ? { x: next.x, y: next.y } : null);
+  }
+
+  // ----- Animated GPU emphasis (P5-T3) ----------------------------------
+  // The dim-others hover treatment is driven entirely by the core's emphasis
+  // uniform: on a hover hit-change over a GPU-dim geom we resolve the hit to its
+  // namespaced focused key and animate `t` 0→1 (ease-out cubic) over
+  // `theme.interactions.hover.durationMs`; on exit we animate t→0 and keep the
+  // last focused key until t reaches 0 (then clear). Zero marks recompile.
+  //
+  // The state machine lives in `./emphasis-driver.ts` (pure, unit-tested with a
+  // deterministic clock). The mount is a thin consumer: it feeds resolved hover
+  // keys into `onHover`, advances the ramp from the RAF tick via `step(now)`,
+  // and routes the returned `{ needsFrame, full }` decisions into `inv` /
+  // `requestOverlay` / the repaint-only frame path (below).
+  //
+  // The uniform holds ONE key. Swapping hover A→B mid-animation snaps the
+  // focused key to B and continues t toward 1 (no per-key crossfade — a single
+  // global uniform can't express two focuses; documented limitation).
+  //
+  // Latest per-frame emphasis resolvers, captured each full compile.
+  let latestEmphasisResolvers: readonly EmphasisResolver[] = [];
+  const emphasis: EmphasisDriver = createEmphasisDriver({
+    // Re-read on every onHover/step so a live reduced-motion / theme change
+    // takes effect immediately. `motion.enabled === false` collapses to a snap.
+    durationS: () => {
+      const m = activeConfig.theme.motion;
+      const durMs = activeConfig.theme.interactions.hover.durationMs ?? 120;
+      return m.enabled && durMs > 0 ? durMs / 1000 : 0;
+    },
+    dim: () => activeConfig.theme.interactions.hover.dim,
+    setEmphasis: (s) => renderer.setEmphasis(s),
+  });
+  // True while the dim animation is mid-flight — a changed emphasis uniform
+  // alters pixels EVERYWHERE, so overlay/regions partial frames are FORBIDDEN
+  // until t reaches a settled value (exactly 0 or 1). See `tick()` / `drawOverlay`.
+  const emphasisAnimating = (): boolean => emphasis.animating();
+  // Set by an emphasis frame request that needs a FULL render but NOT a geom
+  // recompile (the per-tick ramp): a uniform-only change. The tick services it
+  // via the repaint-only path (`renderer.render(currentLayers())` with the live
+  // packs untouched) so the auto-cached glyph axis never re-bakes mid-ramp.
+  let emphasisRepaintPending = false;
+  // Resolve a hit to its GPU focused emphasis key, or 0 when no dim geom owns it.
+  function focusedKeyFor(hit: HoveredHit | null): number {
+    if (!hit || !hoverEmphasisEnabled() || !GPU_DIM_GEOM_KINDS.has(hit.geomKind)) return 0;
+    for (const r of latestEmphasisResolvers) {
+      if (r.geomKind === hit.geomKind && r.data === hit.data) {
+        return r.resolve(hit) ?? 0;
+      }
+    }
+    return 0;
+  }
+  hoverSignal.subscribe((next) => {
+    if (next === lastHoverHit) return;
+    lastHoverHit = next;
+
+    // Drive the emphasis state machine with the resolved focused key (0 = no dim
+    // geom under the cursor). The driver snaps under reduced-motion and reports
+    // whether a frame is needed and whether it must be FULL.
+    const req = emphasis.onHover(focusedKeyFor(next));
+    // A hover hit-change is routed through a FULL recompile (`inv.invalidate()` →
+    // drawFull), NOT the per-tick repaint-only path. Rationale: the deliberately-
+    // inert nearestX geoms (`area`/`rolling`) read `hovered` at COMPILE time, so
+    // a hover-change over them must recompile to refresh their halo; selection /
+    // legend changes arrive via their own invalidations. The hot path (~8x/ramp)
+    // is the per-tick `step()`, which IS optimized to repaint-only below — the
+    // single hover-change frame is not worth the soundness risk.
+    if (req.needsFrame) {
+      if (req.full) inv.invalidate();
+      else requestOverlay(); // exit that was never dimmed — overlay-only repaint
+    }
+  });
+  // Fix C — clear stale emphasis on a data change. Emphasis keys are
+  // index-derived, so a held hover keeps the OLD focused key dimming RE-INDEXED
+  // instances after a data swap. Snap the uniform off (driver `reset()`) and drop
+  // the hover-hit dedup state so the pointer's NEXT move re-establishes emphasis
+  // against the new data. Called by setData / update / the data signal BEFORE the
+  // full redraw they already trigger.
+  function resetEmphasisForData(): void {
+    emphasis.reset(); // snaps the uniform to t:0 / focusedKey:0
+    emphasisRepaintPending = false;
+    lastHoverHit = null; // force the next hoverSignal fire through the subscriber
+  }
+  // Selection state — array of currently-selected hits. Always an array (even
+  // when selection is disabled) so consumers don't branch on null/undefined.
+  const selectionSignal: Signal<readonly HoveredHit[]> = signal<readonly HoveredHit[]>([]);
+  // Brush state — separate signal from selection so consumers can react to
+  // either (or both) without conflating range queries with discrete picks.
+  const brushedSignal: Signal<readonly HoveredHit[]> = signal<readonly HoveredHit[]>([]);
+  // Hidden series — set of keys toggled via legend. pipeline respects this.
+  const hiddenSignal: Signal<ReadonlySet<string>> = signal<ReadonlySet<string>>(new Set());
+  if (
+    interactionsCfg.tooltip ||
+    interactionsCfg.crosshair ||
+    interactionsCfg.selection ||
+    interactionsCfg.brush ||
+    interactionsCfg.legend ||
+    interactionsCfg.contextMenu
+  ) {
+    manager = createInteractionManager(canvas);
+    manager.onChange(() => requestOverlay());
+    // Shared hit-test fan-out — one PointCloudNode per geom regardless of
+    // how many consumers (tooltip, selection, contextMenu). Only built when
+    // at least one hit-driven consumer is enabled.
+    if (
+      interactionsCfg.tooltip ||
+      interactionsCfg.selection ||
+      (interactionsCfg.contextMenu && interactionsCfg.contextMenu.hitMode !== "background")
+    ) {
+      hitLayer = createGrammarHitLayer({ manager, element: canvas });
+    }
+  }
+  // Crosshair bounds — clipped to the active plot frame so the guide line
+  // doesn't extend through axis/legend slots. Updated each draw from the
+  // pipeline output; falls back to the full canvas before the first draw.
+  // For faceted charts, this becomes the *panel* frame containing the
+  // current hover position rather than the chart-wide union frame.
+  let crosshairBounds = { x: 0, y: 0, width, height };
+  // Chart-wide plot frame (faceted: union of panels). Used by brush + as the
+  // crosshair fallback when no panel contains the hover position.
+  let chartPlotFrame: Frame = createFrame({ x: 0, y: 0, width, height });
+  // Latest per-panel frames from the pipeline. Empty for non-faceted charts.
+  let lastPanelFrames: readonly Frame[] = [];
+
+  function frameContaining(p: { x: number; y: number }): Frame | null {
+    for (const f of lastPanelFrames) {
+      if (p.x >= f.x && p.x <= f.x + f.width && p.y >= f.y && p.y <= f.y + f.height) {
+        return f;
+      }
+    }
+    return null;
+  }
+  function updateCrosshairBoundsFor(p: { x: number; y: number } | null): void {
+    if (lastPanelFrames.length === 0 || !p) {
+      crosshairBounds = chartPlotFrame;
+      return;
+    }
+    const f = frameContaining(p);
+    crosshairBounds = f ? { x: f.x, y: f.y, width: f.width, height: f.height } : chartPlotFrame;
+  }
+  if (interactionsCfg.crosshair) {
+    grammarCrosshair = createGrammarCrosshair(
+      {
+        // The crosshair/brush/menu/tooltip primitives are v1-only insomni
+        // helpers (no v3 equivalent yet); they draw via `pushSegment`/`pushRect`
+        // which exist identically on the v3 `Layer` at runtime, so the v3
+        // overlay layer is bridged to the v1 `Layer` type here.
+        hudLayer: () => overlayLayer as unknown as V1Layer,
+        theme: () => activeConfig.theme,
+        bounds: () => crosshairBounds,
+        invalidator: overlayInv,
+      },
+      typeof interactionsCfg.crosshair === "object" ? interactionsCfg.crosshair : {},
+    );
+    // Free pointer-following mode — register a low-zIndex InteractionNode over
+    // the chart-wide plot frame that pushes raw cursor positions into the
+    // crosshair. The hit-layer's pointcloud nodes sit at higher zIndex, so
+    // when the cursor is over a hit point the tooltip's onHover snaps the
+    // crosshair to the data position and this node never sees those events.
+    // Outside hits, this node fires and the crosshair tracks the raw cursor.
+    const crosshairCfg =
+      typeof interactionsCfg.crosshair === "object" ? interactionsCfg.crosshair : {};
+    if (crosshairCfg.followPointer && manager) {
+      manager.add({
+        zIndex: -1,
+        space: "ui",
+        bounds: () => chartPlotFrame,
+        onHoverEnter: (e) => {
+          updateCrosshairBoundsFor({ x: e.x, y: e.y });
+          grammarCrosshair?.setPosition({ x: e.x, y: e.y });
+        },
+        onHoverMove: (e) => {
+          updateCrosshairBoundsFor({ x: e.x, y: e.y });
+          grammarCrosshair?.setPosition({ x: e.x, y: e.y });
+        },
+        onHoverLeave: () => {
+          grammarCrosshair?.setPosition(null);
+        },
+      });
+    }
+  }
+  if (interactionsCfg.selection && manager && hitLayer) {
+    grammarSelection = createGrammarSelection(
+      { manager, hitLayer },
+      {
+        onChange: (selected) => {
+          selectionSignal.set(selected);
+          inv.invalidate();
+        },
+      },
+    );
+  }
+  if (interactionsCfg.brush && manager) {
+    grammarBrush = createGrammarBrush(
+      {
+        manager,
+        // Brush operates on the chart-wide plot frame even when faceted —
+        // a range query that spans panels is still meaningful. Crosshair
+        // bounds are panel-scoped (see `crosshairBounds`).
+        bounds: () => chartPlotFrame,
+        hudLayer: () => overlayLayer as unknown as V1Layer,
+        theme: () => activeConfig.theme,
+        invalidator: overlayInv,
+      },
+      {
+        ...(typeof interactionsCfg.brush === "object" ? interactionsCfg.brush : {}),
+        onChange: (hits) => {
+          brushedSignal.set(hits);
+          // Brushed set never feeds mark compile (only hovered/selected/hidden
+          // do), so a brush change is an overlay-only repaint.
+          requestOverlay();
+        },
+      },
+    );
+  }
+  if (interactionsCfg.legend && manager) {
+    grammarLegend = createGrammarLegend({
+      manager,
+      hidden: hiddenSignal,
+      invalidator: inv,
+    });
+  }
+  if (interactionsCfg.contextMenu && manager) {
+    const cfg = interactionsCfg.contextMenu;
+    // For `background` mode we never need a hit-layer; resolve through a stub.
+    // Otherwise reuse the shared hit-layer built above. A `background`-mode
+    // menu running alongside a tooltip still gets the shared hit-layer (no
+    // harm — it just ignores it).
+    const hl: GrammarHitLayer = hitLayer ?? {
+      sync: () => {},
+      subscribe: () => () => {},
+      pickAt: () => null,
+      state: () => ({ active: null }),
+      subscribeState: () => () => {},
+      dispose: () => {},
+    };
+    grammarContextMenu = createGrammarContextMenu(
+      {
+        manager,
+        hitLayer: hl,
+        hudLayer: () => overlayLayer as unknown as V1Layer,
+        atlas: () => atlas,
+        theme: () => activeConfig.theme,
+        bounds: () => ({ x: 0, y: 0, width, height }),
+        invalidator: overlayInv,
+        onViewportChange: panZoomViewport ? (cb) => panZoomViewport!.onChange(cb) : undefined,
+      },
+      {
+        hitMode: cfg.hitMode ?? "nearest-point",
+        managerOpts:
+          cfg.holdMs !== undefined || cfg.slopPx !== undefined
+            ? { holdMs: cfg.holdMs, slopPx: cfg.slopPx }
+            : undefined,
+        // Suppress trigger while the data viewport is mid-pan / mid-fling.
+        // The manager already cancels touch long-press on drag promotion;
+        // this catches the right-click-during-drag case for mouse.
+        isSuppressed: panZoomBinding
+          ? () => panZoomBinding!.interacting || panZoomBinding!.flinging
+          : undefined,
+        onTrigger: cfg.onTrigger,
+        items: cfg.items,
+        onAction: cfg.onAction,
+        placement: cfg.placement,
+        style: cfg.style,
+      },
+    );
+  }
+  if (interactionsCfg.tooltip && hitLayer) {
+    // Track cursor position so the tooltip anchor follows the pointer even
+    // while the cursor stays within the same data cell (where no enter/leave
+    // fires from the hit-layer). This keeps the tooltip box near the cursor
+    // in dense UIs like heatmaps instead of being left behind at the enter
+    // position.
+    let cursorPos: { x: number; y: number } | null = null;
+    const onCursorMove = (e: PointerEvent) => {
+      cursorPos = { x: e.offsetX, y: e.offsetY };
+    };
+    const onCursorLeave = () => {
+      cursorPos = null;
+    };
+    canvas.addEventListener("pointermove", onCursorMove);
+    canvas.addEventListener("pointerleave", onCursorLeave);
+    cleanupCursorTracking = () => {
+      canvas.removeEventListener("pointermove", onCursorMove);
+      canvas.removeEventListener("pointerleave", onCursorLeave);
+    };
+    const ttCfg = typeof interactionsCfg.tooltip === "object" ? interactionsCfg.tooltip : {};
+    const axisMode = ttCfg.trigger === "axis";
+    grammarTooltip = createGrammarTooltip(
+      {
+        hitLayer,
+        hudLayer: () => overlayLayer as unknown as V1Layer,
+        atlas: () => atlas,
+        theme: () => activeConfig.theme,
+        bounds: () => ({ x: 0, y: 0, width, height }),
+        invalidator: overlayInv,
+        pointerPos: () => cursorPos,
+        scales: () => latestScales,
+        onAxisPointer:
+          axisMode && manager
+            ? (h) => {
+                const node = manager!.add({
+                  zIndex: -2, // below hit clouds (1000+) and crosshair (-1)
+                  space: "ui",
+                  bounds: () => chartPlotFrame,
+                  onHoverEnter: (e) => h.move({ x: e.x, y: e.y }),
+                  onHoverMove: (e) => h.move({ x: e.x, y: e.y }),
+                  onHoverLeave: () => h.leave(),
+                });
+                return () => node.destroy();
+              }
+            : undefined,
+      },
+      {
+        ...(typeof interactionsCfg.tooltip === "object" ? interactionsCfg.tooltip : {}),
+        onHover: (hit) => {
+          // Debounce null transitions: when leave fires, defer the
+          // `hoverSignal.set(null)` through a grace window. A non-null hit
+          // arriving within the window cancels the pending null and applies the
+          // new hit directly. This keeps `emphFocusedKey` (held in the emphasis
+          // driver) pointed at the previous focus until the swap lands, so the
+          // dim stays continuous and never flashes un-dim → re-dim as the cursor
+          // crosses between adjacent geoms.
+          if (pendingHoverNullHandle !== null) {
+            clearTimeout(pendingHoverNullHandle);
+            pendingHoverNullHandle = null;
+          }
+          if (hit) {
+            applyHover(hit);
+            return;
+          }
+          const grace = activeConfig.theme.interactions.hoverSwapGraceMs;
+          if (grace > 0) {
+            pendingHoverNullHandle = setTimeout(() => {
+              pendingHoverNullHandle = null;
+              applyHover(null);
+            }, grace) as unknown as number;
+          } else {
+            applyHover(null);
+          }
+        },
+      },
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // Resize plumbing
+  // -----------------------------------------------------------------------
+
+  // Apply our `width`/`height`/`dpr` to the renderer's backing canvas.
+  // Keeps device pixels = CSS px * dpr; a `space: "ui"` layer maps 1:1 with
+  // CSS pixels.
+  function applySize(): void {
+    if (ownedRenderer) {
+      renderer.setDpr(dpr);
+      renderer.resize(Math.max(1, Math.round(width * dpr)), Math.max(1, Math.round(height * dpr)));
+    }
+  }
+
+  applySize();
+
+  let resizeObserver: ResizeObserver | null = null;
+  if (autoResize && typeof ResizeObserver !== "undefined") {
+    resizeObserver = new ResizeObserver(() => {
+      const r = canvas.getBoundingClientRect();
+      const nextDpr = opts.dpr ?? readDpr();
+      const nextW = r.width || canvas.clientWidth || width;
+      const nextH = r.height || canvas.clientHeight || height;
+      if (nextW === width && nextH === height && nextDpr === dpr) return;
+      width = nextW;
+      height = nextH;
+      dpr = nextDpr;
+      applySize();
+      pendingFullReason = "resize";
+      inv.invalidate();
+    });
+    resizeObserver.observe(canvas);
+  }
+
+  // -----------------------------------------------------------------------
+  // Visibility pause
+  // -----------------------------------------------------------------------
+
+  let visibleHandler: (() => void) | null = null;
+  if (pauseOnHidden && typeof document !== "undefined") {
+    visibleHandler = () => {
+      // When tab returns, force a redraw (state may have advanced).
+      if (document.visibilityState === "visible") inv.invalidate();
+    };
+    document.addEventListener("visibilitychange", visibleHandler);
+  }
+
+  // -----------------------------------------------------------------------
+  // Draw — pure of loop concerns; called from rAF tick, manual update(), or
+  // toSVG(). Uses the active config + the latest dataSnapshot + working
+  // width/height.
+  // -----------------------------------------------------------------------
+
+  // Rebuild active config from the builder closure (if any) and rebind data.
+  function refreshActiveConfig(): void {
+    if (!builder) return;
+    const next = builder();
+    activeConfig = configOf(next);
+    // Builder may return a chart whose `data` is a different signal — rebind.
+    if (isSignal<readonly T[]>(activeConfig.data)) {
+      bindDataSignal();
+    } else {
+      unsubscribeData?.();
+      unsubscribeData = null;
+      dataSnapshot = currentData(activeConfig.data);
+    }
+  }
+
+  // Pan/zoom: override x/y scale domains with the viewport's visible window
+  // so axes / ticks / scales follow pan & zoom automatically. yFit additionally
+  // rescans the visible-X slice each frame so Y tracks on-screen values.
+  function applyPanZoomScales(snapshot: ChartConfig<T>): void {
+    if (!panZoomViewport) return;
+    const vx = panZoomViewport.visibleXDomain as readonly [number, number];
+    let vy = panZoomViewport.visibleYDomain as readonly [number, number];
+    if (yFitPadding !== null) {
+      const yExtent = computeVisibleYExtent(activeConfig.layers, dataSnapshot, vx, yFitPadding);
+      if (yExtent) vy = yExtent;
+    }
+    snapshot.scaleOverrides = {
+      ...snapshot.scaleOverrides,
+      x: { ...snapshot.scaleOverrides.x, domain: vx } as PositionScaleOptions,
+      y: { ...snapshot.scaleOverrides.y, domain: vy } as PositionScaleOptions,
+    };
+  }
+
+  // Notify transitions when data identity or scaleOverride values change.
+  // Compares scaleOverrides by value: closure-driven `build()` recreates the
+  // option objects each frame even when nothing changed, so reference compare
+  // would retrigger every frame and pin transitions at t≈0.
+  function notifyTransitionsOnChange(): void {
+    const currentDataRef: readonly unknown[] = dataSnapshot as readonly unknown[];
+    const currentScaleOverrides = activeConfig.scaleOverrides;
+    const dataChanged = prevDataRef !== null && prevDataRef !== currentDataRef;
+    const scaleChanged =
+      prevScaleOverrides !== null &&
+      SCALE_OVERRIDE_KEYS.some(
+        (k) => !shallowObjectEqual(prevScaleOverrides![k], currentScaleOverrides[k]),
+      );
+    // Gate on theme.motion.enabled — reduced-motion already collapses
+    // duration, but skipping notifyChange avoids spurious frame captures.
+    if (grammarTransitions && activeConfig.theme.motion.enabled && (dataChanged || scaleChanged)) {
+      grammarTransitions.notifyChange();
+    }
+    prevDataRef = currentDataRef;
+    prevScaleOverrides = currentScaleOverrides;
+  }
+
+  // Apply layer clips, viewport frame sync, and crosshair gating from a
+  // freshly-run pipeline output.
+  function applyPipelineFrames(out: import("./pipeline.ts").PipelineOutput<T>): void {
+    chartPlotFrame = out.plotFrame;
+    // Universal: clip marks to the inner plot panel so geom rects/lines
+    // can't bleed into axis / legend / title slots.
+    if (clipMarks) {
+      marksLayer.setClipRect({
+        x: out.plotFrame.x,
+        y: out.plotFrame.y,
+        width: out.plotFrame.width,
+        height: out.plotFrame.height,
+      });
+      const outerClip = {
+        x: out.outerFrame.x,
+        y: out.outerFrame.y,
+        width: out.outerFrame.width,
+        height: out.outerFrame.height,
+      };
+      hudLayer.setClipRect(outerClip);
+      // Overlays share the hud's outer clip. The clip survives `clear()`, so
+      // setting it on full frames keeps it valid through overlay-only frames.
+      overlayLayer.setClipRect(outerClip);
+    }
+    // Pan/zoom: keep the viewport's pointer-frame aligned with the actual
+    // panel so drag deltas map 1:1 to data-domain shifts. Pass `reserve`
+    // so the viewport's axis pixel range matches the position scales —
+    // `dataToScreen` then lines up with where marks actually render.
+    if (panZoomViewport) {
+      panZoomViewport.setFrame(out.plotFrame, out.reserve);
+    }
+    lastPanelFrames = out.panelFrames ?? [];
+    // Recompute panel-scoped bounds against the current hover (panel frames
+    // may have shifted on resize / data change while the cursor sat still).
+    updateCrosshairBoundsFor(hoverSignal.peek());
+    if (grammarCrosshair) {
+      // Auto-enable on continuous x scales only — gating here so the
+      // tooltip's onHover observer (which fires synchronously) sees the
+      // live scale type.
+      grammarCrosshair.setEnabled(out.scales.x.type !== "band");
+    }
+  }
+
+  // v3 composite view fingerprint extension. The mount's layers are all
+  // `ui`-space, so the renderer's camera never moves and it cannot observe a
+  // pan/zoom data-domain shift on its own. Folding the visible domain into
+  // `viewKey` makes the renderer treat a domain change as a view change (a full
+  // repaint) rather than letting an overlay-only damage frame composite against
+  // a stale bake — the v3 fix for v1's group/domain-omission footgun.
+  function currentViewKey(): string | undefined {
+    if (!panZoomViewport) return undefined;
+    const vx = panZoomViewport.visibleXDomain as readonly [number, number];
+    const vy = panZoomViewport.visibleYDomain as readonly [number, number];
+    return `${vx[0]},${vx[1]},${vy[0]},${vy[1]}`;
+  }
+
+  // Render node list for this frame. Order: axis (bottom), caller `belowMarks`,
+  // marks, caller `aboveMarks`, hud, overlay (top). Each layer carries an
+  // explicit `zIndex` band so the core's flat-z composite order matches this
+  // array order exactly (and is robust to any future reordering). Stable across
+  // full and overlay-only frames so the renderer's damage replay sees the same
+  // commands. Extra layers are assigned bands by index (below: 10,11,…; above:
+  // 110,111,…) so they slot between the fixed bands without colliding.
+  function currentLayers(): readonly Layer[] {
+    const extra = opts.extraLayers?.();
+    if (!extra) return [axisLayer, marksLayer, hudLayer, overlayLayer];
+    const below = extra.belowMarks ?? [];
+    const above = extra.aboveMarks ?? [];
+    for (let i = 0; i < below.length; i++) {
+      below[i]!.zIndex = Z_BELOW_BASE + i;
+      below[i]!.label ??= `below:${i}`;
+    }
+    for (let i = 0; i < above.length; i++) {
+      above[i]!.zIndex = Z_ABOVE_BASE + i;
+      above[i]!.label ??= `above:${i}`;
+    }
+    return [axisLayer, ...below, marksLayer, ...above, hudLayer, overlayLayer];
+  }
+
+  // Interaction-aware cache-hint flip (replaces the old pan-tax bake dance).
+  // While a pan/zoom/fling is in flight, set the static layers' `cache` to
+  // "never" so they draw LIVE: a pan recompiles the geoms each frame → the
+  // layer pack version changes → an "auto" bake would re-bake (texture create +
+  // bake pass) EVERY frame, strictly worse than live. On settle, restore "auto"
+  // so the core's policy bakes the now-static stack once and pan-idle hovers ride
+  // the cached fast path. No-op outside `partial` mode (hints are pinned
+  // "never"). Mutating `cache` between frames is a supported core contract
+  // (Layer.cache is mutable; the policy re-evaluates it every render()).
+  function applyInteractionCacheHints(): void {
+    if (!partial) return;
+    const interacting = !!panZoomBinding && (panZoomBinding.interacting || panZoomBinding.flinging);
+    const hint: CacheHint = interacting ? "never" : "auto";
+    axisLayer.cache = hint;
+    // Marks get their own hint: pinned "never" for GPU-dim charts (a bake would
+    // freeze the no-op bake-time emphasis, so dim needs live marks), else the
+    // shared interaction hint (big scatters still auto-bake when settled).
+    marksLayer.cache = marksCacheHint(interacting);
+    hudLayer.cache = hint;
+    // Extra layers (caller below/above) follow the same gesture treatment.
+    const extra = opts.extraLayers?.();
+    if (extra) {
+      for (const l of extra.belowMarks ?? []) l.cache = hint;
+      for (const l of extra.aboveMarks ?? []) l.cache = hint;
+    }
+    // overlayLayer stays "never" — never touched here.
+  }
+
+  // Whether hover emphasis (focus halo / dim) is enabled in the active theme.
+  function hoverEmphasisEnabled(): boolean {
+    return activeConfig.theme.interactions.hover.enabled;
+  }
+  // The decorator (if any) that owns this hit. A decorator draws a local focus
+  // treatment (contrast halo / bring-to-front) into the live overlay layer:
+  // point, plus bar/histogram/tile/line (whose dim-others is the GPU emphasis
+  // uniform — the halo is the complementary focus shape, left at emphasisKey 0
+  // so it stays full-strength while the rest dim). A hit with NO decorator just
+  // gets the uniform dim (or nothing).
+  function decoratorFor(
+    hit: import("./geoms/types.ts").HoveredHit | null,
+  ): import("./geoms/types.ts").GeomHoverDecorator | null {
+    if (!hit) return null;
+    for (const d of latestHoverDecorators) {
+      if (d.geomKind === hit.geomKind && d.data === hit.data) return d;
+    }
+    return null;
+  }
+  // Whether the active chart contains a GPU-dim geom (with hover enabled). Such
+  // a chart pins its marks layer to `cache:"never"` (see `marksCacheHint`) so the
+  // emphasis uniform can dim LIVE marks — a bake would freeze the bake-time no-op
+  // emphasis. Recomputed each full frame off the resolved config.
+  function chartHasDimGeom(): boolean {
+    if (!hoverEmphasisEnabled()) return false;
+    return activeConfig.layers.some((g) => GPU_DIM_GEOM_KINDS.has(g.kind));
+  }
+  // Cache hint for the MARKS layer specifically. Pinned to "never" whenever the
+  // chart has a GPU-dim geom (live marks required for the emphasis uniform to
+  // dim them). Otherwise it follows the shared interaction hint (auto when
+  // settled, never while panning) so big scatters still auto-bake.
+  function marksCacheHint(interacting: boolean): CacheHint {
+    if (!partial) return "never";
+    if (chartHasDimGeom()) return "never";
+    return interacting ? "never" : "auto";
+  }
+
+  // Clear + re-emit the cursor-driven overlays onto their dedicated layer.
+  // Used by both the full and overlay-only paths. The overlay clip is set on
+  // full frames (in applyPipelineFrames) and survives `clear()`.
+  function emitOverlays(): void {
+    overlayLayer.clear();
+    // Hover focus decoration first so it sits beneath crosshair lines + tooltip
+    // shapes (push order = z order within the layer). It composites above the
+    // baked marks, so the focused point reads on top of every other mark.
+    if (hoverEmphasisEnabled()) {
+      const hit = hoverSignal.peek();
+      decoratorFor(hit)?.decorate(hit!, overlayLayer);
+    }
+    // Brush rect next so it sits beneath crosshair lines + tooltip shapes.
+    if (grammarBrush) grammarBrush.draw();
+    if (attachedBrush) attachedBrush.draw();
+    // Crosshair BEFORE tooltip so the tooltip box occludes the crosshair
+    // line that passes beneath/through it — prevents a visible line segment
+    // inside the tooltip's rounded rectangle.
+    if (grammarCrosshair) grammarCrosshair.draw();
+    if (grammarTooltip) grammarTooltip.draw();
+    // Menu on top so it can't be obscured.
+    if (grammarContextMenu) grammarContextMenu.draw();
+  }
+
+  // Current overlay-layer content rect (CSS px), or null when empty. Snapped
+  // outward to integers and padded a few px: the text AABB is advance-width
+  // based and can underflow actual ink (drop shadows, italics, decorations),
+  // and the rect lands as an integer device-px scissor. Without the margin a
+  // moving tooltip could leave a 1–2px ghost of its previous footprint. (The
+  // renderer pads a further +1px for the AA fringe.)
+  const OVERLAY_DAMAGE_PAD = 3;
+  function overlayRect(): FrameRect | null {
+    const b = overlayLayer.effectiveLocalBounds;
+    if (!b) return null;
+    const x = Math.floor(b.minX - OVERLAY_DAMAGE_PAD);
+    const y = Math.floor(b.minY - OVERLAY_DAMAGE_PAD);
+    const maxX = Math.ceil(b.maxX + OVERLAY_DAMAGE_PAD);
+    const maxY = Math.ceil(b.maxY + OVERLAY_DAMAGE_PAD);
+    return { x, y, width: maxX - x, height: maxY - y };
+  }
+  function unionRect(a: FrameRect | null, b: FrameRect | null): FrameRect | null {
+    if (!a) return b;
+    if (!b) return a;
+    const x = Math.min(a.x, b.x);
+    const y = Math.min(a.y, b.y);
+    const maxX = Math.max(a.x + a.width, b.x + b.width);
+    const maxY = Math.max(a.y + a.height, b.y + b.height);
+    return { x, y, width: maxX - x, height: maxY - y };
+  }
+  // The core's `render({ regions })` takes CSS-px `Bounds2D` ({minX,minY,maxX,
+  // maxY}); our overlay rects are `FrameRect` ({x,y,width,height}). Convert.
+  function rectToBounds(r: FrameRect): import("insomni").Bounds2D {
+    return { minX: r.x, minY: r.y, maxX: r.x + r.width, maxY: r.y + r.height };
+  }
+
+  // Full frame: recompile the whole chart, (partial mode) bake the marks, and
+  // render every layer. Resets both dirty flags.
+  function drawFull(): void {
+    if (!fontReady) return;
+    inv.clear();
+    overlayDirty = false;
+
+    refreshActiveConfig();
+
+    const snapshot: ChartConfig<T> = { ...activeConfig, width, height };
+    applyPanZoomScales(snapshot);
+    const legendDimAlpha = interactionsCfg.legend ? interactionsCfg.legend.dimAlpha : undefined;
+
+    notifyTransitionsOnChange();
+
+    const out = runPipeline(snapshot, dataSnapshot, axisLayer, marksLayer, hudLayer, atlas, {
+      // GPU-dim geoms (bar/histogram/tile/line/...) do NOT read `hovered` — their
+      // dim-others treatment rides the animated emphasis uniform (P5-T3), keyed
+      // at compile time. `hovered` is still threaded for the deliberately-inert
+      // nearestX geoms (`area`/`rolling`) whose compile-time halo only updates on
+      // a full frame. Point's focus halo rides the overlay decorator, not
+      // compile-time `hovered`.
+      hovered: hoverEmphasisEnabled() ? hoverSignal.peek() : undefined,
+      selected: grammarSelection ? selectionSignal.peek() : undefined,
+      hidden: hiddenSignal.peek(),
+      legendDimAlpha,
+      transitions: grammarTransitions ?? undefined,
+      transitionKey,
+    });
+
+    // Hand fresh hit-test data to the interactions layer; tooltip ticks are
+    // driven by the rAF loop (see `tick()` below) and tooltip.draw() lays
+    // shapes on the hud layer after the pipeline has finished filling it.
+    applyPipelineFrames(out);
+    // Single sync into the shared hit layer; tooltip + selection observe its
+    // events via subscribe(). `selection.sync` still runs to refresh its
+    // id→position registry (needed for sticky selections across re-renders),
+    // but no longer manages PointCloudNodes itself.
+    if (hitLayer) {
+      hitLayer.sync(out.hitTests);
+    }
+    // Series-readouts pull from the same compiled hit-tests + the live scale
+    // bundle (color scale → series swatch). Push on every draw so the panel
+    // tracks data / scale changes alongside the chart.
+    latestScales = out.scales;
+    latestHoverDecorators = out.hoverDecorators;
+    latestEmphasisResolvers = out.emphasisResolvers;
+    if (attachedSeriesReadouts.size > 0) {
+      for (const r of attachedSeriesReadouts) r.syncHits(out.hitTests);
+    }
+    grammarTooltip?.syncHits?.(out.hitTests);
+    if (grammarSelection) {
+      grammarSelection.sync(out.hitTests);
+    }
+    if (grammarBrush) {
+      grammarBrush.sync(out.hitTests);
+    }
+    if (attachedBrush) {
+      attachedBrush.syncHits(out.hitTests);
+    }
+    if (grammarLegend) {
+      grammarLegend.sync(out);
+    }
+    // Emit the cursor overlays onto their own layer (above the hud).
+    emitOverlays();
+    lastOverlayRect = overlayRect();
+
+    // Background follows the resolved config unless overridden — only when we
+    // own the renderer. Re-apply each frame because the builder may have
+    // produced a chart with a different theme.
+    if (ownedRenderer) {
+      renderer.setBackground(
+        backgroundOverride ?? activeConfig.background ?? activeConfig.theme.background,
+      );
+    }
+
+    // Flip the static layers' cache hint based on the live interaction state
+    // (never while panning/flinging, auto when settled) — the core's per-frame
+    // cache policy reads `Layer.cache` on the next render() and bakes/unbakes
+    // accordingly. No manual cacheLayer/uncacheLayer here: the policy owns it.
+    applyInteractionCacheHints();
+
+    // A normal full frame. NEVER `fullFrame:true` — the core's view fingerprint
+    // (camera/dpr/size/background + `viewKey`) plus its force-full-after-(un)bake
+    // logic decides. With no `regions` this is a full frame by construction; a
+    // (re)bake triggered by the policy this frame is automatically promoted to
+    // full. `viewKey` folds the visible domain so a pan-driven domain shift on
+    // these ui-space layers (whose camera never moves) still forces a full
+    // repaint rather than compositing against a stale bake.
+    // Static debug metadata on the marks layer (P5-T1, D7): the geom kinds in
+    // compile order, refreshed each full frame. Read only when the probe is
+    // enabled; assigning a small array on the full-frame path is irrelevant to
+    // rendering. Reference-assigned (not cloned) — the core copies the reference.
+    marksLayer.debugData = { geoms: activeConfig.layers.map((g) => g.kind) };
+
+    // Resolve the annotation reason: a live pan/zoom gesture overrides the
+    // latched cause; otherwise use whatever the invalidation source set (or the
+    // "invalidate" default). Reset the latch afterwards so a later unclassified
+    // invalidation reports "invalidate" rather than a stale cause.
+    const interacting = !!panZoomBinding && (panZoomBinding.interacting || panZoomBinding.flinging);
+    const reason = interacting ? "pan-zoom" : pendingFullReason;
+    pendingFullReason = "invalidate";
+
+    renderer.render(currentLayers(), {
+      ...(partial ? { viewKey: currentViewKey() } : {}),
+      debug: { reason },
+    });
+  }
+
+  // Overlay-only repaint (partial mode only). The baked static stack (axis /
+  // marks / hud) is untouched in the persistent backbuffer; re-emit just the
+  // overlay layer and DAMAGE-repaint the union of its previous + current
+  // footprints via `regions`. The core scissors the partial frame (OIT-aware,
+  // Phase 1), so the live overlay composites over the baked stack inside the
+  // damage rect with correct transparency.
+  //
+  // `viewKey` MUST match the value the last `drawFull` used so the core's view
+  // fingerprint is unchanged across this overlay-only frame — otherwise the core
+  // demotes to a full repaint. `currentViewKey()` folds only the visible domain,
+  // which doesn't change on an overlay-only frame, so it is stable here.
+  //
+  // OIT note: plot's renderer runs with OIT ON (`createRenderer` default — the
+  // mount does not pass `oit:false`), so a glyph-bearing overlay (tooltip text)
+  // stays a partial frame. (On a NON-OIT renderer the core self-demotes live
+  // MSDF-glyph partial frames to full — correct, just less optimal — but that
+  // path is unreachable here.)
+  function drawOverlay(): void {
+    if (!fontReady) return;
+    overlayDirty = false;
+    emitOverlays();
+    const next = overlayRect();
+    const region = unionRect(lastOverlayRect, next);
+    lastOverlayRect = next;
+    // Nothing visible changed on the overlay (e.g. a hover with no tooltip) —
+    // skip rather than fall back to a full clear.
+    if (!region) return;
+    renderer.render(currentLayers(), {
+      regions: [rectToBounds(region)],
+      viewKey: currentViewKey(),
+      // P5-T1 (D7): overlay-only frames are cursor-driven (tooltip / crosshair /
+      // brush / point halo). A single "hover-moved" tag covers them — the cause
+      // isn't cheaply distinguishable at this call site (all overlay sources
+      // funnel through `requestOverlay`), so we don't build plumbing to split it.
+      debug: { reason: "hover-moved" },
+    });
+  }
+
+  // Repaint-only FULL frame (Fix D — emphasis ramp). A full render of the
+  // EXISTING layers with NO `runPipeline` recompile: the marks/axis/hud packs
+  // are byte-identical to the last `drawFull`, so their cache keys are stable
+  // and the core re-uses every existing bake — zero texture allocs / bake passes
+  // — while the changed emphasis uniform (already written by the driver) dims the
+  // composite. It is a FULL render (no `regions`): the uniform is global, so a
+  // partial frame would leave the un-repainted backbuffer showing the old dim
+  // (the P5-T3 soundness rule). Used by the per-tick ramp where the ONLY thing
+  // that changed is the uniform — marks packs are hover-independent. NEVER used
+  // when `inv.dirty` (a real recompile is pending → `drawFull` wins).
+  function drawRepaint(): void {
+    if (!fontReady) return;
+    renderer.render(currentLayers(), {
+      ...(partial ? { viewKey: currentViewKey() } : {}),
+      // P5-T1 (D7): a uniform-only emphasis dim ramp step (no recompile).
+      debug: { reason: "emphasis-ramp" },
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // RAF tick
+  // -----------------------------------------------------------------------
+
+  let rafId = 0;
+  let lastFrameTime = 0;
+  function tick(time: number): void {
+    if (disposed) return;
+    const dtSeconds = lastFrameTime === 0 ? 0 : Math.max(0, (time - lastFrameTime) / 1000);
+    lastFrameTime = time;
+    // Tick interaction animations even when nothing else is dirty — the
+    // tooltip's fade/show-delay needs frames to advance.
+    if (grammarTooltip && dtSeconds > 0) grammarTooltip.step(dtSeconds);
+    if (grammarContextMenu && dtSeconds > 0) grammarContextMenu.step(dtSeconds);
+    if (grammarTransitions && dtSeconds > 0) {
+      if (grammarTransitions.step(dtSeconds)) inv.invalidate();
+    }
+    // Advance the GPU emphasis dim toward its target via the driver. The driver
+    // writes the eased uniform and reports whether a (full) frame is needed. A
+    // ramp step changes ONLY the uniform — the marks packs are hover-independent
+    // — so we DON'T `inv.invalidate()` (which would `drawFull` → `runPipeline`,
+    // bumping pack versions and re-baking the auto-cached glyph axis ~8x/ramp).
+    // Instead we flag a REPAINT-ONLY full frame (`drawRepaint`): a full render of
+    // the unchanged packs with stable cache keys → zero re-bakes. Still a FULL
+    // render (never regions): the uniform is global. The loop stops cleanly once
+    // settled (the driver returns no frame when `t === target`). A real
+    // invalidation mid-ramp (resize / data / settle below) sets `inv.dirty` and
+    // wins over the repaint via the `needsFull` ordering at the bottom of tick().
+    if (emphasisAnimating()) {
+      const req = emphasis.step(time);
+      if (req.needsFrame) emphasisRepaintPending = true; // req.full is always true here
+    }
+    // Settle edge: detect the interacting → settled transition and force one
+    // final full frame so `applyInteractionCacheHints()` flips the static layers
+    // back to "auto" and the core's policy re-bakes the now-static stack. Without
+    // this, drag-end (no fling) fires no `onChange`, so the last full frame ran
+    // while still interacting (hints "never", live) and the stack would never
+    // re-bake — every later overlay frame would composite against live geometry
+    // it can't damage-track minimally.
+    if (partial) {
+      const nowInteracting =
+        !!panZoomBinding && (panZoomBinding.interacting || panZoomBinding.flinging);
+      if (wasInteracting && !nowInteracting) {
+        pendingFullReason = "settle-rebake";
+        inv.invalidate();
+      }
+      wasInteracting = nowInteracting;
+    }
+    // Frame-kind dispatch, strongest-wins:
+    //   1. `inv.dirty`              → drawFull (recompile + bake + render). A real
+    //      change (resize / data / settle / hover hit-change) ALWAYS wins, even
+    //      mid-ramp, so a resize/data invalidation during the dim animation is
+    //      serviced correctly.
+    //   2. `emphasisRepaintPending` → drawRepaint (FULL render, NO recompile): a
+    //      uniform-only emphasis ramp step. Stable packs → zero re-bakes (Fix D).
+    //   3. `overlayDirty`           → drawOverlay (regions/partial). Only reached
+    //      when the emphasis uniform is SETTLED (an active ramp sets (2), which
+    //      is full and outranks this) — preserving the P5-T3 soundness rule that
+    //      a partial frame never runs while the global uniform is mid-transition.
+    const needsFull = inv.dirty;
+    const needsRepaint = emphasisRepaintPending;
+    const needsOverlay = partial && overlayDirty;
+    if (needsFull || needsRepaint || needsOverlay) {
+      const hidden = pauseOnHidden && typeof document !== "undefined" && document.hidden;
+      if (!hidden) {
+        if (needsFull) drawFull();
+        else if (needsRepaint) drawRepaint();
+        else drawOverlay();
+      }
+      // The repaint flag is consumed by ANY frame this tick (a winning drawFull
+      // already painted the current uniform; a drawRepaint serviced it directly).
+      emphasisRepaintPending = false;
+    }
+    rafId = requestAnimationFrame(tick);
+  }
+  if (autoFrame) {
+    rafId = requestAnimationFrame(tick);
+  }
+
+  // -----------------------------------------------------------------------
+  // Public handle
+  // -----------------------------------------------------------------------
+
+  return {
+    invalidate(): void {
+      inv.invalidate();
+    },
+    update(source) {
+      if (typeof source === "function") {
+        builder = source as () => Chart<T>;
+      } else if (source) {
+        builder = null;
+        activeConfig = configOf(source);
+        bindDataSignal();
+      }
+      // Clear stale index-derived emphasis (Fix C) before the recompile — a held
+      // hover would otherwise keep dimming re-indexed instances.
+      resetEmphasisForData();
+      pendingFullReason = "data-changed";
+      // Pass-through (no source) → just rebuild via the existing builder/spec.
+      inv.invalidate();
+      // If autoFrame is off, draw synchronously so `update()` is the user's
+      // single render call.
+      if (!autoFrame && !disposed) drawFull();
+    },
+    setData(next): void {
+      // Replace activeConfig.data with a frozen snapshot. Signal subscriptions
+      // are torn down because the user just took manual control of the data.
+      unsubscribeData?.();
+      unsubscribeData = null;
+      dataSnapshot = next;
+      activeConfig = { ...activeConfig, data: next };
+      // Clear stale index-derived emphasis (Fix C): the new data re-indexes
+      // instances, so a held hover's old focused key must drop before the redraw.
+      resetEmphasisForData();
+      pendingFullReason = "data-changed";
+      inv.invalidate();
+    },
+    resize(w, h): void {
+      // Manual resize. If autoResize is on you don't usually need this, but
+      // it's a useful escape hatch (e.g. forcing a fixed export size).
+      if (w !== undefined) width = w;
+      if (h !== undefined) height = h;
+      if (w === undefined && h === undefined) {
+        const r = canvas.getBoundingClientRect();
+        width = r.width || canvas.clientWidth || width;
+        height = r.height || canvas.clientHeight || height;
+      }
+      dpr = opts.dpr ?? readDpr();
+      applySize();
+      pendingFullReason = "resize";
+      inv.invalidate();
+    },
+    setBackground(color): void {
+      backgroundOverride = color;
+      inv.invalidate();
+    },
+    toSVG(svgOpts) {
+      // Re-runs the pipeline against fresh layers and an SVGRenderer. Reuses
+      // the live atlas so axis labels render. We deliberately use scratch
+      // layers so the on-screen layers aren't disturbed for a frame.
+      const w = svgOpts?.width ?? width;
+      const h = svgOpts?.height ?? height;
+      const svg = createSVGRenderer({ width: w, height: h, dpr: 1 });
+      // Scratch v3 layers carrying the live atlas so axis labels / glyphs export
+      // (v3 has no `renderer.createLayer`/`font`; the atlas is externalized).
+      const a = createLayer({ space: "ui", atlas });
+      const m = createLayer({ space: "ui", atlas });
+      const u = createLayer({ space: "ui", atlas });
+      // Resolve a concrete config for export — re-run the builder so settings
+      // closures pick up the live values.
+      const exportConfig = builder ? configOf(builder()) : activeConfig;
+      const exportData = builder ? currentData(exportConfig.data) : dataSnapshot;
+      const snapshot: ChartConfig<T> = { ...exportConfig, width: w, height: h };
+      runPipeline(snapshot, exportData, a, m, u, atlas);
+      svg.setBackground(
+        backgroundOverride ?? exportConfig.background ?? exportConfig.theme.background,
+      );
+      svg.render([a, m, u]);
+      // v3's `element()` is a method (was a getter property on v1's SVGRenderer).
+      return svg.element();
+    },
+    destroy(): void {
+      if (disposed) return;
+      disposed = true;
+      if (autoFrame && rafId) cancelAnimationFrame(rafId);
+      unsubscribeData?.();
+      resizeObserver?.disconnect();
+      if (visibleHandler && typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", visibleHandler);
+      }
+      if (pendingHoverNullHandle !== null) {
+        clearTimeout(pendingHoverNullHandle);
+        pendingHoverNullHandle = null;
+      }
+      cleanupCursorTracking?.();
+      grammarTooltip?.dispose();
+      grammarCrosshair?.dispose();
+      grammarSelection?.dispose();
+      grammarBrush?.dispose();
+      attachedBrush?.dispose();
+      attachedBrush = null;
+      grammarLegend?.dispose();
+      grammarContextMenu?.dispose();
+      hitLayer?.dispose();
+      manager?.destroy();
+      for (const a of attachedPresets) a.dispose();
+      attachedPresets.clear();
+      for (const r of attachedSeriesReadouts) r.dispose();
+      attachedSeriesReadouts.clear();
+      panZoomUnsub?.();
+      panZoomBinding?.destroy();
+      inv.dispose();
+      // Drop external subscribers held against the public mount handle so
+      // their closures stop pinning mount internals after teardown.
+      hoverSignal.dispose();
+      selectionSignal.dispose();
+      brushedSignal.dispose();
+      hiddenSignal.dispose();
+      // Only destroy what we created. External renderer/atlas/layers belong
+      // to the caller.
+      if (ownedRenderer) renderer.destroy();
+      if (ownedLayers) {
+        axisLayer.destroy();
+        marksLayer.destroy();
+        hudLayer.destroy();
+        overlayLayer.destroy();
+      }
+    },
+
+    // Escape hatches
+    get renderer() {
+      return renderer;
+    },
+    get axisLayer() {
+      return axisLayer;
+    },
+    get marksLayer() {
+      return marksLayer;
+    },
+    get hudLayer() {
+      return hudLayer;
+    },
+    get overlayLayer() {
+      return overlayLayer;
+    },
+    get invalidator() {
+      return inv;
+    },
+    get hovered() {
+      // Narrow to the read-only view so handle consumers can't mutate the
+      // hover state directly. Mutation flows through the pointer pipeline.
+      return {
+        get: () => hoverSignal.get(),
+        peek: () => hoverSignal.peek(),
+        subscribe: (fn: (v: HoveredHit | null) => void) => hoverSignal.subscribe(fn),
+      };
+    },
+    get selected() {
+      // Read-only view + a `clear()` escape hatch (e.g., on Escape key).
+      // Mutation otherwise flows through the click pipeline.
+      return {
+        get: () => selectionSignal.get(),
+        peek: () => selectionSignal.peek(),
+        subscribe: (fn: (v: readonly HoveredHit[]) => void) => selectionSignal.subscribe(fn),
+        clear: () => grammarSelection?.clear(),
+      };
+    },
+    get brushed() {
+      return {
+        get: () => brushedSignal.get(),
+        peek: () => brushedSignal.peek(),
+        subscribe: (fn: (v: readonly HoveredHit[]) => void) => brushedSignal.subscribe(fn),
+        clear: () => grammarBrush?.clear(),
+      };
+    },
+    get hidden() {
+      return {
+        get: () => hiddenSignal.get(),
+        peek: () => hiddenSignal.peek(),
+        subscribe: (fn: (v: ReadonlySet<string>) => void) => hiddenSignal.subscribe(fn),
+        clear: () => {
+          hiddenSignal.set(new Set());
+          inv.invalidate();
+        },
+      };
+    },
+
+    // Stats
+    get width() {
+      return width;
+    },
+    get height() {
+      return height;
+    },
+    get dpr() {
+      return dpr;
+    },
+    get shapeCount() {
+      return (
+        axisLayer.shapeCount + marksLayer.shapeCount + hudLayer.shapeCount + overlayLayer.shapeCount
+      );
+    },
+    get triangleCount() {
+      return (
+        axisLayer.triangleCount +
+        marksLayer.triangleCount +
+        hudLayer.triangleCount +
+        overlayLayer.triangleCount
+      );
+    },
+    get needsFrame() {
+      return inv.dirty || (partial && overlayDirty);
+    },
+    get plotFrame() {
+      return chartPlotFrame;
+    },
+    get viewport() {
+      return panZoomViewport;
+    },
+    attachSeriesReadout(readoutOpts: AttachSeriesReadoutOptions): AttachedSeriesReadout {
+      // Series-readout needs an InteractionManager — auto-create one when the
+      // mount didn't already build one for a tooltip/selection/etc. Same for
+      // the shared hit-layer: high-z hit-cloud events keep the readout's
+      // `cursorX` populated while the cursor is over a real mark.
+      if (!manager) {
+        manager = createInteractionManager(canvas);
+        manager.onChange(() => requestOverlay());
+      }
+      if (!hitLayer) {
+        hitLayer = createGrammarHitLayer({ manager, element: canvas });
+      }
+      const readout = createSeriesReadout(
+        {
+          manager,
+          bounds: () => chartPlotFrame,
+          scales: () => latestScales,
+          theme: () => activeConfig.theme,
+          invalidator: inv,
+          hitLayer,
+        },
+        readoutOpts,
+      );
+      attachedSeriesReadouts.add(readout);
+      // Force a draw so `out.hitTests` flows into the freshly attached readout
+      // (and a freshly created hit-layer, if any). Without this the panel
+      // stays empty until the next pointer move / data change.
+      inv.invalidate();
+      return {
+        peek: () => readout.peek(),
+        subscribe: (fn) => readout.subscribe(fn),
+        dispose: () => {
+          readout.dispose();
+          attachedSeriesReadouts.delete(readout);
+        },
+      };
+    },
+    attachBrush(brushOpts: AttachBrushOptions): AttachedBrush {
+      if (grammarBrush !== null || attachedBrush !== null) {
+        throw new Error(
+          "attachBrush: a brush is already configured on this mount " +
+            "(via `interactions.brush` or a prior `attachBrush` call). " +
+            "Dispose the existing brush before attaching another.",
+        );
+      }
+      // Same lazy-create pattern as `attachSeriesReadout` — a chart with no
+      // other interactions can still attach a brush after mount.
+      if (!manager) {
+        manager = createInteractionManager(canvas);
+        manager.onChange(() => requestOverlay());
+      }
+      const attached = createAttachedBrush(
+        {
+          manager,
+          // Brush operates on the chart-wide plot frame (matches the
+          // `interactions.brush` path).
+          bounds: () => chartPlotFrame,
+          hudLayer: () => overlayLayer,
+          theme: () => activeConfig.theme,
+          invalidator: overlayInv,
+        },
+        {
+          ...brushOpts,
+          onSelect: (hits) => {
+            // Fan-out to both the mount-level signal (so `MountedPlot.brushed`
+            // observers see the same payload as the declarative brush path)
+            // and the user's onSelect callback.
+            brushedSignal.set(hits);
+            brushOpts.onSelect?.(hits);
+            requestOverlay();
+          },
+        },
+      );
+      attachedBrush = attached;
+      inv.invalidate();
+      return {
+        peek: () => brushedSignal.peek(),
+        rect: () => attached.rect(),
+        subscribe: (fn) => brushedSignal.subscribe(fn),
+        clear: () => attached.clear(),
+        dispose: () => {
+          attached.dispose();
+          if (attachedBrush === attached) attachedBrush = null;
+          if (brushedSignal.peek().length > 0) brushedSignal.set([]);
+        },
+      };
+    },
+    pickAt(canvasX: number, canvasY: number) {
+      return screenToData(canvasX, canvasY, {
+        frame: chartPlotFrame,
+        scales: latestScales,
+        coord: activeConfig.coord,
+      });
+    },
+    attachRangePresets(presetOpts: AttachRangePresetsOptions): AttachedRangePresets {
+      if (!panZoomViewport) {
+        throw new Error(
+          "attachRangePresets: panZoom must be enabled on mount() to drive a range-preset controller.",
+        );
+      }
+      const attached = attachRangePresetsHelper(panZoomViewport, activeConfig.theme, presetOpts);
+      attachedPresets.add(attached);
+      return {
+        setActive: (k) => attached.setActive(k),
+        getActive: () => attached.getActive(),
+        subscribe: (fn) => attached.subscribe(fn),
+        dispose: () => {
+          attached.dispose();
+          attachedPresets.delete(attached);
+        },
+      };
+    },
+
+    // Transitions handle
+    get transitions() {
+      return {
+        requestTransition: () => {
+          if (!activeConfig.theme.motion.enabled) return;
+          grammarTransitions?.requestTransition();
+          inv.invalidate();
+        },
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Charts produced by `plot()` carry their frozen `ChartConfig` on a non-
+ * enumerable internal property (`__config__`). The mount needs that config
+ * to compile the spec, but we don't want it visible on the public `Chart<T>`
+ * interface — the export here keeps the cast in one place.
+ */
+interface ChartWithConfig<T> extends Chart<T> {
+  readonly __config__: ChartConfig<T>;
+}
+
+function configOf<T>(chart: Chart<T>): ChartConfig<T> {
+  const c = (chart as ChartWithConfig<T>).__config__;
+  if (!c) {
+    throw new Error(
+      "Chart is missing internal config — was it produced by plot()? " +
+        "If you're constructing a chart manually, ensure makeChart() is used.",
+    );
+  }
+  return c;
+}
+
+function readDpr(): number {
+  if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+    return window.devicePixelRatio || 1;
+  }
+  return 1;
+}
+
+interface ResolvedPanZoom {
+  minZoom: number;
+  maxZoom: number;
+  panBounds: DataPanBoundsOptions | undefined;
+  pan: AxisSelection;
+  zoom: AxisSelection;
+  /** Half-padding fraction applied around the visible-Y extent, or null when yFit is off. */
+  yFitPadding: number | null;
+}
+
+function resolvePanZoom(input: boolean | PanZoomConfig | undefined): ResolvedPanZoom | null {
+  if (!input) return null;
+  const cfg: PanZoomConfig = input === true ? {} : input;
+
+  // yFit forces X-only pan/zoom — Y becomes derived state.
+  const yFit = cfg.yFit;
+  let yFitPadding: number | null = null;
+  if (yFit) {
+    const raw = yFit === true ? DEFAULT_Y_FIT_PADDING : (yFit.padding ?? DEFAULT_Y_FIT_PADDING);
+    if (!Number.isFinite(raw) || raw < 0 || raw > 0.5) {
+      throw new Error(`panZoom.yFit.padding must be in [0, 0.5] (got ${raw}).`);
+    }
+    yFitPadding = raw;
+  }
+
+  const pan: AxisSelection = yFitPadding !== null ? "x" : (cfg.pan ?? "xy");
+  const zoom: AxisSelection = yFitPadding !== null ? "x" : (cfg.zoom ?? "xy");
+
+  const panBounds: DataPanBoundsOptions | undefined =
+    cfg.panBounds === false ? undefined : (cfg.panBounds ?? DEFAULT_PAN_BOUNDS);
+
+  return {
+    minZoom: cfg.minZoom ?? 1,
+    maxZoom: cfg.maxZoom ?? 100,
+    panBounds,
+    pan,
+    zoom,
+    yFitPadding,
+  };
+}
+
+/**
+ * Walk each layer's x/y accessors, find data points whose X falls inside
+ * `visibleX`, and return `[yMin - pad, yMax + pad]`. Returns `null` when no
+ * layer / no point falls in range — callers should keep the previous Y
+ * window rather than collapsing.
+ */
+function computeVisibleYExtent<T>(
+  layers: ReadonlyArray<{ channels: { x?: unknown; y?: unknown } }>,
+  data: readonly T[],
+  visibleX: readonly [number, number],
+  padding: number,
+): readonly [number, number] | null {
+  if (data.length === 0 || layers.length === 0) return null;
+  const lo = Math.min(visibleX[0], visibleX[1]);
+  const hi = Math.max(visibleX[0], visibleX[1]);
+  let yMin = Infinity;
+  let yMax = -Infinity;
+  let seen = false;
+  for (const layer of layers) {
+    const cx = layer.channels.x;
+    const cy = layer.channels.y;
+    if (cx === undefined || cy === undefined) continue;
+    // Array-shaped channels (stacked / multi-series) — skip; yFit on a stack
+    // would need separate per-series logic and isn't supported in v1.
+    if (Array.isArray(cx) || Array.isArray(cy)) continue;
+    const ax = resolveAes<T, unknown>(cx as Aes<T, unknown>);
+    const ay = resolveAes<T, unknown>(cy as Aes<T, unknown>);
+    for (let i = 0; i < data.length; i++) {
+      const xv = toNumeric(ax.fn(data[i]!, i));
+      if (xv === null || xv < lo || xv > hi) continue;
+      const yv = toNumeric(ay.fn(data[i]!, i));
+      if (yv === null) continue;
+      if (yv < yMin) yMin = yv;
+      if (yv > yMax) yMax = yv;
+      seen = true;
+    }
+  }
+  if (!seen) return null;
+  if (yMin === yMax) {
+    // Singleton — pad against an absolute baseline so the axis has range.
+    const pad = Math.abs(yMin) * padding || 1;
+    return [yMin - pad, yMax + pad];
+  }
+  const span = yMax - yMin;
+  const pad = span * padding;
+  return [yMin - pad, yMax + pad];
+}
+
+function toNumeric(v: unknown): number | null {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (v instanceof Date) {
+    const t = v.getTime();
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+
+/**
+ * Screen → data primitive backing `MountedPlot.pickAt`. Extracted so it can be
+ * unit-tested without spinning up a full mount (WebGPU device, layers, etc.).
+ *
+ * Returns `null` when the point is outside the frame, when `coord.unproject`
+ * rejects the point (polar outside the radius band), when scales are not yet
+ * available (pre-first-draw), or when either position scale lacks `invert`
+ * (band scales — band → continuous picking is a separate problem).
+ */
+function screenToData(
+  canvasX: number,
+  canvasY: number,
+  ctx: {
+    frame: Frame;
+    scales: import("./geoms/types.ts").ScaleBundle | null;
+    coord: Coord;
+  },
+): {
+  plotFrameX: number;
+  plotFrameY: number;
+  dataX: number;
+  dataY: number;
+  frame: Frame;
+} | null {
+  const { frame, scales, coord } = ctx;
+  if (frame.width <= 0 || frame.height <= 0) return null;
+  if (!scales) return null;
+  const xAxis = scales.x.axisScale as { invert?: (v: number) => unknown };
+  const yAxis = scales.y.axisScale as { invert?: (v: number) => unknown };
+  if (typeof xAxis.invert !== "function" || typeof yAxis.invert !== "function") {
+    return null;
+  }
+  // Plot-frame-relative pixel position.
+  const pfx = canvasX - frame.x;
+  const pfy = canvasY - frame.y;
+  // Outside the frame → no hit.
+  if (pfx < 0 || pfx > frame.width || pfy < 0 || pfy > frame.height) return null;
+  // Route through the active coord's unproject. For Cartesian this is the
+  // identity; for polar/radial it inverts the projection and returns null
+  // outside `[innerRadius, outerRadius]`. The pipeline ensures the coord is
+  // `bindFrame`-bound to the current `plotFrame` before each draw, so its
+  // internal centre/outerR match what's on screen.
+  const unprojected = coord.unproject({ x: pfx, y: pfy });
+  if (!unprojected) return null;
+  const dataX = xAxis.invert(unprojected.x) as number;
+  const dataY = yAxis.invert(unprojected.y) as number;
+  if (!Number.isFinite(dataX) || !Number.isFinite(dataY)) return null;
+  return {
+    plotFrameX: unprojected.x,
+    plotFrameY: unprojected.y,
+    dataX,
+    dataY,
+    frame,
+  };
+}
+
+/** @internal — exposed for unit tests only. */
+export const __test__ = {
+  resolvePanZoom,
+  computeVisibleYExtent,
+  wrapViewportThroughCoord,
+  screenToData,
+};
+
+interface ResolvedInteractions {
+  tooltip: false | TooltipConfig;
+  crosshair: false | CrosshairConfig;
+  selection: false | SelectionConfig;
+  brush: false | BrushConfig;
+  legend: false | LegendInteractionConfig;
+  contextMenu: false | ContextMenuConfig;
+}
+
+function resolveInteractions(
+  input: MountPlotOptions<unknown>["interactions"],
+): ResolvedInteractions {
+  // Selection, brush, and context menu are opt-in: not enabled by `true` /
+  // `undefined` shorthand, because their semantics are app-specific (the
+  // context menu in particular has no useful default without an `onTrigger`).
+  if (input === false) {
+    return {
+      tooltip: false,
+      crosshair: false,
+      selection: false,
+      brush: false,
+      legend: false,
+      contextMenu: false,
+    };
+  }
+  if (input === undefined || input === true) {
+    return {
+      tooltip: {},
+      crosshair: {},
+      selection: false,
+      brush: false,
+      legend: {},
+      contextMenu: false,
+    };
+  }
+  const cfg: InteractionsConfig = input;
+  return {
+    tooltip: resolveDefaultOn(cfg.tooltip),
+    crosshair: resolveDefaultOn(cfg.crosshair),
+    selection: resolveOptIn(cfg.selection),
+    brush: resolveOptIn(cfg.brush),
+    legend: resolveDefaultOn(cfg.legend),
+    // Context menu requires an `onTrigger` to be useful, so we only honor
+    // the object form. Boolean shorthands have no sensible default.
+    contextMenu: cfg.contextMenu ?? false,
+  };
+}
+
+// Default-on channels (tooltip/crosshair/legend): undefined or true → {}.
+function resolveDefaultOn<C>(input: C | boolean | undefined): false | C {
+  if (input === false) return false;
+  if (input === undefined || input === true) return {} as C;
+  return input;
+}
+
+// Opt-in channels (selection/brush): undefined or false → off; true → {}.
+function resolveOptIn<C>(input: C | boolean | undefined): false | C {
+  if (!input) return false;
+  if (input === true) return {} as C;
+  return input;
+}
+
+function resolveTransitionsCfg(
+  input: MountPlotOptions<unknown>["transitions"],
+): false | TransitionsConfig {
+  if (input === false) return false;
+  if (input === undefined || input === true) return {};
+  return input;
+}
+
+const SCALE_OVERRIDE_KEYS = [
+  "x",
+  "y",
+  "color",
+  "size",
+  "alpha",
+  "shape",
+  "borderStyle",
+  "overlayGlyph",
+] as const;
+
+/**
+ * Wrap a `DataViewport` so pan/zoom calls flow through `coord.handlePan` /
+ * `coord.handleZoom`. The wrapper is `Object.create(underlying)` — every
+ * untouched member (state, visibleXDomain, absoluteFrame, setFrame, …)
+ * resolves through the prototype, so the wrapper stays in lockstep with the
+ * underlying `DataViewport` API. Only `panBy` and `zoomAt` are overridden.
+ *
+ * `getCoord` is called at-the-event-time so `update()` swapping the chart
+ * spec (and its `coord`) takes effect on the next interaction without a
+ * remount. `invalidate` fires after each routed call because polar's
+ * `handlePan` may mutate its own `startAngle` without touching the viewport —
+ * which means the viewport's own `onChange` won't fire, and the rAF loop
+ * needs an explicit kick to re-draw the rotated chart.
+ */
+function wrapViewportThroughCoord<X, Y>(
+  underlying: DataViewport<X, Y>,
+  getCoord: () => Coord,
+  invalidate: () => void,
+): DataViewport<X, Y> {
+  const wrapped = Object.create(underlying) as DataViewport<X, Y>;
+  // Build a stable handle the coord uses to mutate scale state. Reading the
+  // bound methods up front avoids `this`-binding surprises since `Object.create`
+  // child lookups would otherwise call them with `this === wrapped` (whose
+  // `panBy` is our override — infinite loop).
+  const handle = {
+    panBy: (dx: number, dy: number) => underlying.panBy(dx, dy),
+    zoomAt: (ax: number, ay: number, f: number | { x?: number; y?: number }) =>
+      underlying.zoomAt(ax, ay, f),
+  };
+  Object.defineProperty(wrapped, "panBy", {
+    value: (dx: number, dy: number) => {
+      getCoord().handlePan({ dx, dy, plotFrame: underlying.frame, viewport: handle });
+      invalidate();
+    },
+  });
+  Object.defineProperty(wrapped, "zoomAt", {
+    value: (anchorSx: number, anchorSy: number, factor: number | { x?: number; y?: number }) => {
+      getCoord().handleZoom({
+        factor,
+        cx: anchorSx,
+        cy: anchorSy,
+        plotFrame: underlying.frame,
+        viewport: handle,
+      });
+      invalidate();
+    },
+  });
+  return wrapped;
+}