@weasel-js/labkit 1.1.0 → 1.2.0

package/src/surface/AGENTS.md

@@ -0,0 +1,64 @@
+# Surface — Agent Guide
+
+`src/surface/` lets a lab drive a renderer labkit does not own. labkit publishes
+rects, dirtiness, DPR and one rAF; the consumer keeps the GL.
+
+Use this rather than the `canvas` capability when the renderer is not labkit's —
+three.js, a raw WebGL context, anything with its own render loop. One canvas per
+trial is one WebGL context per trial, and browsers cap those around 8–16, so more
+than a few 3D tiles have to share one surface.
+
+## Files
+
+| File | Role |
+|---|---|
+| `rect.ts` | The `Rect` and `Box` types |
+| `composeRects.ts` | Tile boxes into surface-relative rects; both are viewport-relative, so it is a subtraction |
+| `deviceRect.ts` | `toDeviceRect` — y-flip and device-grid snapping for a GL viewport |
+| `useTiledSurface.ts` | ResizeObserver, dirty set, rAF coalescing, DPR |
+| `SurfaceContext.ts` | Carries the handle down |
+| `useSurfaceTile.ts` | `useSurfaceTile(id)`, `useSurface()`, `useSurfaceOptional()` |
+
+## Shape of a consumer
+
+```tsx
+const surface = useTiledSurface({
+  onFrame: ({ dirty, rects, dpr, size }) => {
+    renderer.setPixelRatio(Math.min(dpr, 2));
+    renderer.setSize(size.width, size.height, false);
+    for (const id of dirty) {
+      const rect = rects.get(id);
+      if (!rect) continue;
+      const v = toDeviceRect(rect, size.height, dpr);
+      // ... setViewport / setScissor / render
+    }
+  },
+});
+```
+
+`onFrame` carries **every** tile's rect, not only the dirty ones — a scissored
+draw has to know where it is drawing relative to a surface that may have resized
+under it.
+
+## The unit is a rect, not a trial
+
+`useSurfaceTile(id)` attaches to whatever element the surface should draw into. A
+trial may register one, or none: a trial holding a drawn pane beside an undrawn
+one contributes a single rect, and a trial with nothing to draw contributes none.
+
+## Traps
+
+- **`preserveDrawingBuffer` is the consumer's job and is usually required.** A
+  partial redraw touches one tile; without it the default framebuffer's contents
+  are undefined after the page composites, and every other tile goes black.
+- **Gutters lie outside every scissor.** Clear the whole surface when the tile set
+  changes, or a re-tile strands the old tiles' pixels between the new ones.
+- **A tile that moves without resizing** is already handled: `Workspace`
+  invalidates rects off the grid's own `node.placementChanged`. A host that moves
+  something the grid does not know about calls `invalidateRects()` itself.
+
+## Testing
+
+No WebGL in the suite. The arithmetic is pure and tested directly; the hook is
+tested with `getBoundingClientRect` stubbed per element, because jsdom measures
+everything as zero.

package/src/surface/SurfaceContext.ts

@@ -0,0 +1,5 @@
+import { createContext } from 'react';
+import type { SurfaceHandle } from './useTiledSurface';
+
+/** Null when no surface owner is above — a lab with no shared surface at all. */
+export const SurfaceContext = createContext<SurfaceHandle | null>(null);

