insomni-plot 0.1.0-alpha.0

package/src/grammar/data/pivot.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// Wide → long reshape helpers
+// ---------------------------------------------------------------------------
+// Most of the heatmap references in the gallery start from a 2D matrix or a
+// wide table — `tile()` consumes long rows of `{x, y, value}`. These two
+// helpers cover both shapes without pulling in a dataframe dependency.
+
+export interface FromMatrixOptions {
+  /** Y labels (rows). Top to bottom. Length must equal `values.length`. */
+  rows: readonly string[];
+  /** X labels (cols). Left to right. Length must equal `values[0].length`. */
+  cols: readonly string[];
+  /** Output key for the row label. Default `"row"`. */
+  rowKey?: string;
+  /** Output key for the col label. Default `"col"`. */
+  colKey?: string;
+  /** Output key for the cell value. Default `"value"`. */
+  valueKey?: string;
+}
+
+export type LongRow<R extends string, C extends string, V extends string> = {
+  [K in R | C | V]: K extends V ? number : string;
+};
+
+/**
+ * Convert a 2D `values[row][col]` matrix into long-format rows that the
+ * `tile()` geom consumes directly. Cells with `NaN` / `null` / `undefined`
+ * are kept (so consumers can opt into NA cell rendering); cells whose
+ * coordinates are out of range are skipped.
+ *
+ * Example:
+ * ```ts
+ * const long = fromMatrix(temperatures, {
+ *   rows: ["00:00", "06:00", "12:00", "18:00"],
+ *   cols: ["Mon", "Tue", "Wed", "Thu", "Fri"],
+ * });
+ * tile({ x: "col", y: "row", fill: "value" })
+ * ```
+ */
+export function fromMatrix(
+  values: readonly (readonly number[])[],
+  opts: FromMatrixOptions,
+): { row: string; col: string; value: number }[] {
+  const rowKey = opts.rowKey ?? "row";
+  const colKey = opts.colKey ?? "col";
+  const valueKey = opts.valueKey ?? "value";
+  const out: { row: string; col: string; value: number }[] = [];
+  for (let r = 0; r < opts.rows.length; r++) {
+    const row = values[r];
+    if (!row) continue;
+    const rowLabel = opts.rows[r]!;
+    for (let c = 0; c < opts.cols.length; c++) {
+      const v = row[c];
+      if (v === undefined) continue;
+      out.push({
+        [rowKey]: rowLabel,
+        [colKey]: opts.cols[c]!,
+        [valueKey]: v,
+      } as { row: string; col: string; value: number });
+    }
+  }
+  return out;
+}
+
+export interface PivotLongerOptions<T> {
+  /** Output column name for the original key. Default `"name"`. */
+  nameKey?: string;
+  /** Output column name for the value. Default `"value"`. */
+  valueKey?: string;
+  /** Optional id columns kept verbatim alongside the long pair. */
+  idColumns?: readonly (keyof T & string)[];
+}
+
+/**
+ * Pivot a wide row to a sequence of long rows — one per `keys` entry.
+ * `idColumns` are copied through to every output row so a per-row identifier
+ * (e.g. car name in the mtcars example) is preserved.
+ *
+ * Example:
+ * ```ts
+ * const long = pivotLonger(mtcars, ["mpg", "cyl", "disp", "hp"], {
+ *   idColumns: ["model"],
+ * });
+ * // → [{ model, name: "mpg", value }, { model, name: "cyl", value }, ...]
+ * ```
+ */
+export function pivotLonger<T extends Record<string, unknown>>(
+  rows: readonly T[],
+  keys: readonly (keyof T & string)[],
+  options: PivotLongerOptions<T> = {},
+): Record<string, unknown>[] {
+  const nameKey = options.nameKey ?? "name";
+  const valueKey = options.valueKey ?? "value";
+  const idColumns = options.idColumns ?? [];
+  const out: Record<string, unknown>[] = [];
+  for (const row of rows) {
+    for (const key of keys) {
+      const entry: Record<string, unknown> = {
+        [nameKey]: key,
+        [valueKey]: row[key],
+      };
+      for (const id of idColumns) entry[id] = row[id];
+      out.push(entry);
+    }
+  }
+  return out;
+}

