insomni-plot 0.1.0-alpha.0

package/src/grammar/interactions/tooltip.ts

@@ -0,0 +1,622 @@
+// ---------------------------------------------------------------------------
+// Grammar-level tooltip wiring
+// ---------------------------------------------------------------------------
+// Subscribes to the shared `GrammarHitLayer` for hover enter/leave events;
+// builds a TooltipContent from the geom's resolved aesthetics and drives
+// insomni's generic `Tooltip` primitive. The hit-layer owns the spatial
+// grids (one per geom regardless of how many consumers attach).
+
+import {
+  type Color,
+  createTooltip,
+  type GlyphAtlas,
+  type Invalidator,
+  type Layer,
+  type Tooltip,
+  type TooltipBounds,
+  type TooltipContent,
+  type TooltipMeasure,
+  type TooltipRow,
+} from "insomni";
+import type {
+  AxisTooltipContentResolver,
+  AxisTooltipInfo,
+  AxisTooltipRow,
+  TooltipContentInfo,
+  TooltipContentResolver,
+  TooltipContentResult,
+  TooltipContentShorthand,
+  TooltipShorthandRow,
+} from "../chart.ts";
+import type { CompiledHitTest, HoveredHit, ResolvedChannelMap, ScaleBundle } from "../geoms/types.ts";
+import { computeSnap, resolveGroupColor, type SnapGroup, type SnapResult } from "./series-snap.ts";
+import type { Theme } from "../theme.ts";
+import type { GrammarHitLayer, HitEventContext } from "./hit-layer.ts";
+import { createDisposable } from "./_disposable.ts";
+import { TEXT_WIDTH_FALLBACK_RATIO } from "../../format.ts";
+
+export interface GrammarTooltipOptions {
+  /** Hover-intent delay before showing (ms). Default from theme.motion.tooltip.showDelay. */
+  showDelay?: number;
+  /** Linger before hiding (ms). Default from theme.motion.tooltip.hideDelay. */
+  hideDelay?: number;
+  /** Fade duration (ms). 0 disables. Default from theme.motion.tooltip.fadeMs. */
+  fadeMs?: number;
+  /**
+   * Hover-intent settle (ms). Coalesces rapid enter/leave/switch events so the
+   * tooltip only commits a show/hide once the cursor holds a target this long —
+   * sweeping across a dense mark grid or through gaps no longer fires an overlay
+   * re-render per cell. 0 disables (commit immediately).
+   * Default from theme.motion.tooltip.settleDelay.
+   */
+  settleDelay?: number;
+  /** Override placement. Default "top". */
+  placement?: "top" | "bottom" | "left" | "right" | "auto";
+  /**
+   * Consumer-supplied content resolver. Returning a string / shorthand
+   * overrides the auto-built channel rows; returning null / undefined falls
+   * back to the default builder.
+   */
+  content?: TooltipContentResolver;
+  /**
+   * Optional secondary observer fired alongside the tooltip's own show/hide.
+   * Receives the active `HoveredHit` (geom kind, data array reference, data
+   * index, snapped position) on enter, and `null` on leave. Used by the
+   * grammar crosshair to track hit positions, and by the mount to publish
+   * `hovered` as a public signal.
+   *
+   * Also fires on touch-tap (`onPress`) since that path calls `commit` which
+   * calls this callback, bypassing the settle debounce.
+   */
+  onHover?(info: HoveredHit | null): void;
+  /**
+   * Trigger model. Default `"item"` (one box per hovered mark — unchanged).
+   * `"axis"` = floating unified readout snapping to the nearest data column.
+   */
+  trigger?: "item" | "axis";
+  /** Snap axis for `trigger:"axis"`. Default `"x"`. */
+  axis?: "x" | "y";
+  /** Axis-mode content hook (replaces the auto rows when it returns a shorthand). */
+  axisContent?: AxisTooltipContentResolver;
+  /** Format the snapped column value (title) in axis mode. */
+  axisTitleFormat?: (v: unknown) => string;
+  /** Format each auto-built row's value in axis mode. */
+  axisValueFormat?: (v: unknown) => string;
+}
+
+export interface GrammarTooltipDeps {
+  hitLayer: GrammarHitLayer;
+  hudLayer: () => Layer;
+  atlas: () => GlyphAtlas | undefined;
+  theme: () => Theme;
+  bounds: () => TooltipBounds;
+  invalidator: Invalidator;
+  /**
+   * Optional: current cursor position in element-local CSS px. When provided,
+   * the tooltip anchor follows the cursor every frame while visible — no need
+   * to wait for a cell-transition enter event.
+   */
+  pointerPos?: () => { x: number; y: number } | null;
+  /** Latest resolved scales (axis-mode swatch resolution). Optional. */
+  scales?: () => ScaleBundle | null;
+  /**
+   * Axis-mode pointer source: a full-frame interaction node registered by the
+   * mount. The tooltip subscribes for cursor tracking when `trigger:"axis"`.
+   * Returns an unregister fn.
+   */
+  onAxisPointer?: (handlers: {
+    move(p: { x: number; y: number }): void;
+    leave(): void;
+  }) => () => void;
+}
+
+export interface GrammarTooltip {
+  /** Tick opacity + delay timers. */
+  step(dt: number): void;
+  /** Draw into the hud layer. */
+  draw(): void;
+  dispose(): void;
+  /** Push fresh compiled hit-tests (axis mode only; item mode ignores). */
+  syncHits?<T>(hits: readonly CompiledHitTest<T>[]): void;
+}
+
+const CHANNEL_ORDER = ["x", "y", "color", "size", "shape", "alpha"] as const;
+type ChannelKey = (typeof CHANNEL_ORDER)[number];
+
+/**
+ * Best-effort default formatter. Numbers go through `Intl.NumberFormat` with
+ * adaptive precision; Dates through ISO; booleans/strings stringify.
+ */
+export function defaultFormat(value: unknown): string {
+  if (value === null || value === undefined) return "—";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return String(value);
+    const abs = Math.abs(value);
+    // Use exponential only for values that would lose precision or produce
+    // absurdly long decimal strings. 1e-6 matches scientific conventions.
+    if (abs !== 0 && (abs < 1e-6 || abs >= 1e7)) {
+      return value.toExponential(3);
+    }
+    const digits = abs >= 100 ? 0 : abs >= 10 ? 1 : abs >= 1 ? 2 : 3;
+    return value.toLocaleString(undefined, { maximumFractionDigits: digits });
+  }
+  if (value instanceof Date) {
+    if (!Number.isFinite(value.getTime())) return "—";
+    // Include time component when the date has a non-midnight time.
+    const s = value.toISOString();
+    const hms = s.slice(11, 19);
+    return hms === "00:00:00" ? s.slice(0, 10) : s.slice(0, 10) + " " + hms;
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "symbol") return value.description ?? "Symbol()";
+  // oxlint-disable-next-line no-base-to-string
+  return String(value);
+}
+
+function buildDefaultContent<T>(hit: CompiledHitTest<T>, hitIndex: number): TooltipContent {
+  const dataIdx = hit.dataIndex[hitIndex]!;
+  const seriesKey = hit.seriesKey?.[hitIndex];
+  const datum = hit.data[dataIdx]!;
+  const rows: TooltipRow[] = [];
+  if (seriesKey !== undefined) {
+    rows.push({ label: "series", value: seriesKey });
+    const value = (datum as Record<string, unknown>)[seriesKey];
+    if (value !== undefined) rows.push({ label: "value", value: defaultFormat(value) });
+  }
+  const channels = hit.channels as ResolvedChannelMap<T>;
+  for (const key of CHANNEL_ORDER) {
+    const aes = channels[key as ChannelKey];
+    if (!aes) continue;
+    if (aes.kind === "constant") continue;
+    const label = aes.column ?? key;
+    const raw = aes.fn(datum, dataIdx);
+    rows.push({
+      label,
+      value: defaultFormat(raw),
+    });
+  }
+  return {
+    title: hit.label,
+    rows,
+  };
+}
+
+function isColor(v: unknown): v is Color {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { r?: unknown }).r === "number" &&
+    typeof (v as { g?: unknown }).g === "number" &&
+    typeof (v as { b?: unknown }).b === "number"
+  );
+}
+
+function resolveAccent(
+  accent: TooltipShorthandRow["accent"],
+  accents: Theme["interactions"]["tooltipAccents"],
+): Color | undefined {
+  if (accent === undefined) return undefined;
+  if (accent === "neutral") return undefined;
+  if (accent === "positive") return accents.positive;
+  if (accent === "negative") return accents.negative;
+  if (isColor(accent)) return accent;
+  return undefined;
+}
+
+function normalizeShorthandValue(value: TooltipShorthandRow["value"]): string {
+  if (typeof value === "string") return value;
+  return defaultFormat(value);
+}
+
+/**
+ * Normalize a consumer-supplied resolver result into the canvas tooltip's
+ * `TooltipContent` shape. Returns null if the result is null/undefined so the
+ * caller can fall through to the default builder.
+ *
+ * - `string` → single value-only row.
+ * - `{ title, rows }` shorthand → rows mapped through the default formatter
+ *   (strings pass through) with accent → row color via theme.
+ *
+ * Exported for tests and for reuse by alternative tooltip hosts.
+ */
+export function normalizeTooltipContent(
+  result: TooltipContentResult | null | undefined,
+  theme: Theme,
+): TooltipContent | null {
+  if (result === null || result === undefined) return null;
+  if (typeof result === "string") {
+    // Empty string → fall back to the default builder.
+    if (result === "") return null;
+    return { rows: [{ value: result }] };
+  }
+  const shorthand: TooltipContentShorthand = result;
+  if (!Array.isArray(shorthand.rows) || shorthand.rows.length === 0) {
+    // Missing or empty rows → fall back.
+    return null;
+  }
+  const accents = theme.interactions.tooltipAccents;
+  const rows: TooltipRow[] = shorthand.rows.map((r) => {
+    const row: TooltipRow = { value: normalizeShorthandValue(r.value) };
+    if (r.label !== undefined) row.label = r.label;
+    if (r.swatch !== undefined) row.swatch = r.swatch;
+    const tint = resolveAccent(r.accent, accents);
+    if (tint !== undefined) row.color = tint;
+    return row;
+  });
+  return shorthand.title !== undefined ? { title: shorthand.title, rows } : { rows };
+}
+
+function buildInfo<T>(hit: CompiledHitTest<T>, hitIndex: number): TooltipContentInfo<T> {
+  const dataIdx = hit.dataIndex[hitIndex]!;
+  return {
+    datum: hit.data[dataIdx]!,
+    dataIndex: dataIdx,
+    mark: hit.label ?? hit.geomKind,
+    seriesKey: hit.seriesKey?.[hitIndex],
+    channels: hit.channels as Readonly<Record<string, unknown>>,
+  };
+}
+
+/**
+ * Resolve final tooltip content for a hit: run the consumer resolver if any,
+ * normalize the result, and fall back to the default channel-driven content
+ * when the resolver returns null/undefined.
+ */
+export function resolveTooltipContent<T>(
+  hit: CompiledHitTest<T>,
+  hitIndex: number,
+  theme: Theme,
+  resolver?: TooltipContentResolver,
+): TooltipContent {
+  if (resolver) {
+    const raw = resolver(buildInfo(hit, hitIndex) as TooltipContentInfo<unknown>);
+    const normalized = normalizeTooltipContent(raw, theme);
+    if (normalized !== null) return normalized;
+  }
+  return buildDefaultContent(hit, hitIndex);
+}
+
+/**
+ * Build the axis-mode tooltip content from a snap result. Pure (no GPU / no
+ * closure state) so it is unit-testable. For `axis:"x"` each auto row's value
+ * is the series Y; for `axis:"y"` it is the series X. When `axisContent`
+ * returns a shorthand it REPLACES the auto rows (normalized through the theme).
+ */
+export function buildAxisTooltipContent(args: {
+  result: SnapResult;
+  axis: "x" | "y";
+  scales: ScaleBundle | null;
+  theme: Theme;
+  titleFormat: (v: unknown) => string;
+  valueFormat: (v: unknown) => string;
+  axisContent?: AxisTooltipContentResolver;
+}): TooltipContent {
+  const { result, axis, scales, theme, titleFormat, valueFormat, axisContent } = args;
+  const autoRows: AxisTooltipRow[] = result.groups.map((g) => {
+    const raw = axis === "y" ? g.xValue : g.yValue;
+    const row: AxisTooltipRow = {
+      label: g.label,
+      value: valueFormat(raw),
+      rawValue: raw,
+      active: g.id === result.activeId,
+    };
+    const color = g.color ?? resolveGroupColor(g, scales);
+    if (color) row.color = color;
+    if (g.seriesKey !== undefined) row.seriesKey = g.seriesKey;
+    return row;
+  });
+  const columnLabel = titleFormat(result.columnValue);
+  if (axisContent) {
+    const info: AxisTooltipInfo = {
+      columnValue: result.columnValue,
+      columnLabel,
+      axis,
+      rows: autoRows,
+      data: result.groups.map((g) => {
+        const dataIdx = g.hit.dataIndex[g.index]!;
+        return {
+          datum: g.hit.data[dataIdx],
+          dataIndex: dataIdx,
+          mark: g.hit.label ?? g.hit.geomKind,
+        };
+      }),
+    };
+    const normalized = normalizeTooltipContent(axisContent(info) ?? null, theme);
+    if (normalized !== null) return normalized;
+  }
+  return {
+    title: columnLabel,
+    rows: autoRows.map((r) => {
+      const row: TooltipRow = { label: r.label, value: r.value };
+      if (r.color) row.swatch = r.color;
+      return row;
+    }),
+  };
+}
+
+/** Project a snap group's picked hit to a `HoveredHit` (for crosshair snap). */
+export function hoveredHitFromGroup(g: SnapGroup): HoveredHit {
+  const dataIdx = g.hit.dataIndex[g.index]!;
+  const h: HoveredHit = {
+    geomKind: g.hit.geomKind,
+    dataIndex: dataIdx,
+    data: g.hit.data,
+    x: g.hit.positions[g.index * 2]!,
+    y: g.hit.positions[g.index * 2 + 1]!,
+  };
+  if (g.seriesKey !== undefined) h.seriesKey = g.seriesKey;
+  return h;
+}
+
+export function createGrammarTooltip(
+  deps: GrammarTooltipDeps,
+  opts: GrammarTooltipOptions = {},
+): GrammarTooltip {
+  // The atlas is resolved lazily — on the first frame the font may not be
+  // ready yet, so `measure` falls back to a rough estimate based on font size.
+  const measure: TooltipMeasure = (text, fontSize) => {
+    const a = deps.atlas();
+    if (a) return a.measureText(text, { fontSize, simple: true });
+    return { width: text.length * fontSize * TEXT_WIDTH_FALLBACK_RATIO, height: fontSize };
+  };
+
+  const motion = deps.theme().motion.tooltip;
+  const tooltip: Tooltip = createTooltip({
+    placement: opts.placement ?? "top",
+    bounds: deps.bounds,
+    measure,
+    showDelay: opts.showDelay ?? motion.showDelay,
+    hideDelay: opts.hideDelay ?? motion.hideDelay,
+    fadeMs: opts.fadeMs ?? motion.fadeMs,
+    invalidator: deps.invalidator,
+  });
+
+  const onHover = opts.onHover ? (info: HoveredHit | null) => opts.onHover!(info) : undefined;
+  const resolver = opts.content;
+
+  // ---- hover-intent settle (debounce) ----
+  // The hit fan-out fires enter/leave on every cell *transition*. We coalesce
+  // events into a single `pending` target and only commit it once the cursor
+  // has held that target for `settle` seconds — but only for cold-start
+  // appears (tooltip is hidden and was not recently visible) and for leaves.
+  // When the tooltip is already on screen (opacity > 0) or was recently hidden
+  // (cursor just crossed a narrow gap), enters commit immediately so switching
+  // between adjacent data points feels snappy and the tooltip never blinks out
+  // on brief gap crossings. The countdown is driven by `step(dt)`.
+  const settle = Math.max(0, opts.settleDelay ?? motion.settleDelay) / 1000;
+  type EnterPayload = {
+    kind: "enter";
+    /** Lazy so item mode builds content in commit() exactly as before. */
+    buildContent: () => TooltipContent;
+    anchor: { x: number; y: number };
+    hit: HoveredHit | null;
+  };
+  type Pending = EnterPayload | { kind: "leave" };
+  let pending: Pending | null = null;
+  let settleRemaining = 0;
+  // Temporal window (seconds) for the just-hid grace — after a hide the
+  // tooltip remains responsive for this long before cold-start settle kicks
+  // in again. Prevents flicker on gap crossings while still applying settle
+  // for truly fresh entries (e.g., re-entering from outside the chart).
+  const JUST_HID_GRACE_S = 0.3;
+  let justHid = false;
+  let justHidTimer = 0;
+  let lastTrackedAnchor: { x: number; y: number } | null = null;
+
+  function commit(p: Pending, fireHover: boolean = true): void {
+    pending = null;
+    settleRemaining = 0;
+    if (p.kind === "enter") {
+      justHid = false;
+      justHidTimer = 0;
+      const content = p.buildContent();
+      const anchor = p.anchor;
+      lastTrackedAnchor = anchor;
+      tooltip.show(anchor, content);
+      if (fireHover) onHover?.(p.hit);
+    } else {
+      justHid = true;
+      justHidTimer = 0;
+      lastTrackedAnchor = null;
+      tooltip.hide();
+      onHover?.(null);
+    }
+  }
+
+  function schedule(p: Pending): void {
+    if (settle <= 0) {
+      commit(p);
+      return;
+    }
+    // Skip settle when the tooltip is on screen (switching between points) or
+    // was recently hidden (re-entering after a brief gap crossing). This
+    // prevents the tooltip from blinking out when the cursor passes through a
+    // narrow gap between adjacent data-point regions.
+    if (p.kind === "enter" && (tooltip.opacity > 0 || justHid)) {
+      // Clear any stale pending (e.g. a leave that was mid-settle) so the
+      // settle timer doesn't fire a stale commit later.
+      pending = null;
+      commit(p);
+      return;
+    }
+    // Cold-start enter: fire onHover immediately so crosshair and hover
+    // emphasis update right away, while still deferring the tooltip box
+    // through the settle window.
+    if (p.kind === "enter") {
+      onHover?.(p.hit);
+    }
+    pending = p;
+    settleRemaining = settle;
+  }
+
+  const axisMode = opts.trigger === "axis";
+  const axisAxis: "x" | "y" = opts.axis ?? "x";
+  const axisTitleFormat = opts.axisTitleFormat ?? defaultFormat;
+  const axisValueFormat = opts.axisValueFormat ?? defaultFormat;
+  let axisHits: readonly CompiledHitTest<unknown>[] = [];
+  let axisCursor: { x: number; y: number } | null = null;
+
+  function itemEnter(ctx: HitEventContext): EnterPayload {
+    return {
+      kind: "enter",
+      buildContent: () => resolveTooltipContent(ctx.compiled, ctx.hitIndex, deps.theme(), resolver),
+      anchor: { x: ctx.pointer.x, y: ctx.pointer.y },
+      hit: ctx.hit,
+    };
+  }
+
+  function recomputeAxis(immediate: boolean = false): void {
+    if (d.isDisposed) return;
+    if (axisCursor === null || axisHits.length === 0) {
+      schedule({ kind: "leave" });
+      return;
+    }
+    const cursor = axisAxis === "y" ? axisCursor.y : axisCursor.x;
+    const result = computeSnap({
+      hits: axisHits,
+      cursor,
+      axis: axisAxis,
+      snap: "nearest-x",
+      active: deps.hitLayer.state().active,
+    });
+    if (result === null) {
+      schedule({ kind: "leave" });
+      return;
+    }
+    const content = buildAxisTooltipContent({
+      result,
+      axis: axisAxis,
+      scales: deps.scales?.() ?? null,
+      theme: deps.theme(),
+      titleFormat: axisTitleFormat,
+      valueFormat: axisValueFormat,
+      axisContent: opts.axisContent,
+    });
+    const activeGroup = result.groups.find((g) => g.id === result.activeId) ?? null;
+    const payload: EnterPayload = {
+      kind: "enter",
+      buildContent: () => content,
+      anchor: { x: axisCursor!.x, y: axisCursor!.y },
+      hit: activeGroup ? hoveredHitFromGroup(activeGroup) : null,
+    };
+    if (immediate) {
+      pending = null;
+      settleRemaining = 0;
+      commit(payload);
+    } else {
+      schedule(payload);
+    }
+  }
+
+  let unsubscribe: () => void;
+  let unsubscribeAxisState: (() => void) | undefined;
+  let unregisterAxisPointer: (() => void) | undefined;
+  if (!axisMode) {
+    unsubscribe = deps.hitLayer.subscribe({
+      key: "tooltip",
+      onHoverEnter(ctx: HitEventContext) {
+        schedule(itemEnter(ctx));
+      },
+      onHoverLeave() {
+        schedule({ kind: "leave" });
+      },
+      onPress(ctx: HitEventContext) {
+        // Touch tap: commit immediately, bypassing settle.
+        pending = null;
+        settleRemaining = 0;
+        commit(itemEnter(ctx));
+      },
+    });
+  } else {
+    // Axis mode: dual cursor source (hit-layer enter for over-a-mark, full-frame
+    // pointer node for bare-frame), mirroring series-readout. state() drives
+    // recompute when the active hit changes.
+    unsubscribe = deps.hitLayer.subscribe({
+      key: "tooltip-axis",
+      onHoverEnter(ctx: HitEventContext) {
+        axisCursor = { x: ctx.pointer.x, y: ctx.pointer.y };
+        recomputeAxis();
+      },
+      onPress(ctx: HitEventContext) {
+        axisCursor = { x: ctx.pointer.x, y: ctx.pointer.y };
+        recomputeAxis(/*immediate=*/ true);
+      },
+    });
+    unsubscribeAxisState = deps.hitLayer.subscribeState(() => recomputeAxis());
+    unregisterAxisPointer = deps.onAxisPointer?.({
+      move: (p) => {
+        axisCursor = { x: p.x, y: p.y };
+        recomputeAxis();
+      },
+      leave: () => {
+        axisCursor = null;
+        schedule({ kind: "leave" });
+      },
+    });
+  }
+
+  const d = createDisposable(() => {
+    unsubscribe();
+    unsubscribeAxisState?.();
+    unregisterAxisPointer?.();
+    pending = null;
+    tooltip.dispose();
+  });
+
+  return {
+    step(dt) {
+      if (d.isDisposed) return;
+      if (pending !== null && dt > 0) {
+        settleRemaining -= dt;
+        if (settleRemaining <= 0) {
+          const p = pending;
+          pending = null;
+          // Cold-start enters already fired onHover in schedule(); don't
+          // re-fire it here so crosshair/hoverSignal aren't doubled.
+          commit(p, /*fireHover=*/ p.kind !== "enter");
+        }
+      }
+      // Decay the just-hid grace window. After JUST_HID_GRACE_S seconds
+      // without an enter, cold-start settle re-activates.
+      if (justHid && dt > 0) {
+        justHidTimer += dt;
+        if (justHidTimer >= JUST_HID_GRACE_S) {
+          justHid = false;
+          justHidTimer = 0;
+        }
+      }
+      // While visible OR logically requested (show-delay fade-in), track
+      // cursor movement so the tooltip follows the pointer even within the
+      // same data cell (where no enter/leave fires). Using `requested`
+      // instead of `opacity > 0` ensures tracking works during the show-delay
+      // fade-in, preventing a 1-frame jump when the tooltip first appears.
+      // Use `visible` (logical requested state, not just opacity > 0) so
+      // tracking works during the show-delay fade-in, preventing a 1-frame
+      // jump when the tooltip first appears.
+      if (tooltip.visible && deps.pointerPos) {
+        const pos = deps.pointerPos();
+        if (
+          pos &&
+          (!lastTrackedAnchor || pos.x !== lastTrackedAnchor.x || pos.y !== lastTrackedAnchor.y)
+        ) {
+          lastTrackedAnchor = { x: pos.x, y: pos.y };
+          tooltip.move(pos);
+        }
+      }
+      tooltip.step(dt);
+    },
+    draw() {
+      if (d.isDisposed) return;
+      tooltip.draw(deps.hudLayer());
+    },
+    dispose: () => d.dispose(),
+    syncHits(hits) {
+      if (!axisMode) return;
+      axisHits = hits as readonly CompiledHitTest<unknown>[];
+      recomputeAxis();
+    },
+  };
+}
+
+/** @internal — exposed for unit tests only. */
+export const __test__ = { buildAxisTooltipContent, hoveredHitFromGroup };

