@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/src/primitives/ZoomControl.tsx

@@ -0,0 +1,76 @@
+import { NumberField, Slider } from '../passthrough/weasel-ui';
+
+/** Props for `<ZoomControl>`. */
+export interface ZoomControlProps {
+  /** Current zoom as a scale factor: 1 is actual size. */
+  zoom: number;
+  /** Fired continuously while the slider drags. */
+  onZoomChange: (zoom: number) => void;
+  /** Fired when a drag settles or the field is committed. Defaults to
+   *  `onZoomChange`. */
+  onZoomCommit?: (zoom: number) => void;
+  /** Smallest selectable zoom. Defaults to 0.1 (10%). */
+  min?: number;
+  /** Largest selectable zoom. Defaults to 8 (800%). */
+  max?: number;
+  className?: string;
+}
+
+// Zoom is perceptually geometric — halving is as big a step as doubling — so
+// the slider runs on log2 and 100% lands mid-track for a symmetric range.
+const toTrack = (zoom: number): number => Math.log2(zoom);
+const fromTrack = (v: number): number => 2 ** v;
+
+const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));
+
+/** Zoom as a log-scaled slider with an editable percentage beside it. Pair it
+ *  with zoom-in / zoom-out buttons in a `<Toolbar.Group>`; this component owns
+ *  only the continuous part. */
+export function ZoomControl({
+  zoom,
+  onZoomChange,
+  onZoomCommit,
+  min = 0.1,
+  max = 8,
+  className,
+}: ZoomControlProps) {
+  const commit = onZoomCommit ?? onZoomChange;
+  const emit = (track: number, done: boolean): void => {
+    const next = clamp(fromTrack(track), min, max);
+    (done ? commit : onZoomChange)(next);
+  };
+
+  return (
+    <div className={`lk-zoom${className ? ` ${className}` : ''}`}>
+      <Slider
+        className="lk-zoom__slider"
+        ariaLabel="Zoom"
+        min={toTrack(min)}
+        max={toTrack(max)}
+        // Detents at the octaves plus actual size, so 25/50/100/200/400% are
+        // reachable by drag rather than only by typing.
+        stops={[-2, -1, 0, 1, 2]}
+        thumbs={[{ value: clamp(toTrack(zoom), toTrack(min), toTrack(max)) }]}
+        onInput={(next) => emit(next[0].value, false)}
+        onChange={(next) => emit(next[0].value, true)}
+        readoutPlacement="none"
+      />
+      {/* `style: 'percent'` formats a fraction, so the field carries the scale
+          factor itself and renders 0.5 as "50%". */}
+      <NumberField
+        className="lk-zoom__field"
+        aria-label="Zoom"
+        value={zoom}
+        minValue={min}
+        maxValue={max}
+        step={0.01}
+        hideSteppers
+        formatOptions={{ style: 'percent', maximumFractionDigits: 0 }}
+        onChange={(next) => {
+          if (!Number.isFinite(next)) return;
+          commit(clamp(next, min, max));
+        }}
+      />
+    </div>
+  );
+}

package/src/primitives/floating.entry.test.tsx

@@ -0,0 +1,14 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { FloatingPanel, Legend } from '../index';
+
+describe('floating public entry', () => {
+  it('reaches a consumer from the package entry point alone', () => {
+    const { container } = render(
+      <FloatingPanel>
+        <Legend entries={[{ key: 'a', label: 'a', color: '#fff' }]} />
+      </FloatingPanel>,
+    );
+    expect(container.querySelector('.lk-floating-panel .lk-legend')).toBeInTheDocument();
+  });
+});

package/src/primitives/index.ts

@@ -1,9 +1,17 @@
+export type { FloatingPanelProps } from './FloatingPanel';
+export { FloatingPanel } from './FloatingPanel';
 export { FpsMeter } from './FpsMeter';
+export type { JobProgressProps } from './JobProgress';
+export { JobProgress } from './JobProgress';
+export type { LegendEntry, LegendMark, LegendProps } from './Legend';
+export { Legend } from './Legend';
 export type { ScaleIndicatorProps } from './ScaleIndicator';
 export { ScaleIndicator } from './ScaleIndicator';
 export type { SidebarProps } from './Sidebar';
 export { Sidebar } from './Sidebar';
-export type { StatusBarProps } from './StatusBar';
+export type { StatusBarProps, StatusBarSectionProps } from './StatusBar';
 export { StatusBar } from './StatusBar';