package/src/surface/composeRects.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { composeRects, rectsEqual } from './composeRects';
+import type { Box } from './rect';
+
+const box = (left: number, top: number, width: number, height: number): Box => ({
+  left,
+  top,
+  width,
+  height,
+});
+
+describe('composeRects', () => {
+  it('reports tiles relative to the container origin', () => {
+    const out = composeRects(box(100, 50, 800, 600), new Map([['a', box(140, 90, 200, 150)]]));
+    expect(out.get('a')).toEqual({ x: 40, y: 40, w: 200, h: 150 });
+  });
+
+  it('works through a nested offset parent, because both are viewport-relative', () => {
+    const out = composeRects(box(0, 0, 800, 600), new Map([['deep', box(310, 220, 90, 40)]]));
+    expect(out.get('deep')).toEqual({ x: 310, y: 220, w: 90, h: 40 });
+  });
+
+  it('handles a container scrolled off the top of the viewport', () => {
+    const out = composeRects(box(0, -200, 800, 600), new Map([['a', box(0, -150, 100, 100)]]));
+    expect(out.get('a')).toEqual({ x: 0, y: 50, w: 100, h: 100 });
+  });
+
+  it('returns one entry per tile', () => {
+    const out = composeRects(
+      box(0, 0, 800, 600),
+      new Map([
+        ['a', box(0, 0, 10, 10)],
+        ['b', box(20, 0, 10, 10)],
+      ]),
+    );
+    expect([...out.keys()]).toEqual(['a', 'b']);
+  });
+});
+
+describe('rectsEqual', () => {
+  it('is false when the previous rect is missing', () => {
+    expect(rectsEqual(undefined, { x: 0, y: 0, w: 1, h: 1 })).toBe(false);
+  });
+
+  it('compares every field', () => {
+    const r = { x: 1, y: 2, w: 3, h: 4 };
+    expect(rectsEqual({ ...r }, r)).toBe(true);
+    expect(rectsEqual({ ...r, h: 5 }, r)).toBe(false);
+  });
+});

package/src/surface/composeRects.ts

@@ -0,0 +1,19 @@
+import type { Box, Rect } from './rect';
+
+/** Every tile's box expressed against the container's origin. */
+export function composeRects(container: Box, tiles: ReadonlyMap<string, Box>): Map<string, Rect> {
+  const out = new Map<string, Rect>();
+  for (const [id, tile] of tiles) {
+    out.set(id, {
+      x: tile.left - container.left,
+      y: tile.top - container.top,
+      w: tile.width,
+      h: tile.height,
+    });
+  }
+  return out;
+}
+
+export function rectsEqual(a: Rect | undefined, b: Rect): boolean {
+  return a !== undefined && a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
+}

package/src/surface/deviceRect.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { toDeviceRect } from './deviceRect';
+
+const onGrid = (v: number, dpr: number) => Math.abs(v * dpr - Math.round(v * dpr)) < 1e-9;
+
+describe('toDeviceRect', () => {
+  it('measures y from the bottom of the surface', () => {
+    const r = toDeviceRect({ x: 0, y: 0, w: 40, h: 10 }, 100, 1);
+    expect(r.y).toBe(90);
+    expect(r.h).toBe(10);
+  });
+
+  it('leaves x and width alone', () => {
+    const r = toDeviceRect({ x: 5, y: 0, w: 40, h: 10 }, 100, 1);
+    expect(r.x).toBe(5);
+    expect(r.w).toBe(40);
+  });
+
+  it('puts every edge on the device grid', () => {
+    const r = toDeviceRect({ x: 33.3, y: 7.7, w: 33.3, h: 21.4 }, 100, 2);
+    expect(onGrid(r.x, 2)).toBe(true);
+    expect(onGrid(r.x + r.w, 2)).toBe(true);
+    expect(onGrid(r.y, 2)).toBe(true);
+    expect(onGrid(r.y + r.h, 2)).toBe(true);
+  });
+
+  it('does not strand a column between neighbours', () => {
+    const a = toDeviceRect({ x: 0, y: 0, w: 33.3333, h: 10 }, 100, 2);
+    const b = toDeviceRect({ x: 33.3333, y: 0, w: 33.3333, h: 10 }, 100, 2);
+    const c = toDeviceRect({ x: 66.6666, y: 0, w: 33.3334, h: 10 }, 100, 2);
+    expect(a.x + a.w).toBe(b.x);
+    expect(b.x + b.w).toBe(c.x);
+  });
+
+  it('snaps a stacked pair without overlapping them', () => {
+    const top = toDeviceRect({ x: 0, y: 0, w: 10, h: 33.3333 }, 100, 3);
+    const bottom = toDeviceRect({ x: 0, y: 33.3333, w: 10, h: 33.3333 }, 100, 3);
+    expect(bottom.y + bottom.h).toBe(top.y);
+  });
+});

