@weasel-js/labkit 1.0.4 → 1.2.0

package/src/state/view.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMemoryAdapter } from './adapters';
+import { createLabStore } from './store';
+import { as2DView, DEFAULT_VIEW } from './view';
+
+interface OrbitView {
+  yaw: number;
+  pitch: number;
+  distance: number;
+}
+
+const orbit: OrbitView = { yaw: 1.1, pitch: 0.3, distance: 9 };
+
+describe('as2DView', () => {
+  it('accepts the 2D shape', () => {
+    expect(as2DView({ zoom: 2, pan: { x: 1, y: 3 } })).toEqual({ zoom: 2, pan: { x: 1, y: 3 } });
+  });
+
+  it('copies rather than aliasing, so a caller cannot mutate the record', () => {
+    const source = { zoom: 2, pan: { x: 1, y: 3 } };
+    const out = as2DView(source);
+    expect(out).not.toBe(source);
+    expect(out?.pan).not.toBe(source.pan);
+  });
+
+  it('rejects an orbit view', () => {
+    expect(as2DView(orbit)).toBeNull();
+  });
+
+  it('rejects a partial 2D view rather than filling in a default', () => {
+    expect(as2DView({ zoom: 2 })).toBeNull();
+    expect(as2DView({ zoom: 2, pan: { x: 1 } })).toBeNull();
+  });
+
+  it('rejects things that are not objects', () => {
+    expect(as2DView(null)).toBeNull();
+    expect(as2DView(undefined)).toBeNull();
+    expect(as2DView(4)).toBeNull();
+  });
+});
+
+describe('a trial view labkit does not interpret', () => {
+  it('stores and returns a view shape that is not zoom/pan', () => {
+    const store = createLabStore({ storageKey: 'view-a', storage: createMemoryAdapter() });
+    store.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'gem',
+      config: {},
+      state: {},
+      view: DEFAULT_VIEW,
+    });
+
+    store.getState().updateTrialView('w1', orbit);
+
+    expect(store.getState().trials[0]?.view as OrbitView).toEqual(orbit);
+  });
+
+  it('round-trips that view through persistence', () => {
+    vi.useFakeTimers();
+    const mem = createMemoryAdapter();
+    const seed = createLabStore({ storageKey: 'view-b', storage: mem });
+    seed.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'gem',
+      config: {},
+      state: {},
+      view: orbit,
+    });
+    vi.advanceTimersByTime(500);
+    vi.useRealTimers();
+
+    const hydrated = createLabStore({ storageKey: 'view-b', storage: mem });
+    expect(hydrated.getState().trials[0]?.view as OrbitView).toEqual(orbit);
+  });
+});
+
+describe('an unchanged write costs no new record', () => {
+  it('returns the same trial object when setState returns its input', () => {
+    const store = createLabStore({ storageKey: 'identity-a', storage: createMemoryAdapter() });
+    store.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'gem',
+      config: {},
+      state: { n: 1 },
+      view: DEFAULT_VIEW,
+    });
+    const before = store.getState().trials[0];
+
+    store.getState().updateTrialState('w1', (prev: unknown) => prev);
+
+    // A trial re-renders on record identity, so allocating here would turn the
+    // standard React bail-out into a render loop.
+    expect(store.getState().trials[0]).toBe(before);
+  });
+
+  it('still replaces the record when the state actually changes', () => {
+    const store = createLabStore({ storageKey: 'identity-b', storage: createMemoryAdapter() });
+    store.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'gem',
+      config: {},
+      state: { n: 1 },
+      view: DEFAULT_VIEW,
+    });
+    const before = store.getState().trials[0];
+
+    store.getState().updateTrialState('w1', { n: 2 });
+
+    expect(store.getState().trials[0]).not.toBe(before);
+  });
+
+  it('returns the same trial object when the view is written unchanged', () => {
+    const store = createLabStore({ storageKey: 'identity-c', storage: createMemoryAdapter() });
+    store.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'gem',
+      config: {},
+      state: {},
+      view: orbit,
+    });
+    const before = store.getState().trials[0];
+
+    store.getState().updateTrialView('w1', orbit);
+
+    expect(store.getState().trials[0]).toBe(before);
+  });
+});

package/src/state/view.ts

@@ -0,0 +1,18 @@
+import type { ViewTransform } from '../instrument/types';
+
+/** The 2D view labkit has always shipped, and what a trial gets when it names no
+ *  other. Re-exported under its own name so a consumer can say which it means. */
+export type ViewTransform2D = ViewTransform;
+
+export const DEFAULT_VIEW: ViewTransform2D = { zoom: 1, pan: { x: 0, y: 0 } };
+
+/** A trial's view is opaque to labkit, so anything that needs the 2D shape — the
+ *  zoom chrome, `CanvasStack` — asks for it and handles not getting it. */
+export function as2DView(view: unknown): ViewTransform2D | null {
+  if (typeof view !== 'object' || view === null) return null;
+  const v = view as Partial<ViewTransform2D>;
+  if (typeof v.zoom !== 'number') return null;
+  if (typeof v.pan !== 'object' || v.pan === null) return null;
+  if (typeof v.pan.x !== 'number' || typeof v.pan.y !== 'number') return null;
+  return { zoom: v.zoom, pan: { x: v.pan.x, y: v.pan.y } };
+}

package/src/styles.less

@@ -1,6 +1,6 @@
 // Imports compile-time only. Component .less files are added in later steps.
 @import './theme/base.less';
-@import './lab/WorkspaceGrid.less';
+@import './lab/Workspace.less';
 @import './lab/LabShell.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Sidebar.less';
@@ -8,7 +8,7 @@
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
 @import './lab/Lab.less';
-@import './workspace/Workspace.less';
+@import './trial/Trial.less';
 @import './controls/ControlPanel.less';
 @import './canvas/CanvasStack.less';
 @import './layers/LayerList.less';

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],
+  );
+}