package/src/grammar/emphasis-driver.d.ts

@@ -0,0 +1,69 @@
+/** The emphasis uniform write the driver hands back to the renderer. */
+export interface EmphasisState {
+    focusedKey: number;
+    dimAlpha: number;
+    t: number;
+}
+/**
+ * What a driver method asks of the host this turn.
+ *   • `needsFrame` — a frame must be drawn at all.
+ *   • `full` — that frame MUST be a FULL render (never a regions/overlay-only
+ *     partial), because the emphasis uniform is in a visible/transitioning state
+ *     (see SOUNDNESS RULE in the module header). When `needsFrame` is true and
+ *     `full` is false, an overlay-only repaint is sound.
+ */
+export interface FrameRequest {
+    needsFrame: boolean;
+    full: boolean;
+}
+export interface EmphasisDriverOptions {
+    /**
+     * Animation duration in seconds. `<= 0` means reduced-motion: the dim snaps
+     * instantly (no ramp). Re-read on every `onHover` via `durationS` being a
+     * thunk so a live theme/reduced-motion change takes effect immediately.
+     */
+    durationS: () => number;
+    /** Dim alpha (theme.interactions.hover.dim) for the non-focused instances. */
+    dim: () => number;
+    /** Push an emphasis uniform write to the renderer. */
+    setEmphasis: (state: EmphasisState) => void;
+}
+/**
+ * The animated-emphasis state machine. Pure aside from the injected
+ * `setEmphasis` sink; time is supplied by the caller (deterministic in tests).
+ */
+export interface EmphasisDriver {
+    /**
+     * A hover hit resolved to its focused emphasis key (or `null`/`0` for no dim
+     * geom / exit). Updates the target and, under reduced-motion, snaps `t`.
+     * Returns the frame the host must draw. The full-frame decision encodes Fix A:
+     * ANY snap (enter OR exit) from/to a visibly-dimmed state is a global pixel
+     * change → FULL; an exit that was never showing is an ordinary overlay move.
+     */
+    onHover(focusedKey: number | null): FrameRequest;
+    /**
+     * Advance the ramp by the time elapsed since the last `step`/`onHover` call.
+     * Writes the eased uniform and returns the frame to draw. While transitioning
+     * this is always a FULL frame. Returns {@link NO_FRAME} when already settled
+     * (so the RAF loop can stop re-invalidating — no perpetual frames).
+     */
+    step(now: number): FrameRequest;
+    /** True while `t` has not reached its target (mid-transition). */
+    animating(): boolean;
+    /**
+     * Snap the uniform to the settled-off state (t = 0, focusedKey = 0) and clear
+     * all internal animation state. Used on the DATA path (setData/update): a held
+     * hover's stale focused key — index-derived, so it points at re-indexed
+     * instances after a data swap — is dropped before the full redraw; the
+     * pointer's next move re-establishes emphasis. Idempotent. Does NOT itself
+     * request a frame (the data path already forces a full redraw).
+     */
+    reset(): void;
+    /** Internal state, exposed for tests/diagnostics. */
+    state(): {
+        focusedKey: number;
+        t: number;
+        target: number;
+    };
+}
+export declare function createEmphasisDriver(opts: EmphasisDriverOptions): EmphasisDriver;