package/src/surface/deviceRect.ts

@@ -0,0 +1,19 @@
+import type { Rect } from './rect';
+
+/**
+ * A DOM rect as a GL viewport rect: origin at the bottom-left, every edge snapped
+ * to the device-pixel grid. Still CSS pixels, because three.js applies its own
+ * pixel ratio — snapping here is what stops a tile and its neighbour rounding
+ * apart and leaving a hairline column between them.
+ */
+export function toDeviceRect(rect: Rect, surfaceHeight: number, dpr: number): Rect {
+  const snap = (v: number) => Math.round(v * dpr) / dpr;
+  const x = snap(rect.x);
+  const y = snap(surfaceHeight - rect.y - rect.h);
+  return {
+    x,
+    y,
+    w: snap(rect.x + rect.w) - x,
+    h: snap(surfaceHeight - rect.y) - y,
+  };
+}

package/src/surface/index.ts

@@ -0,0 +1,7 @@
+export { composeRects, rectsEqual } from './composeRects';
+export { toDeviceRect } from './deviceRect';
+export type { Box, Rect } from './rect';
+export { SurfaceContext } from './SurfaceContext';
+export { useSurface, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+export type { SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions } from './useTiledSurface';
+export { useTiledSurface } from './useTiledSurface';

package/src/surface/rect.ts

@@ -0,0 +1,16 @@
+/** A box in CSS pixels, measured from the surface's own top-left corner. */
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The subset of `DOMRect` this package reads. Accepting the subset rather than
+ *  `DOMRect` is what lets the pure functions be tested without a DOM. */
+export interface Box {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}

package/src/surface/useSurfaceTile.test.tsx

@@ -0,0 +1,67 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SurfaceContext } from './SurfaceContext';
+import { useSurface, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+import type { SurfaceHandle } from './useTiledSurface';
+
+function fakeHandle(): SurfaceHandle {
+  return {
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    invalidateRects: vi.fn(),
+    registerTile: vi.fn(),
+    containerRef: vi.fn(),
+  };
+}
+
+function Tile({ id }: { id: string }) {
+  const ref = useSurfaceTile(id);
+  return <div ref={ref} data-testid={id} />;
+}
+
+describe('useSurfaceTile', () => {
+  it('registers its element with the surface on mount', () => {
+    const handle = fakeHandle();
+    const { getByTestId } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Tile id="a" />
+      </SurfaceContext.Provider>,
+    );
+    expect(handle.registerTile).toHaveBeenCalledWith('a', getByTestId('a'));
+  });
+
+  it('unregisters on unmount', () => {
+    const handle = fakeHandle();
+    const { unmount } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Tile id="a" />
+      </SurfaceContext.Provider>,
+    );
+    unmount();
+    expect(handle.registerTile).toHaveBeenCalledWith('a', null);
+  });
+
+  it('is inert with no surface above it, so a 2D lab is unaffected', () => {
+    expect(() => render(<Tile id="a" />)).not.toThrow();
+  });
+});
+
+describe('useSurface', () => {
+  it('throws outside a provider, because a caller asking for it needs one', () => {
+    function Consumer() {
+      useSurface();
+      return null;
+    }
+    expect(() => render(<Consumer />)).toThrow(/requires a surface/i);
+  });
+
+  it('returns null from the optional form outside a provider', () => {
+    let seen: SurfaceHandle | null | undefined;
+    function Consumer() {
+      seen = useSurfaceOptional();
+      return null;
+    }
+    render(<Consumer />);
+    expect(seen).toBeNull();
+  });
+});

package/src/surface/useSurfaceTile.ts

