insomni-plot 0.1.0-alpha.0

package/src/grammar/mount.test.ts

@@ -0,0 +1,479 @@
+// @vitest-environment jsdom
+/**
+ * Unit tests for the mount.ts render-orchestration invariants (P5 migration).
+ *
+ * mount.ts cannot be directly imported in node-mode tests because it
+ * transitively imports "insomni/reactivity" (a browser-only export). So these
+ * tests exercise the REAL building blocks the mount composes:
+ *   - `createLayer` (real insomni) with the explicit zIndex bands + cache hints,
+ *     proving the band layout + cache-pin contract mount.ts mints layers under;
+ *   - the REAL `createEmphasisDriver` state machine (`./emphasis-driver.ts`),
+ *     which mount.ts wires to renderer.setEmphasis / inv / requestOverlay / RAF;
+ *   - the per-tick frame-kind dispatch RULE (recompile-only-when-dirty), proving
+ *     Fix D: an emphasis ramp produces FULL renders with ZERO pipeline recompiles.
+ *
+ * The emphasis STATE MACHINE itself is tested directly in emphasis-driver.test.ts
+ * (deterministic clock); the key-band + GPU_DIM_GEOM_KINDS contracts in
+ * geoms/emphasis.test.ts. No hand-copied driver mirror lives here anymore.
+ *
+ * Plot NEVER calls cacheLayer/uncacheLayer and NEVER passes fullFrame:true — the
+ * core's per-frame cache policy + view fingerprint own the bake/full decision.
+ */
+
+import { createLayer } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { createEmphasisDriver, type EmphasisState } from "./emphasis-driver.ts";
+
+// ---------------------------------------------------------------------------
+// Layer band layout + cache hints (real `createLayer`)
+//
+// Mount mints the four owned layers as:
+//   const staticCacheHint = partial ? "auto" : "never";
+//   axisLayer    = createLayer({ space:"ui", zIndex:0,   cache: staticCacheHint });
+//   marksLayer   = createLayer({ space:"ui", zIndex:100, cache: staticCacheHint });
+//   hudLayer     = createLayer({ space:"ui", zIndex:200, cache: staticCacheHint });
+//   overlayLayer = createLayer({ space:"ui", zIndex:300, cache: "never" });
+// These tests run that exact minting against the real layer impl.
+// ---------------------------------------------------------------------------
+
+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;
+
+function staticCacheHint(partial: boolean): "auto" | "never" {
+  return partial ? "auto" : "never";
+}
+
+function makeLayers(partial: boolean) {
+  const hint = staticCacheHint(partial);
+  const axisLayer = createLayer({ space: "ui", zIndex: Z_AXIS, cache: hint });
+  const marksLayer = createLayer({ space: "ui", zIndex: Z_MARKS, cache: hint });
+  const hudLayer = createLayer({ space: "ui", zIndex: Z_HUD, cache: hint });
+  const overlayLayer = createLayer({ space: "ui", zIndex: Z_OVERLAY, cache: "never" });
+  const cleanup = () => {
+    axisLayer.destroy();
+    marksLayer.destroy();
+    hudLayer.destroy();
+    overlayLayer.destroy();
+  };
+  return { axisLayer, marksLayer, hudLayer, overlayLayer, cleanup };
+}
+
+describe("layer zIndex bands + cache hints", () => {
+  test("partial=true: static layers cache:'auto', overlay 'never'; bands ascend axis<marks<hud<overlay", () => {
+    const { axisLayer, marksLayer, hudLayer, overlayLayer, cleanup } = makeLayers(true);
+
+    expect(axisLayer.cache).toBe("auto");
+    expect(marksLayer.cache).toBe("auto");
+    expect(hudLayer.cache).toBe("auto");
+    expect(overlayLayer.cache).toBe("never");
+
+    expect(axisLayer.zIndex).toBe(0);
+    expect(marksLayer.zIndex).toBe(100);
+    expect(hudLayer.zIndex).toBe(200);
+    expect(overlayLayer.zIndex).toBe(300);
+    expect(axisLayer.zIndex! < marksLayer.zIndex!).toBe(true);
+    expect(marksLayer.zIndex! < hudLayer.zIndex!).toBe(true);
+    expect(hudLayer.zIndex! < overlayLayer.zIndex!).toBe(true);
+
+    cleanup();
+  });
+
+  test("partial=false: EVERY layer is cache:'never' (pure-live fallback)", () => {
+    const { axisLayer, marksLayer, hudLayer, overlayLayer, cleanup } = makeLayers(false);
+
+    expect(axisLayer.cache).toBe("never");
+    expect(marksLayer.cache).toBe("never");
+    expect(hudLayer.cache).toBe("never");
+    expect(overlayLayer.cache).toBe("never");
+
+    cleanup();
+  });
+
+  test("overlay is ALWAYS cache:'never' regardless of partial", () => {
+    const a = makeLayers(true);
+    expect(a.overlayLayer.cache).toBe("never");
+    a.cleanup();
+    const b = makeLayers(false);
+    expect(b.overlayLayer.cache).toBe("never");
+    b.cleanup();
+  });
+
+  test("extra below/above layers slot into 10.. / 110.. bands (between fixed bands)", () => {
+    const below = [createLayer({ space: "ui" }), createLayer({ space: "ui" })];
+    const above = [createLayer({ space: "ui" })];
+    for (let i = 0; i < below.length; i++) below[i]!.zIndex = Z_BELOW_BASE + i;
+    for (let i = 0; i < above.length; i++) above[i]!.zIndex = Z_ABOVE_BASE + i;
+
+    expect(below.map((l) => l.zIndex)).toEqual([10, 11]);
+    expect(above.map((l) => l.zIndex)).toEqual([110]);
+    expect(below.every((l) => l.zIndex! > Z_AXIS && l.zIndex! < Z_MARKS)).toBe(true);
+    expect(above.every((l) => l.zIndex! > Z_MARKS && l.zIndex! < Z_HUD)).toBe(true);
+
+    for (const l of [...below, ...above]) l.destroy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Interaction-aware cache-hint flip (real `Layer.cache` mutation)
+//
+// mount.ts's `applyInteractionCacheHints()`:
+//   if (!partial) return;
+//   const interacting = !!binding && (binding.interacting || binding.flinging);
+//   const hint = interacting ? "never" : "auto";
+//   axisLayer.cache = hint; marksLayer.cache = hint; hudLayer.cache = hint;
+//   marksLayer.cache = marksCacheHint(interacting); // dim charts pin "never"
+//   // overlay stays "never".
+// We run the same mutation against real layers (mutating Layer.cache between
+// frames is a supported core contract).
+// ---------------------------------------------------------------------------
+
+interface StubBinding {
+  interacting: boolean;
+  flinging: boolean;
+}
+
+function applyInteractionCacheHints(
+  partial: boolean,
+  binding: StubBinding | null,
+  layers: ReturnType<typeof makeLayers>,
+): void {
+  if (!partial) return;
+  const interacting = !!binding && (binding.interacting || binding.flinging);
+  const hint = interacting ? "never" : "auto";
+  layers.axisLayer.cache = hint;
+  layers.marksLayer.cache = hint;
+  layers.hudLayer.cache = hint;
+  // overlay untouched.
+}
+
+describe("interaction-aware cache-hint flip", () => {
+  test("dragging (interacting): static layers flip to 'never', overlay stays 'never'", () => {
+    const layers = makeLayers(true);
+    applyInteractionCacheHints(true, { interacting: true, flinging: false }, layers);
+
+    expect(layers.axisLayer.cache).toBe("never");
+    expect(layers.marksLayer.cache).toBe("never");
+    expect(layers.hudLayer.cache).toBe("never");
+    expect(layers.overlayLayer.cache).toBe("never");
+
+    layers.cleanup();
+  });
+
+  test("flinging also flips static layers to 'never'", () => {
+    const layers = makeLayers(true);
+    applyInteractionCacheHints(true, { interacting: false, flinging: true }, layers);
+
+    expect(layers.axisLayer.cache).toBe("never");
+    expect(layers.marksLayer.cache).toBe("never");
+    expect(layers.hudLayer.cache).toBe("never");
+
+    layers.cleanup();
+  });
+
+  test("settled (not interacting): static layers restore to 'auto'", () => {
+    const layers = makeLayers(true);
+    applyInteractionCacheHints(true, { interacting: true, flinging: false }, layers);
+    applyInteractionCacheHints(true, { interacting: false, flinging: false }, layers);
+
+    expect(layers.axisLayer.cache).toBe("auto");
+    expect(layers.marksLayer.cache).toBe("auto");
+    expect(layers.hudLayer.cache).toBe("auto");
+    expect(layers.overlayLayer.cache).toBe("never");
+
+    layers.cleanup();
+  });
+
+  test("no binding (pan/zoom not configured): hints stay 'auto'", () => {
+    const layers = makeLayers(true);
+    applyInteractionCacheHints(true, null, layers);
+
+    expect(layers.axisLayer.cache).toBe("auto");
+    expect(layers.marksLayer.cache).toBe("auto");
+    expect(layers.hudLayer.cache).toBe("auto");
+
+    layers.cleanup();
+  });
+
+  test("partial=false: hint flip is a no-op (layers stay 'never')", () => {
+    const layers = makeLayers(false);
+    applyInteractionCacheHints(false, { interacting: true, flinging: false }, layers);
+
+    expect(layers.axisLayer.cache).toBe("never");
+    expect(layers.marksLayer.cache).toBe("never");
+    expect(layers.hudLayer.cache).toBe("never");
+
+    layers.cleanup();
+  });
+
+  test("drag → settle: 'never' during gesture, 'auto' after release", () => {
+    const layers = makeLayers(true);
+
+    applyInteractionCacheHints(true, { interacting: true, flinging: false }, layers);
+    expect(layers.marksLayer.cache).toBe("never");
+
+    applyInteractionCacheHints(true, { interacting: false, flinging: false }, layers);
+    expect(layers.marksLayer.cache).toBe("auto");
+
+    layers.cleanup();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Fix D — per-tick emphasis ramp is REPAINT-ONLY: N full renders, ZERO recompiles.
+//
+// This composes the REAL emphasis driver with the mount's per-tick dispatch RULE
+// (the thin-consumer glue that stays in mount.ts):
+//
+//   if (emphasisAnimating()) { const req = driver.step(now);
+//                              if (req.needsFrame) repaintPending = true; }
+//   const needsFull   = inv.dirty;                 // real recompile pending
+//   const needsRepaint = repaintPending;           // uniform-only full render
+//   if (needsFull) drawFull();          // runPipeline + bake + render (FULL)
+//   else if (needsRepaint) drawRepaint(); // render(currentLayers()) — NO pipeline
+//   else drawOverlay();                  // regions/partial
+//
+// The pipeline + renderer boundaries are faked so we can count recompiles and
+// classify the render kind of every emitted frame.
+// ---------------------------------------------------------------------------
+
+interface FrameLog {
+  kind: "full" | "repaint" | "overlay";
+  regions: boolean; // whether this render() carried `regions` (partial)
+}
+
+/** A tick loop that drives the REAL driver through the production dispatch rule. */
+function makeTickHarness(opts: { durationS: number }) {
+  let durationS = opts.durationS;
+  const emphasisWrites: EmphasisState[] = [];
+  let runPipelineCalls = 0;
+  let renderCalls = 0;
+  const frames: FrameLog[] = [];
+
+  const driver = createEmphasisDriver({
+    durationS: () => durationS,
+    dim: () => 0.45,
+    setEmphasis: (s) => emphasisWrites.push({ ...s }),
+  });
+
+  // --- faked mount boundaries ---
+  let invDirty = false;
+  let overlayDirty = false;
+  let repaintPending = false;
+
+  function runPipeline(): void {
+    runPipelineCalls++; // the expensive recompile + axis bake bump
+  }
+  function render(withRegions: boolean): void {
+    renderCalls++;
+    void withRegions;
+  }
+  function drawFull(): void {
+    invDirty = false;
+    overlayDirty = false;
+    runPipeline(); // a full frame recompiles
+    render(false);
+    frames.push({ kind: "full", regions: false });
+  }
+  function drawRepaint(): void {
+    render(false); // FULL render, NO runPipeline → packs stable → zero re-bakes
+    frames.push({ kind: "repaint", regions: false });
+  }
+  function drawOverlay(): void {
+    overlayDirty = false;
+    render(true); // regions/partial
+    frames.push({ kind: "overlay", regions: true });
+  }
+
+  function tick(now: number): void {
+    if (driver.animating()) {
+      const req = driver.step(now);
+      if (req.needsFrame) repaintPending = true;
+    }
+    const needsFull = invDirty;
+    const needsRepaint = repaintPending;
+    const needsOverlay = overlayDirty;
+    if (needsFull || needsRepaint || needsOverlay) {
+      if (needsFull) drawFull();
+      else if (needsRepaint) drawRepaint();
+      else drawOverlay();
+      repaintPending = false;
+    }
+  }
+
+  return {
+    driver,
+    tick,
+    onHover(key: number | null): void {
+      const req = driver.onHover(key);
+      if (req.needsFrame) {
+        if (req.full)
+          invDirty = true; // hover hit-change → full recompile
+        else overlayDirty = true;
+      }
+    },
+    markOverlayDirty: () => {
+      overlayDirty = true;
+    },
+    invalidate: () => {
+      invDirty = true;
+    },
+    setDuration: (s: number) => (durationS = s),
+    get runPipelineCalls() {
+      return runPipelineCalls;
+    },
+    get renderCalls() {
+      return renderCalls;
+    },
+    frames,
+    emphasisWrites,
+  };
+}
+
+describe("Fix D — emphasis ramp is repaint-only (no per-tick recompile)", () => {
+  test("N ramp steps produce N FULL renders and ZERO pipeline recompiles", () => {
+    const h = makeTickHarness({ durationS: 0.1 }); // 100ms ramp
+    h.onHover(1234); // enter → one full recompile frame
+    // Service the enter frame (drawFull).
+    h.tick(0);
+    expect(h.runPipelineCalls).toBe(1);
+    expect(h.frames.at(-1)!.kind).toBe("full");
+
+    // Now ramp: 5 steps of 25ms. The driver settles at t=1 partway, but each
+    // animating step requests a frame; once settled, step() requests nothing.
+    const recompilesBefore = h.runPipelineCalls;
+    let now = 0;
+    let repaintFrames = 0;
+    for (let i = 0; i < 5; i++) {
+      now += 25;
+      const framesBefore = h.frames.length;
+      h.tick(now);
+      const emitted = h.frames.length > framesBefore;
+      if (emitted) {
+        // Every emitted ramp frame is a repaint-only FULL render (no regions).
+        expect(h.frames.at(-1)!.kind).toBe("repaint");
+        expect(h.frames.at(-1)!.regions).toBe(false);
+        repaintFrames++;
+      }
+    }
+    // The ramp emitted at least one repaint frame...
+    expect(repaintFrames).toBeGreaterThan(0);
+    // ...and NOT ONE of them recompiled the pipeline (Fix D core assertion).
+    expect(h.runPipelineCalls).toBe(recompilesBefore);
+  });
+
+  test("a real invalidation mid-ramp (resize/data) WINS → drawFull, not repaint", () => {
+    const h = makeTickHarness({ durationS: 0.2 });
+    h.onHover(1234);
+    h.tick(0); // enter full
+    h.tick(50); // ramp step (repaint)
+    expect(h.frames.at(-1)!.kind).toBe("repaint");
+    const recompiles = h.runPipelineCalls;
+    // A resize fires inv.invalidate() mid-ramp.
+    h.invalidate();
+    h.tick(75);
+    // inv.dirty outranks the repaint → a full recompile frame.
+    expect(h.frames.at(-1)!.kind).toBe("full");
+    expect(h.runPipelineCalls).toBe(recompiles + 1);
+  });
+
+  test("an overlay-only request is SUPPRESSED while the dim is animating (soundness)", () => {
+    const h = makeTickHarness({ durationS: 0.2 });
+    h.onHover(1234);
+    h.tick(0); // enter full
+    // Cursor moves (tooltip) mid-ramp → overlay requested.
+    h.markOverlayDirty();
+    h.tick(50);
+    // The animating ramp's repaint outranks the overlay → FULL repaint, not a
+    // partial regions frame (the uniform is global; a partial would ghost).
+    expect(h.frames.at(-1)!.kind).toBe("repaint");
+    expect(h.frames.at(-1)!.regions).toBe(false);
+  });
+
+  test("once settled, a pure overlay change rides a regions (overlay) frame again", () => {
+    const h = makeTickHarness({ durationS: 0.1 });
+    h.onHover(1234);
+    h.tick(0);
+    h.tick(50);
+    h.tick(100); // settle at t=1
+    expect(h.driver.animating()).toBe(false);
+    h.markOverlayDirty();
+    h.tick(116);
+    expect(h.frames.at(-1)!.kind).toBe("overlay");
+    expect(h.frames.at(-1)!.regions).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Fix A — reduced-motion hover-exit forces a FULL frame (no stuck dim).
+//
+// Drives the REAL driver through the same dispatch glue. The bug: a reduced-
+// motion exit snapped the uniform off (global pixel change) but routed to an
+// overlay-only repaint, leaving the rest of the backbuffer dimmed.
+// ---------------------------------------------------------------------------
+
+describe("Fix A — reduced-motion exit forces a full frame", () => {
+  test("hover then exit under reduced-motion both produce FULL frames", () => {
+    const h = makeTickHarness({ durationS: 0 }); // reduced-motion
+    h.onHover(1234); // snap on
+    h.tick(0);
+    expect(h.frames.at(-1)!.kind).toBe("full");
+    expect(h.driver.state().t).toBe(1);
+
+    const fullsBefore = h.frames.filter((f) => f.kind === "full").length;
+    h.onHover(null); // snap off — MUST be a full frame, not overlay
+    h.tick(16);
+    const lastFrame = h.frames.at(-1)!;
+    expect(lastFrame.kind).toBe("full"); // <-- the fix (was "overlay" → stuck dim)
+    expect(lastFrame.regions).toBe(false);
+    expect(h.frames.filter((f) => f.kind === "full").length).toBe(fullsBefore + 1);
+    // Uniform snapped off → no residual dim.
+    expect(h.driver.state()).toEqual({ focusedKey: 0, t: 0, target: 0 });
+    expect(h.emphasisWrites.at(-1)!.t).toBe(0);
+  });
+
+  test("hover-enter under reduced-motion is a full frame (symmetric to exit)", () => {
+    const h = makeTickHarness({ durationS: 0 });
+    h.onHover(1234);
+    h.tick(0);
+    expect(h.frames.at(-1)!.kind).toBe("full");
+    expect(h.frames.at(-1)!.regions).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Marks cache pin for dim charts (P5-T3) — mirror of mount.ts `marksCacheHint`.
+// (A pure decision table; the dim-set membership it keys off is GPU_DIM_GEOM_KINDS,
+// tested in geoms/emphasis.test.ts.)
+// ---------------------------------------------------------------------------
+
+function marksCacheHint(opts: {
+  partial: boolean;
+  hasDimGeom: boolean;
+  interacting: boolean;
+}): "auto" | "never" {
+  if (!opts.partial) return "never";
+  if (opts.hasDimGeom) return "never";
+  return opts.interacting ? "never" : "auto";
+}
+
+describe("marks cache pin for dim charts (P5-T3)", () => {
+  test("a chart with a dim geom pins marks to 'never' even when settled", () => {
+    expect(marksCacheHint({ partial: true, hasDimGeom: true, interacting: false })).toBe("never");
+    expect(marksCacheHint({ partial: true, hasDimGeom: true, interacting: true })).toBe("never");
+  });
+
+  test("a pure-scatter chart (no dim geom) keeps 'auto' when settled, 'never' while interacting", () => {
+    expect(marksCacheHint({ partial: true, hasDimGeom: false, interacting: false })).toBe("auto");
+    expect(marksCacheHint({ partial: true, hasDimGeom: false, interacting: true })).toBe("never");
+  });
+
+  test("partial=false → always 'never' regardless of dim geom", () => {
+    expect(marksCacheHint({ partial: false, hasDimGeom: true, interacting: false })).toBe("never");
+    expect(marksCacheHint({ partial: false, hasDimGeom: false, interacting: false })).toBe("never");
+  });
+});