package/src/grammar/emphasis-driver.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Unit tests for the REAL animated-emphasis driver (`emphasis-driver.ts`).
+ *
+ * These drive the production state machine directly with a deterministic clock —
+ * no hand-copied mirror. The driver is the single source of truth for: the t
+ * ramp, the ease-out-cubic write, reduced-motion snap, hover swap, the exit-snap
+ * full-frame rule (Fix A), and reset() (Fix C). The mount is a thin consumer that
+ * wires `setEmphasis` → renderer and routes `{ needsFrame, full }` into
+ * inv/requestOverlay/drawRepaint.
+ */
+
+import { describe, expect, test } from "vite-plus/test";
+
+import {
+  createEmphasisDriver,
+  type EmphasisDriver,
+  type EmphasisState,
+} from "./emphasis-driver.ts";
+
+interface Harness {
+  driver: EmphasisDriver;
+  writes: EmphasisState[];
+  setDuration: (s: number) => void;
+}
+
+function makeDriver(opts: { durationS?: number; dim?: number } = {}): Harness {
+  let durationS = opts.durationS ?? 0.1; // 100ms default
+  const dim = opts.dim ?? 0.45;
+  const writes: EmphasisState[] = [];
+  const driver = createEmphasisDriver({
+    durationS: () => durationS,
+    dim: () => dim,
+    setEmphasis: (s) => writes.push({ ...s }),
+  });
+  return { driver, writes, setDuration: (s) => (durationS = s) };
+}
+
+const FOCUS_A = 1234;
+const FOCUS_B = 5678;
+
+describe("emphasis driver — enter / ramp / settle", () => {
+  test("enter resolves the key, requests a FULL frame, and starts t at 0", () => {
+    const { driver, writes } = makeDriver({ durationS: 0.1, dim: 0.45 });
+    const req = driver.onHover(FOCUS_A);
+    expect(req).toEqual({ needsFrame: true, full: true });
+    expect(driver.state()).toEqual({ focusedKey: FOCUS_A, t: 0, target: 1 });
+    expect(writes.at(-1)).toEqual({ focusedKey: FOCUS_A, dimAlpha: 0.45, t: 0 });
+  });
+
+  test("t ramps over durationMs; each step is a FULL frame; settles at 1", () => {
+    const { driver, writes } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    // First step seeds the clock (advances nothing).
+    expect(driver.step(0).needsFrame).toBe(true);
+    expect(driver.state().t).toBe(0);
+    // 50ms over a 100ms ramp → t 0.5.
+    let r = driver.step(50);
+    expect(r).toEqual({ needsFrame: true, full: true });
+    expect(driver.state().t).toBeCloseTo(0.5, 5);
+    expect(driver.animating()).toBe(true);
+    // Another 50ms → settled at 1.
+    r = driver.step(100);
+    expect(driver.state().t).toBeCloseTo(1, 5);
+    expect(driver.animating()).toBe(false);
+    // The eased write reflects ease-out-cubic of t.
+    const last = writes.at(-1)!;
+    expect(last.t).toBeCloseTo(1, 5);
+    // A step once settled requests no frame (loop stops — no perpetual RAF).
+    expect(driver.step(116)).toEqual({ needsFrame: false, full: false });
+  });
+
+  test("the written t is ease-out-cubic of the raw ramp t", () => {
+    const { driver, writes } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    driver.step(0); // seed
+    driver.step(50); // raw t = 0.5
+    const eased = 1 - Math.pow(1 - 0.5, 3); // 0.875
+    expect(writes.at(-1)!.t).toBeCloseTo(eased, 5);
+  });
+});
+
+describe("emphasis driver — exit", () => {
+  test("exit from a shown dim ramps t→0 (FULL frames) then clears the key", () => {
+    const { driver } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    driver.step(0);
+    driver.step(100); // settle on
+    const req = driver.onHover(null);
+    expect(req).toEqual({ needsFrame: true, full: true });
+    expect(driver.state().target).toBe(0);
+    driver.step(100); // seed clock at exit's first step
+    driver.step(150); // 50ms → t 0.5
+    expect(driver.state().t).toBeCloseTo(0.5, 5);
+    expect(driver.state().focusedKey).toBe(FOCUS_A); // held until settled
+    driver.step(200); // → t 0
+    expect(driver.state().t).toBeCloseTo(0, 5);
+    expect(driver.state().focusedKey).toBe(0); // cleared once t reaches 0
+  });
+
+  // Fix A core: an exit that was never showing a dim is an ordinary overlay move
+  // (point halo / tooltip) — NOT a full frame.
+  test("exit with no dim shown → no full frame (overlay-only territory)", () => {
+    const { driver } = makeDriver({ durationS: 0.1 });
+    const req = driver.onHover(null);
+    expect(req).toEqual({ needsFrame: false, full: false });
+  });
+});
+
+describe("emphasis driver — hover swap (single uniform)", () => {
+  test("A→B mid-ramp snaps focusedKey to B and continues toward 1 (no reset)", () => {
+    const { driver } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    driver.step(0);
+    driver.step(50); // t 0.5 toward A
+    const req = driver.onHover(FOCUS_B);
+    expect(req).toEqual({ needsFrame: true, full: true });
+    expect(driver.state().focusedKey).toBe(FOCUS_B);
+    expect(driver.state().target).toBe(1);
+    expect(driver.state().t).toBeCloseTo(0.5, 5); // continues, not reset
+    // Resumes ramping (clock re-seeds on the swap).
+    driver.step(50);
+    driver.step(100); // 50ms more → t 1
+    expect(driver.state().t).toBeCloseTo(1, 5);
+  });
+});
+
+describe("emphasis driver — Fix A: reduced-motion snaps are FULL frames", () => {
+  test("reduced-motion ENTER snaps t→1 in one full frame (no ramp)", () => {
+    const { driver, writes } = makeDriver({ durationS: 0 });
+    const req = driver.onHover(FOCUS_A);
+    expect(req).toEqual({ needsFrame: true, full: true });
+    expect(driver.state().t).toBe(1);
+    expect(driver.animating()).toBe(false);
+    expect(writes.at(-1)!.t).toBe(1);
+    // No ramp frames follow.
+    expect(driver.step(16)).toEqual({ needsFrame: false, full: false });
+  });
+
+  // The bug Fix A repairs: reduced-motion EXIT snapped the uniform off (a global
+  // pixel change) but the OLD code routed it to an overlay-only repaint, leaving
+  // the rest of the backbuffer stuck dimmed. The driver now reports `full` for
+  // any snap-off from a shown dim.
+  test("reduced-motion EXIT from a shown dim snaps off as a FULL frame (not overlay)", () => {
+    const { driver, writes } = makeDriver({ durationS: 0 });
+    driver.onHover(FOCUS_A); // snap on
+    expect(driver.state().t).toBe(1);
+    const req = driver.onHover(null); // snap off
+    expect(req).toEqual({ needsFrame: true, full: true }); // <-- the fix
+    expect(driver.state()).toEqual({ focusedKey: 0, t: 0, target: 0 });
+    expect(writes.at(-1)!.t).toBe(0);
+  });
+
+  test("live duration change to 0 mid-hover takes effect on the next onHover", () => {
+    const h = makeDriver({ durationS: 0.1 });
+    h.driver.onHover(FOCUS_A);
+    h.driver.step(0);
+    h.driver.step(100); // settle on (animated)
+    h.setDuration(0); // user flips on reduced-motion
+    const req = h.driver.onHover(null);
+    expect(req.full).toBe(true);
+    expect(h.driver.state().t).toBe(0); // snapped, not ramped
+  });
+});
+
+describe("emphasis driver — Fix C: reset() on the data path", () => {
+  test("reset snaps the uniform off and clears all state", () => {
+    const { driver, writes } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    driver.step(0);
+    driver.step(50); // mid-ramp, dim shown
+    expect(driver.state().focusedKey).toBe(FOCUS_A);
+    driver.reset();
+    expect(driver.state()).toEqual({ focusedKey: 0, t: 0, target: 0 });
+    expect(driver.animating()).toBe(false);
+    // reset writes a settled-off uniform so the next full redraw shows no dim.
+    expect(writes.at(-1)).toEqual({ focusedKey: 0, dimAlpha: 0.45, t: 0 });
+  });
+
+  test("after reset, the next enter re-establishes emphasis from scratch", () => {
+    const { driver } = makeDriver({ durationS: 0.1 });
+    driver.onHover(FOCUS_A);
+    driver.step(0);
+    driver.step(100);
+    driver.reset();
+    const req = driver.onHover(FOCUS_B);
+    expect(req).toEqual({ needsFrame: true, full: true });
+    expect(driver.state()).toEqual({ focusedKey: FOCUS_B, t: 0, target: 1 });
+  });
+});
+
+describe("emphasis driver — no-dim hits never engage", () => {
+  test("onHover(null) / onHover(0) with nothing shown is inert", () => {
+    const { driver, writes } = makeDriver({ durationS: 0.1 });
+    expect(driver.onHover(null)).toEqual({ needsFrame: false, full: false });
+    expect(driver.onHover(0)).toEqual({ needsFrame: false, full: false });
+    expect(driver.state().focusedKey).toBe(0);
+    expect(writes).toHaveLength(0);
+  });
+});