@@ -0,0 +1,32 @@
+import { useCallback, useContext } from 'react';
+import { SurfaceContext } from './SurfaceContext';
+import type { SurfaceHandle } from './useTiledSurface';
+
+/** The surface above, or null. Use this where a surface is genuinely optional. */
+export function useSurfaceOptional(): SurfaceHandle | null {
+  return useContext(SurfaceContext);
+}
+
+/** The surface above. Throws where a caller cannot work without one. */
+export function useSurface(): SurfaceHandle {
+  const surface = useContext(SurfaceContext);
+  if (!surface) throw new Error('[labkit] useSurface requires a surface owner above it');
+  return surface;
+}
+
+/**
+ * A ref callback that publishes this element's rect to the surface under `id`.
+ *
+ * Attach it to whichever element the surface should draw into — that is not
+ * necessarily the trial's own element, since a trial may hold a drawn pane beside
+ * an undrawn one, or none at all.
+ */
+export function useSurfaceTile(id: string): (el: HTMLElement | null) => void {
+  const surface = useSurfaceOptional();
+  return useCallback(
+    (el: HTMLElement | null) => {
+      surface?.registerTile(id, el);
+    },
+    [surface, id],
+  );
+}

package/src/surface/useTiledSurface.test.tsx

@@ -0,0 +1,231 @@
+import { act, render } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
+import { useTiledSurface } from './useTiledSurface';
+
+/** jsdom measures everything as zero, so each element is given a box by hand. */
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+interface HarnessProps {
+  frames: SurfaceFrame[];
+  onHandle: (h: SurfaceHandle) => void;
+}
+
+function Harness({ frames, onHandle }: HarnessProps) {
+  const surface = useTiledSurface({
+    onFrame: (f) => {
+      frames.push(f);
+    },
+  });
+  useEffect(() => {
+    onHandle(surface);
+  }, [surface, onHandle]);
+  return (
+    <div
+      data-testid="stage"
+      ref={(el) => {
+        if (!el) return;
+        stubBox(el, 0, 0, 800, 600);
+        surface.containerRef(el);
+      }}
+    >
+      <div
+        data-testid="a"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 0, 0, 400, 600);
+          surface.registerTile('a', el);
+        }}
+      />
+      <div
+        data-testid="b"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 400, 0, 400, 600);
+          surface.registerTile('b', el);
+        }}
+      />
+    </div>
+  );
+}
+
+/** Runs every pending rAF callback. */
+function flushFrames(): void {
+  act(() => {
+    vi.advanceTimersByTime(64);
+  });
+}
+
+describe('useTiledSurface', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('coalesces three invalidations in one tick into a single frame', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.invalidate('a');
+      handle?.invalidate('b');
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames).toHaveLength(1);
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+  });
+
+  it('fires nothing on a clean tick', () => {
+    const frames: SurfaceFrame[] = [];
+    render(<Harness frames={frames} onHandle={() => {}} />);
+    flushFrames();
+    frames.length = 0;
+    flushFrames();
+    expect(frames).toHaveLength(0);
+  });
+
+  it('carries every tile rect, not only the dirty ones', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidate('a'));
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])]).toEqual(['a']);
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 400, y: 0, w: 400, h: 600 });
+  });
+
+  it('reports the surface size and dpr', () => {
+    vi.stubGlobal('devicePixelRatio', 3);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidateAll());
+    flushFrames();
+
+    expect(frames[0]?.dpr).toBe(3);
+    expect(frames[0]?.size).toEqual({ width: 800, height: 600 });
+  });
+
+  it('marks every tile dirty when the dpr changes', () => {
+    vi.stubGlobal('devicePixelRatio', 1);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    vi.stubGlobal('devicePixelRatio', 2);
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+    expect(frames[0]?.dpr).toBe(2);
+  });
+
+  it('re-measures on invalidateRects, which is how a moved tile is caught', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    const { getByTestId } = render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    // A sibling reflow slides tile b left. ResizeObserver sees no size change.
+    stubBox(getByTestId('b'), 320, 0, 400, 600);
+
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 320, y: 0, w: 400, h: 600 });
+  });
+
+  it('drops a tile that unregisters', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.registerTile('b', null);
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames[0]?.rects.has('b')).toBe(false);
+  });
+});