insomni-plot 0.1.0-alpha.0

package/src/heatmap.test.ts

@@ -0,0 +1,320 @@
+// @vitest-environment jsdom
+import { describe, expect, test, vi } from "vite-plus/test";
+
+import { viridis } from "./colors.ts";
+import { HeatmapCpuRenderer } from "./heatmap/cpu.ts";
+import { HeatmapGpuRenderer } from "./heatmap/gpu.ts";
+import { resolveSpec, type HeatmapSpec } from "./heatmap/types.ts";
+import { Layer } from "insomni";
+
+interface Pt {
+  x: number;
+  y: number;
+  w?: number;
+}
+
+function baseSpec(overrides: Partial<HeatmapSpec<Pt>> = {}): HeatmapSpec<Pt> {
+  return {
+    x: (d) => d.x,
+    y: (d) => d.y,
+    bins: [4, 4],
+    xDomain: [0, 4],
+    yDomain: [0, 4],
+    frame: { x: 0, y: 0, width: 40, height: 40 },
+    colorMap: viridis,
+    ...overrides,
+  };
+}
+
+function cpu(
+  data: readonly Pt[],
+  overrides: Partial<HeatmapSpec<Pt>> = {},
+): HeatmapCpuRenderer<Pt> {
+  return new HeatmapCpuRenderer(resolveSpec(baseSpec(overrides)), data);
+}
+
+// ---------------------------------------------------------------------------
+// Spec validation (lives in resolveSpec, shared by both renderers)
+// ---------------------------------------------------------------------------
+
+describe("heatmap spec validation", () => {
+  test("rejects non-integer bin counts", () => {
+    expect(() => resolveSpec(baseSpec({ bins: [0, 4] }))).toThrow(/positive integers/);
+    expect(() => resolveSpec(baseSpec({ bins: [4, 2.5] }))).toThrow(/positive integers/);
+  });
+
+  test("rejects non-positive weightScale", () => {
+    expect(() => resolveSpec(baseSpec({ weightScale: 0 }))).toThrow(/weightScale/);
+    expect(() => resolveSpec(baseSpec({ weightScale: -1 }))).toThrow(/weightScale/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CPU binning — HeatmapCpuRenderer.build() returns v3 Layer drawables
+// ---------------------------------------------------------------------------
+
+describe("HeatmapCpuRenderer.build — CPU binning", () => {
+  test("empty data produces a v3 Layer with no rects", () => {
+    const [layer] = cpu([]).build();
+    expect(layer).toBeInstanceOf(Layer);
+    expect((layer as Layer).shapeCount).toBe(0);
+  });
+
+  test("emits one rect per non-empty cell", () => {
+    // 4×4 grid over [0,4]×[0,4] → cells at integer coords 0..3.
+    // Points at (0.5, 0.5), (0.5, 0.5), (2.5, 1.5) → 2 distinct cells.
+    const [layer] = cpu([
+      { x: 0.5, y: 0.5 },
+      { x: 0.5, y: 0.5 },
+      { x: 2.5, y: 1.5 },
+    ]).build();
+    expect((layer as Layer).shapeCount).toBe(2);
+  });
+
+  test("drops data outside the domain", () => {
+    const [layer] = cpu([
+      { x: -1, y: 0.5 },
+      { x: 4.5, y: 0.5 }, // exactly at upper bound is excluded (tx >= 1)
+      { x: 4, y: 2 }, // tx == 1 excluded
+      { x: 1, y: 1 },
+    ]).build();
+    expect((layer as Layer).shapeCount).toBe(1);
+  });
+
+  test("rect positions align with the frame", () => {
+    const frame = { x: 100, y: 50, width: 40, height: 40 };
+    // bins 4×4 over [0,4]×[0,4] → 10px cells
+    const [layer] = cpu([{ x: 2.5, y: 1.5 }], { frame }).build();
+    const l = layer as Layer;
+    const cmd = l.pack.commands[0]!;
+    // v3 packs a typeFlag (number) per command rather than a "shapes" string;
+    // a rect lives in the rect-kind span, so there is exactly one command.
+    expect(l.pack.commands.length).toBe(1);
+    // ix = floor(2.5 * 4 / 4) = 2 → cell x = 100 + 2*10 = 120 (left edge)
+    // iy is flipped so higher data-y is higher on screen:
+    //   raw = floor(1.5 * 4 / 4) = 1 → iy = ny-1-raw = 2 → cell y = 50 + 2*10 = 70
+    // The 10×10 cell rect therefore centers at (125, 75). Assert via the AABB
+    // center (the v3 SDF rect pads its AABB by a feather margin for AA, so the
+    // raw min/max carry an implementation-defined inset — the center does not).
+    const aabb = l.pack.aabbs;
+    const cx = (aabb[0]! + aabb[2]!) / 2;
+    const cy = (aabb[1]! + aabb[3]!) / 2;
+    expect(cx).toBeCloseTo(125);
+    expect(cy).toBeCloseTo(75);
+    void cmd;
+  });
+
+  test("uses weight accessor when provided", () => {
+    const [layer] = cpu(
+      [
+        { x: 0.5, y: 0.5, w: 5 },
+        { x: 0.5, y: 0.5, w: 7 },
+      ],
+      { weight: (d) => d.w ?? 1 },
+    ).build();
+    // One cell, sum weight = 12 → fill should be at t=1 of the palette.
+    expect((layer as Layer).shapeCount).toBe(1);
+  });
+
+  test("setData re-bins on next build call", () => {
+    const renderer = cpu([{ x: 0.5, y: 0.5 }]);
+    const [first] = renderer.build();
+    expect((first as Layer).shapeCount).toBe(1);
+
+    renderer.setData([
+      { x: 0.5, y: 0.5 },
+      { x: 2.5, y: 2.5 },
+      { x: 3.5, y: 0.5 },
+    ]);
+    const [second] = renderer.build();
+    expect((second as Layer).shapeCount).toBe(3);
+  });
+
+  test("degenerate domain produces an empty layer", () => {
+    const [layer] = cpu([{ x: 1, y: 1 }], { xDomain: [2, 2] }).build();
+    expect((layer as Layer).shapeCount).toBe(0);
+  });
+
+  test("getMax reflects the largest bin weight", () => {
+    const renderer = cpu(
+      [
+        { x: 0.5, y: 0.5, w: 5 },
+        { x: 0.5, y: 0.5, w: 7 },
+        { x: 2.5, y: 2.5, w: 3 },
+      ],
+      { weight: (d) => d.w ?? 1 },
+    );
+    expect(renderer.getMax()).toBe(12);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// GPU build — caller-driven v3 compute seam + sprite Layer
+//
+// Replaces the dropped v1 SceneProducer / GPUProducerContext / enqueueCompute
+// protocol. The new contract:
+//   build(root, renderer) → Layer   (space:"ui", one sprite quad)
+//   - queues exactly one renderer.compute(cb) when binning is dirty
+//   - cb opens its own compute pass and dispatches the binning kernels
+//   - returns a sprite Layer (spritePack with count 1) reading the GPU output
+//   - the sprite Layer is cleared + re-pushed every frame (no bumpVersion needed)
+//
+// jsdom has no real WebGPU, so we drive the renderer against a recording fake
+// device/root that hands back opaque tokens for every resource. This proves the
+// seam wiring (compute callback registered + runs, sprite Layer produced) without
+// asserting GPU pixel behaviour (covered by the renderer's browser suite).
+// ---------------------------------------------------------------------------
+
+// jsdom defines no WebGPU globals. `ensureState` reads the usage/visibility
+// flag enums to build descriptors; the values are irrelevant to the recording
+// fake (it ignores descriptors), so we stub them with the real bit values.
+const g = globalThis as Record<string, unknown>;
+g.GPUBufferUsage ??= {
+  STORAGE: 0x80,
+  COPY_DST: 0x08,
+  COPY_SRC: 0x04,
+  UNIFORM: 0x40,
+  MAP_READ: 0x01,
+};
+g.GPUTextureUsage ??= {
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+  COPY_DST: 0x10,
+};
+g.GPUShaderStage ??= { COMPUTE: 0x04, VERTEX: 0x01, FRAGMENT: 0x02 };
+
+function fakeComputePass() {
+  return {
+    setPipeline: vi.fn(),
+    setBindGroup: vi.fn(),
+    dispatchWorkgroups: vi.fn(),
+    end: vi.fn(),
+  };
+}
+
+function fakeEncoder(pass: ReturnType<typeof fakeComputePass>) {
+  return {
+    beginComputePass: vi.fn(() => pass),
+  };
+}
+
+interface FakeGpu {
+  // The TgpuRoot stand-in passed to build().
+  root: { device: GPUDevice; createBuffer: ReturnType<typeof vi.fn> };
+  // The v3 Renderer2D stand-in.
+  renderer: { compute: ReturnType<typeof vi.fn> };
+  pass: ReturnType<typeof fakeComputePass>;
+  // Resolves the most recently queued compute callback against the fake encoder.
+  runQueuedCompute(): void;
+}
+
+function makeFakeGpu(): FakeGpu {
+  const token = (label: string) => ({ __token: label });
+  const device = {
+    createBuffer: vi.fn(() => ({ destroy: vi.fn() })),
+    createTexture: vi.fn(() => ({ createView: vi.fn(() => token("view")), destroy: vi.fn() })),
+    createShaderModule: vi.fn(() => token("module")),
+    createBindGroupLayout: vi.fn(() => token("bgl")),
+    createPipelineLayout: vi.fn(() => token("pll")),
+    createComputePipeline: vi.fn(() => token("pipeline")),
+    createBindGroup: vi.fn(() => token("bg")),
+    queue: { writeBuffer: vi.fn(), writeTexture: vi.fn() },
+  } as unknown as GPUDevice;
+
+  // root.createBuffer(...).$usage("storage") → a thing with `.buffer`.
+  const root = {
+    device,
+    createBuffer: vi.fn(() => ({
+      $usage: vi.fn(() => ({ buffer: token("sprite-buffer"), destroy: vi.fn() })),
+    })),
+  };
+
+  const pass = fakeComputePass();
+  const queued: Array<(encoder: GPUCommandEncoder) => void> = [];
+  const renderer = {
+    compute: vi.fn((cb: (encoder: GPUCommandEncoder) => void) => queued.push(cb)),
+  };
+
+  return {
+    root: root as unknown as FakeGpu["root"],
+    renderer,
+    pass,
+    runQueuedCompute() {
+      const cb = queued.at(-1);
+      if (cb) cb(fakeEncoder(pass) as unknown as GPUCommandEncoder);
+    },
+  };
+}
+
+describe("HeatmapGpuRenderer.build — v3 compute seam", () => {
+  test("returns a sprite Layer and queues a compute callback", () => {
+    const gpu = new HeatmapGpuRenderer(resolveSpec(baseSpec()), [
+      { x: 0.5, y: 0.5 },
+      { x: 2.5, y: 1.5 },
+    ]);
+    const fake = makeFakeGpu();
+
+    const drawable = gpu.build(fake.root as never, fake.renderer as never);
+
+    expect(drawable).toBeInstanceOf(Layer);
+    // spritePack holds one quad pointing at the output texture.
+    expect(drawable.spritePack?.count).toBe(1);
+    // The dirty first build must register exactly one compute callback.
+    expect(fake.renderer.compute).toHaveBeenCalledTimes(1);
+    gpu.destroy();
+  });
+
+  test("queued callback opens its own compute pass and dispatches", () => {
+    const gpu = new HeatmapGpuRenderer(resolveSpec(baseSpec()), [{ x: 0.5, y: 0.5 }]);
+    const fake = makeFakeGpu();
+
+    gpu.build(fake.root as never, fake.renderer as never);
+    fake.runQueuedCompute();
+
+    // The callback owns its pass (caller-driven), and runs the four binning
+    // kernels (clear, splat, reduce, colormap) → at least 4 dispatches + end.
+    expect(fake.pass.end).toHaveBeenCalledTimes(1);
+    expect(fake.pass.dispatchWorkgroups.mock.calls.length).toBeGreaterThanOrEqual(4);
+    gpu.destroy();
+  });
+
+  test("clean build skips compute; dirty build re-queues it (partial-redraw contract)", () => {
+    const gpu = new HeatmapGpuRenderer(resolveSpec(baseSpec()), [{ x: 0.5, y: 0.5 }]);
+    const fake = makeFakeGpu();
+
+    const drawable = gpu.build(fake.root as never, fake.renderer as never);
+
+    // Clean build: no new data, no compute queued; same Layer identity returned.
+    const again = gpu.build(fake.root as never, fake.renderer as never);
+    expect(again).toBe(drawable);
+    expect(fake.renderer.compute).toHaveBeenCalledTimes(1);
+    // Sprite is still present after second build (re-pushed each frame).
+    expect(again.spritePack?.count).toBe(1);
+
+    // Dirty build: data changed → compute re-queued.
+    gpu.setData([
+      { x: 0.5, y: 0.5 },
+      { x: 2.5, y: 2.5 },
+    ]);
+    gpu.build(fake.root as never, fake.renderer as never);
+    expect(fake.renderer.compute).toHaveBeenCalledTimes(2);
+    gpu.destroy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+describe("heatmap renderers — lifecycle", () => {
+  test("GPU destroy() is safe before any build (no GPU state)", () => {
+    const gpu = new HeatmapGpuRenderer(resolveSpec(baseSpec()), [{ x: 1, y: 1 }]);
+    expect(() => gpu.destroy()).not.toThrow();
+  });
+
+  test("GPU destroy() is idempotent", () => {
+    const gpu = new HeatmapGpuRenderer(resolveSpec(baseSpec()), []);
+    gpu.destroy();
+    expect(() => gpu.destroy()).not.toThrow();
+  });
+});

package/src/heatmap.ts

@@ -0,0 +1,123 @@
+// ---------------------------------------------------------------------------
+// heatmapLayer — heatmap controller over a CPU and a GPU renderer.
+// ---------------------------------------------------------------------------
+// v3 dropped the v1 SceneProducer / GPUProducerContext / ProducedDrawable draw
+// protocol (decisions.md T4 = caller-driven `renderer.compute(cb)` + drawable
+// Layer). This controller no longer implements `SceneProducer`; instead
+// the chart layer decides CPU-vs-GPU and calls the matching build method:
+//
+//   - GPU (interactive WebGPU): `buildGPU({ renderer })` threads
+//     `resolveRoot(renderer.device)` + the v3 renderer into the GPU renderer.
+//     The binning compute is queued onto the renderer's `compute(cb)` seam and
+//     a single sprite `Layer` (space:"ui") is returned (drawn post-main).
+//   - CPU (SVG export / no device): `buildCPU()` returns v3 `Layer`s of rects
+//     (or a rasterized image layer for dense grids).
+//
+// The capability switch lives HERE (the chart layer), never inside the
+// renderer's `render()`.
+
+import { resolveRoot } from "insomni/internal";
+import type { Layer, Renderer2D } from "insomni";
+
+import { HeatmapCpuRenderer, type HeatmapCpuDrawable } from "./heatmap/cpu.ts";
+import { HeatmapGpuRenderer } from "./heatmap/gpu.ts";
+import { resolveSpec, type HeatmapSpec, type ResolvedSpec } from "./heatmap/types.ts";
+
+export type { HeatmapSpec } from "./heatmap/types.ts";
+
+/** Options threaded into the GPU build path. */
+export interface HeatmapBuildOptions {
+  /** The v3 renderer whose `compute(cb)` seam the binning passes are recorded onto. */
+  renderer: Renderer2D;
+}
+
+export interface HeatmapProducer<T> {
+  /** Swap the underlying data. Invalidates both CPU and GPU bin state. */
+  setData(data: readonly T[]): void;
+  /**
+   * Largest bin weight currently visible. Triggers a (cheap) CPU rebin if
+   * needed. Useful when wiring a continuous color-bar legend whose domain
+   * tracks the actual data range. Returns `0` when no data is in view.
+   */
+  getMax(): number;
+  /**
+   * GPU path — queues the binning compute onto `renderer.compute(cb)` and returns
+   * a `space:"ui"` sprite {@link Layer} (a single quad covering the frame,
+   * sampling the compute-written output texture) to draw post-main. The renderer's
+   * device owns the GPU buffers/textures via `resolveRoot(renderer.device)`.
+   */
+  buildGPU(opts: HeatmapBuildOptions): Layer;
+  /**
+   * CPU path — returns v3 `Layer`s (vector rects) or a rasterized image layer.
+   * Used by the SVG export path and any device-less consumer.
+   */
+  buildCPU(): readonly HeatmapCpuDrawable[];
+  destroy(): void;
+}
+
+export function heatmapLayer<T>(data: readonly T[], spec: HeatmapSpec<T>): HeatmapProducer<T> {
+  return new HeatmapProducerImpl(data, spec);
+}
+
+class HeatmapProducerImpl<T> implements HeatmapProducer<T> {
+  private readonly resolved: ResolvedSpec<T>;
+  private readonly cpu: HeatmapCpuRenderer<T>;
+  private readonly gpu: HeatmapGpuRenderer<T>;
+  private unsubscribeViewport: (() => void) | null = null;
+
+  constructor(data: readonly T[], spec: HeatmapSpec<T>) {
+    this.resolved = resolveSpec(spec);
+    this.cpu = new HeatmapCpuRenderer(this.resolved, data);
+    this.gpu = new HeatmapGpuRenderer(this.resolved, data);
+    if (this.resolved.viewport) {
+      this.unsubscribeViewport = this.resolved.viewport.onChange(() => {
+        this.cpu.markDirty();
+        this.gpu.markDirty();
+      });
+    }
+  }
+
+  setData(data: readonly T[]): void {
+    this.cpu.setData(data);
+    this.gpu.setData(data);
+  }
+
+  getMax(): number {
+    this.syncFromViewport();
+    return this.cpu.getMax();
+  }
+
+  buildCPU(): readonly HeatmapCpuDrawable[] {
+    this.syncFromViewport();
+    return this.cpu.build();
+  }
+
+  buildGPU(opts: HeatmapBuildOptions): Layer {
+    this.syncFromViewport();
+    // v3's Renderer2D exposes `device` but not its TgpuRoot — resolve one from
+    // the device (cached per device by `resolveRoot`).
+    const root = resolveRoot(opts.renderer.device);
+    return this.gpu.build(root, opts.renderer);
+  }
+
+  destroy(): void {
+    if (this.unsubscribeViewport) {
+      this.unsubscribeViewport();
+      this.unsubscribeViewport = null;
+    }
+    this.gpu.destroy();
+  }
+
+  /** Pull current visible domain + frame off the viewport, if one is attached. */
+  private syncFromViewport(): void {
+    const vp = this.resolved.viewport;
+    if (!vp) return;
+    const xd = vp.visibleXDomain as readonly [number, number];
+    const yd = vp.visibleYDomain as readonly [number, number];
+    this.resolved.x0 = xd[0];
+    this.resolved.x1 = xd[1];
+    this.resolved.y0 = yd[0];
+    this.resolved.y1 = yd[1];
+    this.resolved.frame = vp.frame;
+  }
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./grammar/index.ts";

package/src/index.ts

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// insomni-plot — grammar-of-graphics API
+// ---------------------------------------------------------------------------
+// The high-level grammar lives at the package root. Low-level imperative
+// primitives (scales, axes, *Mark builders, viewport, navigator, etc.) are
+// available at "insomni-plot/core".
+
+export * from "./grammar/index.ts";

package/src/interactions.d.ts

@@ -0,0 +1,48 @@
+import { type FlingOptions } from "insomni";
+import type { DataViewport } from "./viewport.ts";
+export type AxisSelection = "x" | "y" | "xy" | "none";
+export interface BindDataViewportOptions {
+    /** Enable pointer drag pan. Default: true. */
+    drag?: boolean;
+    /** Enable mouse-wheel zoom. Default: true. */
+    wheel?: boolean;
+    /** Enable two-finger pinch (touch). Default: true. */
+    pinch?: boolean;
+    /** SmoothDamp time constant (seconds). `0` = instant (no smoothing). Default: `0`. */
+    smoothTime?: number;
+    /**
+     * Drag-release fling. `true` enables with defaults, `false` disables, or
+     * pass an object to tune. Default: off (fling on a chart feels disorienting).
+     */
+    fling?: boolean | FlingOptions;
+    /**
+     * Axes that respond to drag / pinch pan. Default: derived from axis types
+     * (continuous/time axes pan; band axes don't).
+     */
+    pan?: AxisSelection;
+    /** Axes that respond to wheel / pinch zoom. Default: derived from axis types. */
+    zoom?: AxisSelection;
+    /** Multiplier applied to wheel deltaY. Default: 0.001. */
+    wheelSensitivity?: number;
+    /**
+     * When true, Shift while wheeling zooms Y only; Meta / Ctrl zoom X only.
+     * Default: true.
+     */
+    axisModifiers?: boolean;
+}
+export interface DataViewportBinding {
+    readonly mode: "data";
+    /** True while the user is actively dragging or pinching. */
+    readonly interacting: boolean;
+    /** True while a drag-release fling is still decaying. */
+    readonly flinging: boolean;
+    /** Hard disable. */
+    enabled: boolean;
+    /** Advance smoothing / fling by `dt` seconds and apply pending pan. */
+    update(dt: number): void;
+    /** Immediately cancel any pending smoothing and fling. */
+    stopAnimation(): void;
+    /** Remove all listeners and release any pending state. */
+    destroy(): void;
+}
+export declare function bindDataViewport<X, Y>(viewport: DataViewport<X, Y>, element: HTMLElement, options?: BindDataViewportOptions): DataViewportBinding;