-export type { ToolbarProps } from './Toolbar';
+export type { ToolbarButtonProps, ToolbarGroupProps, ToolbarProps } from './Toolbar';
 export { Toolbar } from './Toolbar';
+export type { ZoomControlProps } from './ZoomControl';
+export { ZoomControl } from './ZoomControl';

package/src/primitives/useRovingTabIndex.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { nextIndex } from './useRovingTabIndex';
+
+describe('nextIndex', () => {
+  it('steps forward and wraps', () => {
+    expect(nextIndex(0, 'ArrowRight', 3)).toBe(1);
+    expect(nextIndex(2, 'ArrowRight', 3)).toBe(0);
+  });
+
+  it('steps back and wraps', () => {
+    expect(nextIndex(1, 'ArrowLeft', 3)).toBe(0);
+    expect(nextIndex(0, 'ArrowLeft', 3)).toBe(2);
+  });
+
+  it('jumps to the ends', () => {
+    expect(nextIndex(1, 'Home', 3)).toBe(0);
+    expect(nextIndex(1, 'End', 3)).toBe(2);
+  });
+
+  it('returns null for a key it does not handle', () => {
+    expect(nextIndex(1, 'Enter', 3)).toBeNull();
+  });
+
+  it('returns null when there is nothing to move to', () => {
+    expect(nextIndex(0, 'ArrowRight', 0)).toBeNull();
+  });
+});

package/src/primitives/useRovingTabIndex.ts

@@ -0,0 +1,79 @@
+import { type KeyboardEvent, useCallback, useEffect, useRef } from 'react';
+
+/** Where a key takes focus within `count` items, or null if it does not move it. */
+export function nextIndex(current: number, key: string, count: number): number | null {
+  if (count === 0) return null;
+  switch (key) {
+    case 'ArrowRight':
+      return (current + 1) % count;
+    case 'ArrowLeft':
+      return (current - 1 + count) % count;
+    case 'Home':
+      return 0;
+    case 'End':
+      return count - 1;
+    default:
+      return null;
+  }
+}
+
+/**
+ * The APG roving-tabindex contract: exactly one item in the tab order, arrows
+ * moving focus within. `tabIndex` is written onto the DOM nodes rather than
+ * threaded through props, because the items are arbitrary children — the
+ * container never sees them as a list it could index.
+ */
+export function useRovingTabIndex<T extends HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const stop = useRef(0);
+
+  const items = useCallback(
+    (): HTMLElement[] =>
+      ref.current
+        ? Array.from(
+            ref.current.querySelectorAll<HTMLElement>('button:not([disabled]), [role="button"]'),
+          )
+        : [],
+    [],
+  );
+
+  const setTabStop = useCallback(
+    (index: number) => {
+      const found = items();
+      const at = Math.min(Math.max(index, 0), Math.max(found.length - 1, 0));
+      stop.current = at;
+      for (const [i, el] of found.entries()) el.tabIndex = i === at ? 0 : -1;
+    },
+    [items],
+  );
+
+  // Re-establish the tab stop whenever the item set changes — a trial's toolbar
+  // contributions are dynamic, and `disabled` moves a button in and out of the
+  // set without touching the child list. The focused item keeps the stop.
+  useEffect(() => {
+    const resync = () => {
+      const focused = items().indexOf(document.activeElement as HTMLElement);
+      setTabStop(focused === -1 ? stop.current : focused);
+    };
+    resync();
+    if (!ref.current) return;
+    const mo = new MutationObserver(resync);
+    mo.observe(ref.current, { childList: true, subtree: true, attributeFilter: ['disabled'] });
+    return () => mo.disconnect();
+  }, [items, setTabStop]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<T>) => {
+      const found = items();
+      const current = found.indexOf(document.activeElement as HTMLElement);
+      const next = nextIndex(current === -1 ? 0 : current, e.key, found.length);
+      if (next === null) return;
+      e.preventDefault();
+      found[next]?.focus();
+      setTabStop(next);
+    },
+    [items, setTabStop],
+  );
+
+  return { ref, onKeyDown };
+}

package/src/state/store.ts