package/src/grammar/emphasis-driver.ts

@@ -0,0 +1,205 @@
+// ---------------------------------------------------------------------------
+// Animated GPU-emphasis driver (P5-T3) — extracted from mount.ts
+// ---------------------------------------------------------------------------
+// The dim-others hover treatment is driven entirely by the core renderer's
+// emphasis uniform: on a hover hit-change over a GPU-dim geom the mount resolves
+// the hit to a namespaced focused key and animates `t` 0→1 (ease-out cubic) over
+// `theme.interactions.hover.durationMs`; on exit `t` ramps back to 0 and the
+// focused key is held until `t` settles, then cleared. Zero marks recompile per
+// hover frame.
+//
+// This module is the PURE state machine for that animation, factored out of the
+// mount so it can be unit-tested directly (deterministic `now()`) instead of
+// against a hand-copied mirror. The mount is a thin consumer: it wires the
+// driver's `setEmphasis(state)` callback to `renderer.setEmphasis(...)`, feeds
+// hover hits in through `onHover(key)`, advances the ramp from the RAF tick via
+// `step(now)`, and routes the returned `{ needsFrame, full }` decisions into
+// `inv.invalidate()` / `requestOverlay()`.
+//
+// SOUNDNESS RULE (load-bearing): a changed emphasis uniform alters pixels
+// EVERYWHERE (every tagged instance re-mixes its alpha), so a regions/overlay
+// partial frame would leave the un-repainted backbuffer showing the previous
+// dim. Therefore every frame the driver requests while the uniform is in a
+// VISIBLE / TRANSITIONING state is a FULL frame (`full: true`). Only a settled,
+// fully-undimmed state (t === 0, no focused key) lets the mount fall back to the
+// cheap overlay path for a pure cursor-overlay change.
+//
+// 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).
+
+/** The emphasis uniform write the driver hands back to the renderer. */
+export interface EmphasisState {
+  focusedKey: number;
+  dimAlpha: number;
+  t: number;
+}
+
+/**
+ * What a driver method asks of the host this turn.
+ *   • `needsFrame` — a frame must be drawn at all.
+ *   • `full` — that frame MUST be a FULL render (never a regions/overlay-only
+ *     partial), because the emphasis uniform is in a visible/transitioning state
+ *     (see SOUNDNESS RULE in the module header). When `needsFrame` is true and
+ *     `full` is false, an overlay-only repaint is sound.
+ */
+export interface FrameRequest {
+  needsFrame: boolean;
+  full: boolean;
+}
+
+const NO_FRAME: FrameRequest = { needsFrame: false, full: false };
+
+export interface EmphasisDriverOptions {
+  /**
+   * Animation duration in seconds. `<= 0` means reduced-motion: the dim snaps
+   * instantly (no ramp). Re-read on every `onHover` via `durationS` being a
+   * thunk so a live theme/reduced-motion change takes effect immediately.
+   */
+  durationS: () => number;
+  /** Dim alpha (theme.interactions.hover.dim) for the non-focused instances. */
+  dim: () => number;
+  /** Push an emphasis uniform write to the renderer. */
+  setEmphasis: (state: EmphasisState) => void;
+}
+
+/**
+ * The animated-emphasis state machine. Pure aside from the injected
+ * `setEmphasis` sink; time is supplied by the caller (deterministic in tests).
+ */
+export interface EmphasisDriver {
+  /**
+   * A hover hit resolved to its focused emphasis key (or `null`/`0` for no dim
+   * geom / exit). Updates the target and, under reduced-motion, snaps `t`.
+   * Returns the frame the host must draw. The full-frame decision encodes Fix A:
+   * ANY snap (enter OR exit) from/to a visibly-dimmed state is a global pixel
+   * change → FULL; an exit that was never showing is an ordinary overlay move.
+   */
+  onHover(focusedKey: number | null): FrameRequest;
+
+  /**
+   * Advance the ramp by the time elapsed since the last `step`/`onHover` call.
+   * Writes the eased uniform and returns the frame to draw. While transitioning
+   * this is always a FULL frame. Returns {@link NO_FRAME} when already settled
+   * (so the RAF loop can stop re-invalidating — no perpetual frames).
+   */
+  step(now: number): FrameRequest;
+
+  /** True while `t` has not reached its target (mid-transition). */
+  animating(): boolean;
+
+  /**
+   * Snap the uniform to the settled-off state (t = 0, focusedKey = 0) and clear
+   * all internal animation state. Used on the DATA path (setData/update): a held
+   * hover's stale focused key — index-derived, so it points at re-indexed
+   * instances after a data swap — is dropped before the full redraw; the
+   * pointer's next move re-establishes emphasis. Idempotent. Does NOT itself
+   * request a frame (the data path already forces a full redraw).
+   */
+  reset(): void;
+
+  /** Internal state, exposed for tests/diagnostics. */
+  state(): { focusedKey: number; t: number; target: number };
+}
+
+const easeOutCubic = (t: number): number => 1 - Math.pow(1 - t, 3);
+const clamp01 = (t: number): number => Math.max(0, Math.min(1, t));
+
+export function createEmphasisDriver(opts: EmphasisDriverOptions): EmphasisDriver {
+  let focusedKey = 0; // 0 = nothing focused (settled / inert)
+  let t = 0; // 0 (no dim) … 1 (full dim) — raw, linear; eased at write time
+  let target = 0; // ramp t toward this (0 on exit, 1 on enter)
+  let durationS = 0; // resolved from the theme thunk on each hover change
+  let lastNow = 0; // last `step` timestamp; seeded on first step after a change
+  let lastNowValid = false;
+
+  const animating = (): boolean => t !== target;
+
+  // True when the uniform currently shows (or is ramping toward) a dim — i.e. a
+  // partial frame would be unsound. Either we have a live focused key with a
+  // non-zero/ramping-up t, or we are mid-ramp-out (t still > 0).
+  const isShowing = (): boolean => focusedKey !== 0 && (target === 1 || t > 0);
+
+  function write(): void {
+    opts.setEmphasis({ focusedKey, dimAlpha: opts.dim(), t: easeOutCubic(clamp01(t)) });
+  }
+
+  function onHover(nextFocused: number | null): FrameRequest {
+    const key = nextFocused ?? 0;
+    durationS = opts.durationS();
+    const snap = durationS <= 0;
+    const wasShowing = isShowing();
+
+    if (key !== 0) {
+      // Enter / swap. Snap the focused key (uniform holds one), ramp toward 1.
+      focusedKey = key;
+      target = 1;
+      lastNowValid = false; // re-seed the ramp clock on the next step
+      if (snap) t = 1; // reduced-motion: snap on
+      write();
+      // Enter is ALWAYS a global pixel change (a new dim appears, or the dim
+      // re-targets a different instance), so it always forces a FULL frame —
+      // both for the animated ramp AND the reduced-motion snap (Fix A symmetry).
+      return { needsFrame: true, full: true };
+    }
+
+    // No dim geom focused → ramp out (or, under reduced-motion, snap off).
+    target = 0;
+    lastNowValid = false;
+    if (snap) {
+      focusedKey = 0;
+      t = 0;
+      write();
+    }
+    // Fix A: any change from/to a visibly-dimmed state is a global pixel change
+    // and MUST be a full frame — INCLUDING the reduced-motion snap-off (which
+    // clears the dim everywhere in one frame). Only an exit that was never
+    // showing is an ordinary cursor-overlay move (point halo / tooltip).
+    if (wasShowing) return { needsFrame: true, full: true };
+    return { needsFrame: false, full: false };
+  }
+
+  function step(now: number): FrameRequest {
+    if (!animating()) {
+      lastNowValid = false;
+      return NO_FRAME;
+    }
+    if (!lastNowValid) {
+      // First step since the last change — seed the clock, advance nothing yet.
+      lastNow = now;
+      lastNowValid = true;
+    }
+    const dt = Math.max(0, (now - lastNow) / 1000);
+    lastNow = now;
+    if (dt > 0) {
+      if (durationS > 0) {
+        const stepT = dt / durationS;
+        t = t < target ? Math.min(target, t + stepT) : Math.max(target, t - stepT);
+      } else {
+        t = target;
+      }
+    }
+    // Clear the held focused key once a ramp-out settles at 0.
+    if (target === 0 && t <= 0) focusedKey = 0;
+    write();
+    // Mid-transition (or just-settled this frame) the uniform changed → FULL.
+    return { needsFrame: true, full: true };
+  }
+
+  function reset(): void {
+    focusedKey = 0;
+    t = 0;
+    target = 0;
+    durationS = 0;
+    lastNowValid = false;
+    write();
+  }
+
+  return {
+    onHover,
+    step,
+    animating,
+    reset,
+    state: () => ({ focusedKey, t, target }),
+  };
+}