package/src/grammar/interactions/transitions.d.ts

@@ -0,0 +1,34 @@
+import { type Easing } from "insomni";
+import type { Invalidator } from "insomni";
+import type { ActiveTransition, GeomFrame } from "../geoms/types.ts";
+export interface TransitionsOptions {
+    /** Duration in seconds. */
+    duration: number;
+    easing: Easing;
+    invalidator: Invalidator;
+}
+export interface GrammarTransitions {
+    /** Advance the progress tween. Returns true while a transition is active. */
+    step(dt: number): boolean;
+    /**
+     * Signal that data/config has changed. If stored frames exist, snapshots
+     * them as "from" frames before the new pipeline compiles.
+     */
+    notifyChange(): void;
+    /**
+     * Returns the active transition context for geom at layer index `i`,
+     * or undefined when no transition is running or no stored frame exists.
+     */
+    contextFor(layerIndex: number, scope?: unknown): ActiveTransition | undefined;
+    /**
+     * Store the current compiled frame for future "from" use.
+     * Always updates the stable store. If a transition was just signalled,
+     * kicks off the progress tween.
+     */
+    storeFrame(layerIndex: number, frame: GeomFrame, scope?: unknown): void;
+    /** True while a transition is running. */
+    readonly active: boolean;
+    /** Imperatively request a transition on next draw, even without a data change. */
+    requestTransition(): void;
+}
+export declare function createGrammarTransitions(opts: TransitionsOptions): GrammarTransitions;