@@ -28,7 +28,7 @@ export interface LabStoreActions {
   removeTrial: (id: string) => void;
   updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
   updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
-  updateTrialView: (id: string, view: TrialRecord['view']) => void;
+  updateTrialView: (id: string, view: unknown) => void;
   updateTrialUndoStack: (
     id: string,
     next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack']),
@@ -39,6 +39,8 @@ export interface LabStoreActions {
   deleteSnapshot: (snapshotId: string) => void;
   listSnapshots: (trialId?: string) => SavedSnapshot[];
   setMode: (mode: LabMode) => void;
+  setLabTool: (id: string | null) => void;
+  setTrialTool: (trialId: string, id: string | null) => void;
   setLayout: (layout: Record<string, unknown>) => void;
 }
 
@@ -70,6 +72,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
     layout: hydratedLayout,
+    activeToolId: null,
 
     addTrial: (record) => {
       set((s) => ({
@@ -89,6 +92,10 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           if (w.id !== id) return w;
           const nextState =
             typeof next === 'function' ? (next as (prev: unknown) => unknown)(w.state) : next;
+          // An updater that returns its input means "nothing changed", and must not
+          // cost a new record: the trial re-renders on record identity, so
+          // allocating here turns the standard React bail-out into a render loop.
+          if (Object.is(nextState, w.state)) return w;
           return { ...w, state: nextState };
         }),
       }));
@@ -110,7 +117,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
 
     updateTrialView: (id, view) => {
       set((s) => ({
-        trials: s.trials.map((w) => (w.id === id ? { ...w, view } : w)),
+        trials: s.trials.map((w) => (w.id === id && !Object.is(view, w.view) ? { ...w, view } : w)),
       }));
       scheduleFlush();
     },
@@ -197,6 +204,13 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
+    setLabTool: (id) => set({ activeToolId: id }),
+
+    setTrialTool: (trialId, id) =>
+      set((s) => ({
+        trials: s.trials.map((t) => (t.id === trialId ? { ...t, activeToolId: id } : t)),
+      })),
+
     setLayout: (layout) => {
       set({ layout });
       scheduleFlush();

package/src/state/toolSlot.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { createLabStore } from './store';
+
+function store() {
+  return createLabStore({ storageKey: 'test', storage: { read: () => null, write: () => {} } });
+}
+
+const record = { id: 't1', instrumentName: 'X', config: {}, state: {}, view: {} };
+
+describe('the tool slot', () => {
+  it('starts empty at both levels', () => {
+    const s = store();
+    expect(s.getState().activeToolId).toBeNull();
+  });
+
+  it('sets the lab slot', () => {
+    const s = store();
+    s.getState().setLabTool('brush');
+    expect(s.getState().activeToolId).toBe('brush');
+  });
+
+  it('sets a trial slot without touching the lab one', () => {
+    const s = store();
+    s.getState().addTrial(record);
+    s.getState().setLabTool('brush');
+    s.getState().setTrialTool('t1', 'eraser');
+    expect(s.getState().activeToolId).toBe('brush');
+    expect(s.getState().trials[0].activeToolId).toBe('eraser');
+  });
+
+  it('leaves a trial slot undefined until it is set', () => {
+    const s = store();
+    s.getState().addTrial(record);
+    expect(s.getState().trials[0].activeToolId).toBeUndefined();
+  });
+});

package/src/state/types.ts

@@ -7,12 +7,16 @@ export interface UndoStack {
 
 /** One trial as the store holds it: which instrument it runs, that
  *  instrument's config and state, the camera, and the undo history. */
-export interface TrialRecord<TS = unknown, TC = unknown> {
+export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
   id: string;
   instrumentName: string;
   config: TC;
   state: TS;
-  view: { zoom: number; pan: { x: number; y: number } };
+  /** Opaque to labkit: persisted, restored on Reset and handed to the instrument,
+   *  but never read into. A 3D lab puts an orbit here and keeps all three. */
+  view: TV;
+  /** This trial's own tool slot. Undefined means it reads the lab's. */
+  activeToolId?: string | null;
   undoStack: UndoStack;
 }
 
@@ -37,6 +41,8 @@ export interface LabStoreState {
   trials: TrialRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
+  /** The lab's tool slot — what a trial with no slot of its own resolves to. */
+  activeToolId: string | null;
   /** Per-trial tile extents, keyed by trial id. Opaque here — the
    *  shape belongs to whatever lays the trials out. */
   layout: Record<string, unknown>;

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

@@ -4,11 +4,17 @@
 @import './lab/LabShell.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Sidebar.less';
+@import './primitives/ZoomControl.less';
 @import './primitives/StatusBar.less';
+@import './primitives/JobProgress.less';
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
+@import './primitives/Legend.less';
+@import './primitives/FloatingPanel.less';
 @import './lab/Lab.less';
 @import './trial/Trial.less';
+@import './chrome/regions/ViewportRegion.less';
+@import './chrome/regions/PaletteRegion.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;
+}