package/src/grammar/equality.d.ts

@@ -0,0 +1,3 @@
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+export declare function arraysEqual(a: readonly unknown[], b: readonly unknown[]): boolean;
+export declare function shallowObjectEqual(a: unknown, b: unknown): boolean;

package/src/grammar/equality.ts

@@ -0,0 +1,40 @@
+// Date-aware leaf comparison. Two Dates with the same instant count as equal
+// even when they're separate instances — the realistic case when builder
+// closures recreate option objects each frame, or when two channels resolve
+// the same field via separate accessors.
+export function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  return Object.is(a, b);
+}
+
+export function arraysEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!valuesEqual(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+// Shallow object equality with Date-aware leaves and array-typed values
+// compared element-wise. Non-array, non-primitive values (palette objects,
+// blendSpace strings) fall back to `Object.is` — those rarely change at
+// runtime, and a false-negative there merely re-triggers a transition the
+// user did intend.
+export function shallowObjectEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  const aKeys = Object.keys(a as object);
+  const bKeys = Object.keys(b as object);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.hasOwn(b as object, k)) return false;
+    const av = (a as Record<string, unknown>)[k];
+    const bv = (b as Record<string, unknown>)[k];
+    if (Array.isArray(av) && Array.isArray(bv)) {
+      if (!arraysEqual(av, bv)) return false;
+    } else if (!valuesEqual(av, bv)) return false;
+  }
+  return true;
+}