@weasel-js/labkit 1.4.4 → 1.5.1

package/src/state/usePersistedState.test.tsx

@@ -0,0 +1,125 @@
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { createMemoryAdapter } from './adapters';
+import { labPrefix } from './labRecords';
+import { Persistence } from './Persistence';
+import { SingletonExperimentProvider } from './SingletonExperiment';
+import { type PersistedStateOptions, usePersistedState } from './usePersistedState';
+
+function Tab({
+  name = 'tab',
+  label = 'tab',
+  options,
+}: {
+  name?: string | null;
+  label?: string;
+  options?: PersistedStateOptions;
+}) {
+  const [value, setValue] = usePersistedState(name, 'shape', options);
+  return (
+    <>
+      <output aria-label={label}>{value}</output>
+      <button type="button" onClick={() => setValue('color')}>
+        {`set ${label}`}
+      </button>
+      <button type="button" onClick={() => setValue((prev) => `${prev}+`)}>
+        {`append ${label}`}
+      </button>
+    </>
+  );
+}
+
+const P = labPrefix('k');
+const shown = (label = 'tab') => screen.getByLabelText(label).textContent;
+
+function persisted(backing: Map<string, unknown>, children: React.ReactNode) {
+  return (
+    <Persistence storageKey="k" storage={createMemoryAdapter(backing)} fallback={<p>loading</p>}>
+      {children}
+    </Persistence>
+  );
+}
+
+describe('usePersistedState', () => {
+  it('is plain useState with no provider above it', () => {
+    render(<Tab />);
+    act(() => screen.getByText('set tab').click());
+    expect(shown()).toBe('color');
+  });
+
+  it('is plain useState, writing nothing, for a null name', async () => {
+    const backing = new Map<string, unknown>();
+    const view = render(persisted(backing, <Tab name={null} />));
+    await screen.findByLabelText('tab');
+    act(() => screen.getByText('set tab').click());
+    expect(shown()).toBe('color');
+    view.unmount();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(backing.size).toBe(0);
+  });
+
+  it('keeps its value across a remount, lab-scoped outside a trial', async () => {
+    const backing = new Map<string, unknown>();
+    const first = render(persisted(backing, <Tab />));
+    expect(screen.getByText('loading')).toBeInTheDocument();
+    await screen.findByLabelText('tab');
+    expect(shown()).toBe('shape');
+    act(() => screen.getByText('set tab').click());
+    act(() => screen.getByText('append tab').click());
+    expect(shown()).toBe('color+');
+    first.unmount();
+    await waitFor(() => expect(backing.get(`${P}value:lab:tab`)).toBe('color+'));
+
+    render(persisted(backing, <Tab />));
+    await screen.findByLabelText('tab');
+    expect(shown()).toBe('color+');
+  });
+
+  it('scopes to the trial it is in, unless asked for the lab', async () => {
+    const backing = new Map<string, unknown>();
+    render(
+      <SingletonExperimentProvider
+        id="t:1"
+        initialConfig={{}}
+        initialState={{}}
+        storageKey="k"
+        storage={createMemoryAdapter(backing)}
+      >
+        <Tab label="own" />
+        <Tab label="shared" name="shared" options={{ scope: 'lab' }} />
+      </SingletonExperimentProvider>,
+    );
+    await screen.findByLabelText('own');
+    act(() => screen.getByText('set own').click());
+    act(() => screen.getByText('set shared').click());
+    await waitFor(() => expect(backing.get(`${P}value:trial:t%3A1:tab`)).toBe('color'));
+    await waitFor(() => expect(backing.get(`${P}value:lab:shared`)).toBe('color'));
+  });
+
+  it('keeps two components with one name in step', async () => {
+    const backing = new Map<string, unknown>();
+    render(
+      persisted(
+        backing,
+        <>
+          <Tab label="a" />
+          <Tab label="b" />
+        </>,
+      ),
+    );
+    await screen.findByLabelText('a');
+    act(() => screen.getByText('set a').click());
+    expect(shown('b')).toBe('color');
+  });
+
+  it("re-renders with another tab's write", async () => {
+    const backing = new Map<string, unknown>();
+    render(persisted(backing, <Tab />));
+    await screen.findByLabelText('tab');
+    await act(async () => {
+      await createMemoryAdapter(backing).set(`${P}value:lab:tab`, 'from elsewhere');
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    expect(shown()).toBe('from elsewhere');
+  });
+});

package/src/state/usePersistedState.ts

@@ -0,0 +1,66 @@
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useContext,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { TrialIdContext } from './context';
+import { valueRecord } from './labRecords';
+import { PersistenceContext } from './Persistence';
+
+/** Options for `usePersistedState`. */
+export interface PersistedStateOptions {
+  /** `'trial'` — the default inside a trial — keeps a value per trial, and
+   *  closing the trial deletes it. `'lab'` shares one value across the lab. */
+  scope?: 'trial' | 'lab';
+}
+
+/**
+ * `useState` whose value survives a reload: a widget's open tab, a panel's
+ * position. Inside a `<Lab>`, `SingletonExperimentProvider` or `<Persistence>`
+ * the value is a record, loaded before first render and re-rendered when
+ * another tab changes it. With no provider above it, or a null `name`, it is
+ * plain `useState` — so a component can offer optional persistence and still
+ * mount anywhere.
+ *
+ * Values must be structured-clone values; the JSON-backed adapters warn about
+ * one JSON would change. Snapshots do not include them.
+ */
+export function usePersistedState<T>(
+  name: string | null | undefined,
+  initial: T | (() => T),
+  options: PersistedStateOptions = {},
+): [T, Dispatch<SetStateAction<T>>] {
+  const records = useContext(PersistenceContext);
+  const trialId = useContext(TrialIdContext);
+  const [local, setLocal] = useState(initial);
+
+  const record =
+    records && name != null ? valueRecord(options.scope === 'lab' ? null : trialId, name) : null;
+
+  const subscribe = useCallback(
+    (notify: () => void) =>
+      records && record
+        ? records.subscribe((changes) => {
+            if (changes.some((c) => c.name === record)) notify();
+          })
+        : () => {},
+    [records, record],
+  );
+  const read = (): T =>
+    records && record && records.has(record) ? (records.get(record) as T) : local;
+  const persisted = useSyncExternalStore(subscribe, read, read);
+
+  const setPersisted = useCallback<Dispatch<SetStateAction<T>>>(
+    (next) => {
+      if (!records || !record) return;
+      const prev = records.has(record) ? (records.get(record) as T) : local;
+      records.set(record, typeof next === 'function' ? (next as (p: T) => T)(prev) : next);
+    },
+    [records, record, local],
+  );
+
+  return records && record ? [persisted, setPersisted] : [local, setLocal];
+}

package/src/state/useTrialState.test.tsx

@@ -1,7 +1,10 @@
 import { act, renderHook } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { describe, expect, it } from 'vitest';
-import { createMemoryAdapter } from './adapters';
+import { auto } from '../config/auto';
+import { f } from '../config/builder';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { Instrument } from '../instrument/types';
 import { LabStoreProvider, TrialIdProvider } from './context';
 import { createLabStore } from './store';
 import { useTrialState } from './useTrialState';
@@ -10,7 +13,7 @@ type TestState = { count: number };
 type TestConfig = { step: number };
 
 function makeWrapper(trialId: string) {
-  const store = createLabStore({ storageKey: 'test', storage: createMemoryAdapter() });
+  const store = createLabStore();
   store.getState().addTrial({
     id: trialId,
     instrumentName: 'Counter',
@@ -59,7 +62,7 @@ describe('useTrialState', () => {
   });
 
   it('sibling trial does not re-render on unrelated trial changes', () => {
-    const store = createLabStore({ storageKey: 'test', storage: createMemoryAdapter() });
+    const store = createLabStore();
     store.getState().addTrial({
       id: 'w1',
       instrumentName: 'T',
@@ -100,3 +103,84 @@ describe('useTrialState', () => {
     expect(() => renderHook(() => useTrialState())).toThrow('[labkit]');
   });
 });
+
+const autoInstrument = defineInstrument({
+  name: 'Auto',
+  config: f.schema({
+    width: f.number(432),
+    gap: f.number(12).auto((c) => (c.width as number) / 24),
+  }),
+  initialState: () => ({ count: 0 }),
+  render: () => null,
+});
+
+function makeAutoWrapper(trialId: string) {
+  const store = createLabStore({ instruments: [autoInstrument as Instrument] });
+  store.getState().addTrial({
+    id: trialId,
+    instrumentName: 'Auto',
+    config: autoInstrument.defaultConfig(),
+    state: { count: 0 },
+    view: { zoom: 1, pan: { x: 0, y: 0 } },
+  });
+  return {
+    store,
+    wrapper: ({ children }: { children: ReactNode }) => (
+      <LabStoreProvider store={store}>
+        <TrialIdProvider trialId={trialId}>{children}</TrialIdProvider>
+      </LabStoreProvider>
+    ),
+  };
+}
+
+describe('auto paths', () => {
+  it('hands the instrument the resolved config and the raw one separately', () => {
+    const { store, wrapper } = makeAutoWrapper('w1');
+    const { result } = renderHook(
+      () => useTrialState<{ count: number }, { width: number; gap: number }>(),
+      { wrapper },
+    );
+    act(() => store.getState().updateTrialConfig('w1', 'gap', auto));
+    expect(result.current.config.gap).toBe(18);
+    expect(result.current.raw.gap).toBe(12);
+    expect([...result.current.auto]).toEqual(['gap']);
+  });
+
+  it('leaves a pinned config untouched', () => {
+    const { wrapper } = makeAutoWrapper('w1');
+    const { result } = renderHook(
+      () => useTrialState<{ count: number }, { width: number; gap: number }>(),
+      { wrapper },
+    );
+    expect(result.current.config.gap).toBe(12);
+    expect(result.current.config).toBe(result.current.raw);
+    expect([...result.current.auto]).toEqual([]);
+  });
+
+  it('records a path written as auto instead of storing the sentinel', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', 24);
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    const rec = store.getState().trials[0];
+    expect(rec?.auto).toEqual(['gap']);
+    // The last pinned value survives, so un-pinning is lossless.
+    expect(rec?.config).toEqual({ width: 432, gap: 24 });
+  });
+
+  it('pins again when a real value is written to an auto path', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    store.getState().updateTrialConfig('w1', 'gap', 30);
+    const rec = store.getState().trials[0];
+    expect(rec?.auto).toBeUndefined();
+    expect((rec?.config as { gap: number }).gap).toBe(30);
+  });
+
+  it('does not allocate a new record when the path is already auto', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    const first = store.getState().trials[0];
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    expect(store.getState().trials[0]).toBe(first);
+  });
+});

package/src/state/useTrialState.ts

@@ -1,5 +1,6 @@
 import { useContext } from 'react';
 import { useStore } from 'zustand/react';
+import { useResolvedConfig } from '../config/useResolvedConfig';
 import { LabStoreContext, TrialIdContext } from './context';
 import type { TrialStateHandle } from './types';
 
@@ -19,10 +20,17 @@ export function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS
 
   const updateTrialState = useStore(ctx.store, (s) => s.updateTrialState);
   const updateTrialConfig = useStore(ctx.store, (s) => s.updateTrialConfig);
+  // The store's own copy, not `useConfigSchema`: that reads `LabContext`, and
+  // this hook only has the store's.
+  const instrumentHooks = useStore(ctx.store, (s) => s.instrumentHooks);
+  const schema = instrumentHooks().configSchemas[record.instrumentName];
+  const { config, auto } = useResolvedConfig<TC>(schema, record.config as TC, record.auto);
 
   return {
     state: record.state as TS,
-    config: record.config as TC,
+    config,
+    raw: record.config as TC,
+    auto,
     setState: (next) => updateTrialState(trialId, next as Parameters<typeof updateTrialState>[1]),
     setConfig: (path, value) => updateTrialConfig(trialId, path, value),
   };

package/src/state/view.test.ts

@@ -1,7 +1,9 @@
-import { describe, expect, it, vi } from 'vitest';
+import { ZOOM_FLOOR } from '@weasel-js/core';
+import { describe, expect, it } from 'vitest';
 import { createMemoryAdapter } from './adapters';
+import { openLabStore } from './openLabStore';
 import { createLabStore } from './store';
-import { as2DView, DEFAULT_VIEW } from './view';
+import { as2DView, DEFAULT_VIEW, normalize2DView, withZoom } from './view';
 
 interface OrbitView {
   yaw: number;
@@ -41,7 +43,7 @@ describe('as2DView', () => {
 
 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() });
+    const store = createLabStore();
     store.getState().addTrial({
       id: 'w1',
       instrumentName: 'gem',
@@ -55,28 +57,32 @@ describe('a trial view labkit does not interpret', () => {
     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({
+  it('round-trips that view through persistence', async () => {
+    const backing = new Map<string, unknown>();
+    const seed = await openLabStore({
+      storageKey: 'view-b',
+      storage: createMemoryAdapter(backing),
+    });
+    seed.store.getState().addTrial({
       id: 'w1',
       instrumentName: 'gem',
       config: {},
       state: {},
       view: orbit,
     });
-    vi.advanceTimersByTime(500);
-    vi.useRealTimers();
+    await seed.close();
 
-    const hydrated = createLabStore({ storageKey: 'view-b', storage: mem });
-    expect(hydrated.getState().trials[0]?.view as OrbitView).toEqual(orbit);
+    const hydrated = await openLabStore({
+      storageKey: 'view-b',
+      storage: createMemoryAdapter(backing),
+    });
+    expect(hydrated.store.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() });
+    const store = createLabStore();
     store.getState().addTrial({
       id: 'w1',
       instrumentName: 'gem',
@@ -94,7 +100,7 @@ describe('an unchanged write costs no new record', () => {
   });
 
   it('still replaces the record when the state actually changes', () => {
-    const store = createLabStore({ storageKey: 'identity-b', storage: createMemoryAdapter() });
+    const store = createLabStore();
     store.getState().addTrial({
       id: 'w1',
       instrumentName: 'gem',
@@ -110,7 +116,7 @@ describe('an unchanged write costs no new record', () => {
   });
 
   it('returns the same trial object when the view is written unchanged', () => {
-    const store = createLabStore({ storageKey: 'identity-c', storage: createMemoryAdapter() });
+    const store = createLabStore();
     store.getState().addTrial({
       id: 'w1',
       instrumentName: 'gem',
@@ -125,3 +131,31 @@ describe('an unchanged write costs no new record', () => {
     expect(store.getState().trials[0]).toBe(before);
   });
 });
+
+describe('2D view zoom invariant', () => {
+  it('reads a stored zoom of 0 back as the floor', () => {
+    expect(as2DView({ zoom: 0, pan: { x: 1, y: 2 } })).toEqual({
+      zoom: ZOOM_FLOOR,
+      pan: { x: 1, y: 2 },
+    });
+  });
+
+  it('normalizes a NaN zoom and a non-finite pan', () => {
+    expect(normalize2DView({ zoom: Number.NaN, pan: { x: Infinity, y: 3 } })).toEqual({
+      zoom: ZOOM_FLOOR,
+      pan: { x: 0, y: 3 },
+    });
+  });
+
+  it('returns a valid view unchanged', () => {
+    const v = { zoom: 2, pan: { x: 1, y: 1 } };
+    expect(normalize2DView(v)).toBe(v);
+  });
+
+  it('writes a new zoom through the same rule', () => {
+    expect(withZoom({ zoom: 2, pan: { x: 4, y: 5 } }, 0)).toEqual({
+      zoom: ZOOM_FLOOR,
+      pan: { x: 4, y: 5 },
+    });
+  });
+});

package/src/state/view.ts

@@ -1,3 +1,4 @@
+import { normalizeZoom } from '@weasel-js/core';
 import type { ViewTransform } from '../instrument/types';
 
 /** The 2D view labkit has always shipped, and what a trial gets when it names no
@@ -14,5 +15,21 @@ export function as2DView(view: unknown): ViewTransform2D | null {
   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 } };
+  return normalize2DView({ zoom: v.zoom, pan: { x: v.pan.x, y: v.pan.y } });
+}
+
+/** `view` inside the invariant every view holds: a zoom that is not a finite
+ *  number of at least `ZOOM_FLOOR` becomes the floor, and a non-finite pan
+ *  becomes 0. Returns `view` itself when it already holds. */
+export function normalize2DView(view: ViewTransform2D): ViewTransform2D {
+  const zoom = normalizeZoom(view.zoom);
+  const x = Number.isFinite(view.pan.x) ? view.pan.x : 0;
+  const y = Number.isFinite(view.pan.y) ? view.pan.y : 0;
+  if (zoom === view.zoom && x === view.pan.x && y === view.pan.y) return view;
+  return { zoom, pan: { x, y } };
+}
+
+/** `view` at a new zoom, through the same rule. */
+export function withZoom(view: ViewTransform2D, zoom: number): ViewTransform2D {
+  return normalize2DView({ zoom, pan: view.pan });
 }

package/src/styles.less

@@ -5,6 +5,7 @@
 @import './lab/LabSwitcher.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Sidebar.less';
+@import './primitives/Split.less';
 @import './primitives/ZoomControl.less';
 @import './primitives/StatusBar.less';
 @import './primitives/JobProgress.less';
@@ -18,8 +19,10 @@
 @import './chrome/regions/PaletteRegion.less';
 @import './controls/ControlPanel.less';
 @import './canvas/CanvasStack.less';
+@import './canvas/Stage.less';
 @import './loupe/Loupe.less';
 @import './layers/LayerList.less';
 @import './annotations/Annotations.less';
 @import './dragdrop/Palette.less';
 @import './dragdrop/DragGhost.less';
+@import './specimen/Specimen.less';

package/src/surface/AGENTS.md

@@ -15,7 +15,7 @@ than a few 3D tiles have to share one surface.
 | `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 |
+| `useTiledSurface.ts` | ResizeObserver, dirty set, rAF coalescing, DPR, re-tile clears |
 | `SurfaceContext.ts` | Carries the handle down |
 | `useSurfaceTile.ts` | `useSurfaceTile(id)`, `useTileId(id)`, `useSurface()`, `useSurfaceOptional()` |
 
@@ -38,7 +38,9 @@ const surface = useTiledSurface({
 
 `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.
+under it. It runs before this frame's painters, and what it invalidates paints
+in the same frame: a buffer the owner just resized is blank, and every tile owes
+a repaint.
 
 ## A tile id is scoped to its trial
 
@@ -61,14 +63,44 @@ one contributes a single rect, and a trial with nothing to draw contributes none
 - **`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.
+- **Gutters lie outside every scissor**, so a tile that moves leaves its old
+  picture where nothing will paint over it — a cloned trial strands the whole
+  previous layout in the gap. Register a `registerClear(id, fn)` beside the
+  painter: every registered clear runs, before any painter, on a frame where
+  `frame.retiled` is true. A tenant must not clear from its own painter, because
+  tenants paint in sequence and the second would wipe the first.
+- **The owner cannot clear for you.** labkit owns the canvas, never the context,
+  and `canvas.width = <its own value>` resizes nothing, so it clears nothing —
+  the DOM trick that resets a 2D canvas is a no-op here. Only the context that
+  drew the pixels can erase them, which is why the clear is a tenant's to
+  register.
+- **There are two buffers, and the default is the wrong one for an opaque
+  tenant.** `useSurfaceCanvas()` gives you the buffer *over* the trial DOM,
+  which is what a mark annotating an instrument wants and what every tenant
+  predating the split asked for. A renderer that fills its tile buries anything
+  the pane draws, so it wants `useSurfaceCanvas('under')` and a transparent
+  pane. Both buffers share one set of tile rects — rects are measured against
+  the surface container either way — so nothing else about a tenant changes.
+- **A tile that moves without resizing** is handled twice over, and it needs
+  both. `Workspace` invalidates rects off the grid's own `node.placementChanged`,
+  which catches the move being *ordered*; the surface then keeps measuring until
+  two measurements agree, which catches where it *lands*. Without the second, a
+  panel whose size settles while its position is still animating leaves
+  `ResizeObserver` with nothing to report, and the tile paints for the rest of
+  its life at the spot it was caught mid-flight. A host that moves something the
+  grid does not know about still 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.
+
+Which layer a tenant landed on is not testable here at all — jsdom resolves no
+`z-index`, so `Lab.surface.test.tsx` asserts source order and says in the test
+that it is a proxy. A browser settles it, and the probe has to be a **child of
+the tile's own element**: one appended to `<body>` is outside the stacking
+context the buffers sit in, so it paints over everything and reports success
+whichever buffer the tenant chose. Measured against the 3D lab with a magenta
+div inside `.td-pane` — on `'under'` the div survives, on `'over'` it reads back
+as the viewport's own background.

package/src/surface/SurfaceContext.ts

@@ -4,6 +4,29 @@ 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);
 
-/** The buffer the surface's tiles paint into. Null until the owner's canvas is
- *  mounted, and for an owner that keeps its surface unpainted. */
-export const SurfaceCanvasContext = createContext<HTMLCanvasElement | null>(null);
+/**
+ * Which of the two stacked buffers a tenant paints into.
+ *
+ * `'over'` sits above the trial DOM: right for marks that annotate an
+ * instrument, which is what the surface was built for and so the default.
+ * `'under'` sits below it, which is what an opaque renderer needs — a tile that
+ * fills its pane hides anything the pane's own DOM draws, so a 3D viewport on
+ * the over-buffer has to paint its own chrome into the backend rather than
+ * putting a label or a button in the pane.
+ *
+ * Both exist for the lifetime of the surface and share one set of tile rects,
+ * so a lab can hold an annotated 2D trial and an opaque 3D one at once.
+ */
+export type SurfaceLayer = 'over' | 'under';
+
+/** The two buffers a surface owner publishes. A member is null until the
+ *  owner's canvas mounts, and for an owner that keeps its surface unpainted. */
+export interface SurfaceCanvases {
+  over: HTMLCanvasElement | null;
+  under: HTMLCanvasElement | null;
+}
+
+const NO_CANVASES: SurfaceCanvases = { over: null, under: null };
+
+/** The buffers the surface's tiles paint into. */
+export const SurfaceCanvasContext = createContext<SurfaceCanvases>(NO_CANVASES);

package/src/surface/index.ts

@@ -1,6 +1,7 @@
 export { composeRects, rectsEqual } from './composeRects';
 export { toDeviceRect } from './deviceRect';
 export type { Box, Rect } from './rect';
+export type { SurfaceCanvases, SurfaceLayer } from './SurfaceContext';
 export { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
 export {
   useSurface,
@@ -10,6 +11,7 @@ export {
   useTileId,
 } from './useSurfaceTile';
 export type {
+  SurfaceClear,
   SurfaceFrame,
   SurfaceHandle,
   TilePainter,

package/src/surface/useSurfaceTile.test.tsx

@@ -10,6 +10,7 @@ function fakeHandle(): SurfaceHandle {
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
+    registerClear: vi.fn(() => () => {}),
     registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),

package/src/surface/useSurfaceTile.ts

@@ -1,12 +1,13 @@
 import { useCallback, useContext } from 'react';
 import { TrialIdContext } from '../state/context';
-import { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
+import { SurfaceCanvasContext, SurfaceContext, type SurfaceLayer } from './SurfaceContext';
 import type { SurfaceHandle } from './useTiledSurface';
 
-/** The surface's shared buffer, or null where nothing paints one. What a tile
- *  hands to `paintInto`. */
-export function useSurfaceCanvas(): HTMLCanvasElement | null {
-  return useContext(SurfaceCanvasContext);
+/** One of the surface's two shared buffers, or null where nothing paints one.
+ *  What a tile hands to `paintInto`. See {@link SurfaceLayer} for which to ask
+ *  for; the default is the one over the trial DOM. */
+export function useSurfaceCanvas(layer: SurfaceLayer = 'over'): HTMLCanvasElement | null {
+  return useContext(SurfaceCanvasContext)[layer];
 }
 
 /** The surface above, or null. Use this where a surface is genuinely optional. */