@weasel-js/labkit 1.1.0 → 1.2.0

package/src/job/types.ts

@@ -0,0 +1,47 @@
+/** What a running job reports as it goes. `total` may arrive at any point and may
+ *  arrive more than once; a job that cannot count up front simply never sends it.
+ *
+ *  `failed` is a first-class event rather than a thrown error because these
+ *  failures are per item: a run with two failed items is a partial success, and
+ *  its other items are worth showing. */
+export type JobEvent<T> =
+  | { kind: 'total'; total: number }
+  | { kind: 'item'; item: T }
+  | { kind: 'failed'; index: number; error: string };
+
+/** Where a job is. `idle` before its first run and after a cancel; `done` when the
+ *  iterable finished, whether or not items failed along the way. */
+export type JobStatus = 'idle' | 'running' | 'done' | 'error';
+
+/** Declares that an instrument has work too slow to do during a render: what to
+ *  run, when to re-run it, and how each result folds into state. */
+export interface JobCapability<TS = unknown, TC = unknown, TItem = unknown> {
+  /** Re-run whenever this value changes, compared element-wise. A job with no
+   *  `key` runs only when something calls `start()`. */
+  key?: (config: TC, state: TS) => readonly unknown[];
+  /** Start on mount and on every `key` change. Default false. */
+  auto?: boolean;
+  run: (args: { config: TC; state: TS; signal: AbortSignal }) => AsyncIterable<JobEvent<TItem>>;
+  /** Fold one result into state. Called once per `item` event, in arrival order. */
+  onItem: (item: TItem, state: TS) => TS;
+}
+
+/** One item that failed, and why. */
+export interface JobFailure {
+  index: number;
+  error: string;
+}
+
+/** What `RenderContext.job` exposes. Present only when the instrument declares the
+ *  capability; `undefined` otherwise. */
+export interface JobHandle {
+  status: JobStatus;
+  done: number;
+  /** Null until the job reports a total, and forever if it never does. */
+  total: number | null;
+  failures: readonly JobFailure[];
+  /** The error that ended the run, when `status` is `'error'`. */
+  error: string | null;
+  start: () => void;
+  cancel: () => void;
+}

package/src/job/useJob.test.tsx

@@ -0,0 +1,210 @@
+import { act, render, waitFor } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import type { JobCapability, JobEvent, JobHandle } from './types';
+import { useJob } from './useJob';
+
+interface State {
+  items: number[];
+}
+interface Config {
+  n: number;
+}
+
+/** Yields 0..n-1, pausing between each so a test can cancel mid-run. */
+async function* counter(
+  n: number,
+  signal: AbortSignal,
+  failAt?: number,
+): AsyncGenerator<JobEvent<number>> {
+  yield { kind: 'total', total: n };
+  for (let i = 0; i < n; i++) {
+    await new Promise((r) => setTimeout(r, 2));
+    if (signal.aborted) return;
+    if (i === failAt) {
+      yield { kind: 'failed', index: i, error: 'frame died' };
+      continue;
+    }
+    yield { kind: 'item', item: i };
+  }
+}
+
+const capability = (failAt?: number): JobCapability<State, Config, number> => ({
+  run: ({ config, signal }) => counter(config.n, signal, failAt),
+  onItem: (item, state) => ({ items: [...state.items, item] }),
+});
+
+interface HarnessProps {
+  capability: JobCapability<State, Config, number>;
+  config: Config;
+  onHandle: (h: JobHandle, s: State) => void;
+}
+
+function Harness({ capability: cap, config, onHandle }: HarnessProps) {
+  const [state, setState] = useState<State>({ items: [] });
+  const job = useJob({ capability: cap, config, state, setState });
+  onHandle(job, state);
+  return null;
+}
+
+describe('useJob', () => {
+  it('folds each item into state and counts progress', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability()}
+        config={{ n: 3 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+    expect(seen.state.items).toEqual([0, 1, 2]);
+    expect(seen.handle?.done).toBe(3);
+    expect(seen.handle?.total).toBe(3);
+  });
+
+  it('counts a failed item without ending the run', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability(1)}
+        config={{ n: 3 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+    expect(seen.state.items).toEqual([0, 2]);
+    expect(seen.handle?.failures).toEqual([{ index: 1, error: 'frame died' }]);
+    expect(seen.handle?.done).toBe(2);
+  });
+
+  it('stops folding results once cancelled', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability()}
+        config={{ n: 50 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+    act(() => seen.handle?.cancel());
+    const atCancel = seen.state.items.length;
+    await new Promise((r) => setTimeout(r, 30));
+    expect(seen.state.items.length).toBe(atCancel);
+    expect(seen.handle?.status).toBe('idle');
+  });
+
+  it('discards results from a run its key superseded', async () => {
+    const withKey: JobCapability<State, Config, number> = {
+      ...capability(),
+      key: (config) => [config.n],
+      auto: true,
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    const { rerender } = render(
+      <Harness
+        capability={withKey}
+        config={{ n: 40 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+
+    rerender(
+      <Harness
+        capability={withKey}
+        config={{ n: 2 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+
+    // The superseded 40-item run cannot have contributed: the winner yields two.
+    expect(seen.state.items).toEqual([0, 1]);
+  });
+
+  it('aborts on unmount', async () => {
+    const aborted = vi.fn();
+    const watching: JobCapability<State, Config, number> = {
+      run: ({ signal }) => {
+        signal.addEventListener('abort', aborted);
+        return counter(50, signal);
+      },
+      onItem: (item, state) => ({ items: [...state.items, item] }),
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    const { unmount } = render(
+      <Harness
+        capability={watching}
+        config={{ n: 50 }}
+        onHandle={(h) => {
+          seen.handle = h;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+    unmount();
+    expect(aborted).toHaveBeenCalled();
+  });
+
+  it('reports a thrown error without losing the items already folded', async () => {
+    const throwing: JobCapability<State, Config, number> = {
+      run: async function* () {
+        yield { kind: 'item', item: 7 };
+        await new Promise((r) => setTimeout(r, 1));
+        throw new Error('the baker died');
+      },
+      onItem: (item, state) => ({ items: [...state.items, item] }),
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={throwing}
+        config={{ n: 1 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('error'));
+    expect(seen.handle?.error).toMatch(/the baker died/);
+    expect(seen.state.items).toEqual([7]);
+  });
+
+  it('does not start on its own without auto', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={{ ...capability(), key: (c) => [c.n] }}
+        config={{ n: 3 }}
+        onHandle={(h) => {
+          seen.handle = h;
+        }}
+      />,
+    );
+    await new Promise((r) => setTimeout(r, 20));
+    expect(seen.handle?.status).toBe('idle');
+  });
+});

package/src/job/useJob.ts

@@ -0,0 +1,134 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { JobCapability, JobFailure, JobHandle, JobStatus } from './types';
+
+export interface UseJobOptions<TS, TC, TItem> {
+  capability: JobCapability<TS, TC, TItem>;
+  config: TC;
+  state: TS;
+  setState: (next: TS | ((prev: TS) => TS)) => void;
+}
+
+interface Progress {
+  status: JobStatus;
+  done: number;
+  total: number | null;
+  failures: JobFailure[];
+  error: string | null;
+}
+
+const IDLE: Progress = { status: 'idle', done: 0, total: null, failures: [], error: null };
+
+function sameKey(a: readonly unknown[] | null, b: readonly unknown[] | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
+}
+
+export function useJob<TS, TC, TItem>({
+  capability,
+  config,
+  state,
+  setState,
+}: UseJobOptions<TS, TC, TItem>): JobHandle {
+  const [progress, setProgress] = useState<Progress>(IDLE);
+
+  // A run is identified by a token. Every result checks its token before touching
+  // state, so a superseded run finishes harmlessly instead of racing the winner.
+  const token = useRef(0);
+  const abort = useRef<AbortController | null>(null);
+
+  // Read through refs: `run` is called once per run and must see the values as of
+  // that moment rather than re-subscribing on every render.
+  const capRef = useRef(capability);
+  capRef.current = capability;
+  const configRef = useRef(config);
+  configRef.current = config;
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const setStateRef = useRef(setState);
+  setStateRef.current = setState;
+
+  const cancel = useCallback(() => {
+    token.current += 1;
+    abort.current?.abort();
+    abort.current = null;
+    setProgress(IDLE);
+  }, []);
+
+  const start = useCallback(() => {
+    token.current += 1;
+    const mine = token.current;
+    abort.current?.abort();
+    const controller = new AbortController();
+    abort.current = controller;
+    setProgress({ ...IDLE, status: 'running' });
+
+    void (async () => {
+      try {
+        const iterable = capRef.current.run({
+          config: configRef.current,
+          state: stateRef.current,
+          signal: controller.signal,
+        });
+        for await (const event of iterable) {
+          if (token.current !== mine) return;
+          if (event.kind === 'total') {
+            setProgress((p) => ({ ...p, total: event.total }));
+          } else if (event.kind === 'failed') {
+            setProgress((p) => ({
+              ...p,
+              failures: [...p.failures, { index: event.index, error: event.error }],
+            }));
+          } else {
+            const fold = capRef.current.onItem;
+            const item = event.item;
+            setStateRef.current((prev) => fold(item, prev));
+            setProgress((p) => ({ ...p, done: p.done + 1 }));
+          }
+        }
+        if (token.current !== mine) return;
+        setProgress((p) => ({ ...p, status: 'done' }));
+      } catch (err) {
+        if (token.current !== mine) return;
+        setProgress((p) => ({
+          ...p,
+          status: 'error',
+          error: err instanceof Error ? err.message : String(err),
+        }));
+      }
+    })();
+  }, []);
+
+  // Re-run when the declared key changes. `auto` covers the first mount too.
+  const lastKey = useRef<readonly unknown[] | null>(null);
+  const started = useRef(false);
+  const auto = capability.auto === true;
+  const key = capability.key ? capability.key(config, state) : null;
+  // `key` is compared element-wise inside; depending on the array identity here
+  // would restart the job on every render.
+  useEffect(() => {
+    if (!auto) return;
+    if (started.current && sameKey(lastKey.current, key)) return;
+    lastKey.current = key;
+    started.current = true;
+    start();
+  }, [auto, key, start]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(
+    () => () => {
+      token.current += 1;
+      abort.current?.abort();
+      abort.current = null;
+    },
+    [],
+  );
+
+  return {
+    status: progress.status,
+    done: progress.done,
+    total: progress.total,
+    failures: progress.failures,
+    error: progress.error,
+    start,
+    cancel,
+  };
+}

package/src/lab/Lab.stories.tsx

@@ -33,10 +33,9 @@ export const Default: Story = {
 
 function AddSecondTrial() {
   const ctx = useLabContext();
-  // biome-ignore lint/correctness/useExhaustiveDependencies: run once on mount
   useEffect(() => {
     if (ctx.trials.length < 2) ctx.addTrial('Stub');
-  }, []);
+  }, [ctx]);
   return null;
 }
 

package/src/lab/Workspace.surface.test.tsx

@@ -0,0 +1,49 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
+import { Workspace } from './Workspace';
+
+function fakeHandle(): SurfaceHandle {
+  return {
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    invalidateRects: vi.fn(),
+    registerTile: vi.fn(),
+    containerRef: vi.fn(),
+  };
+}
+
+describe('Workspace with a surface above it', () => {
+  it('invalidates rects when the tile set changes, because a re-tile moves tiles', () => {
+    const handle = fakeHandle();
+    const { rerender } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+    (handle.invalidateRects as ReturnType<typeof vi.fn>).mockClear();
+
+    rerender(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a', 'b']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+          <div>b</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+
+    expect(handle.invalidateRects).toHaveBeenCalled();
+  });
+
+  it('renders unchanged with no surface above it', () => {
+    const { getByText } = render(
+      <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+        <div>a</div>
+      </Workspace>,
+    );
+    expect(getByText('a')).toBeInTheDocument();
+  });
+});

package/src/lab/Workspace.tsx

@@ -17,6 +17,8 @@ import {
   StrategyRegistryProvider,
 } from 'windease/react';
 
+import { useSurfaceOptional } from '../surface/useSurfaceTile';
+
 const ZONE_ID = asNodeId('lk-workspace');
 const STRATEGIES = { grid: gridStrategy as never };
 const KIND = 'trial';
@@ -93,7 +95,7 @@ export function Workspace({
   const items = Children.toArray(children);
   const idKey = ids ? ids.join(',') : `#${items.length}`;
   // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
-  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]);
+  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Held in refs rather than depended on: a fresh object each render would
   // re-run the sync effect, and only a newly registered tile reads `layout`.
@@ -119,6 +121,10 @@ export function Workspace({
   }
   const store = storeRef.current;
 
+  // A tile that only moves reports nothing to a ResizeObserver, and only this
+  // component knows the grid moved one. Optional: a lab may own no surface.
+  const surface = useSurfaceOptional();
+
   useLayoutEffect(() => {
     store.updateContainerConfig(ZONE_ID, { resizable, gap, padding });
   }, [store, resizable, gap, padding]);
@@ -139,6 +145,13 @@ export function Workspace({
     store.setChildOrder(ZONE_ID, [...nodeIds]);
   }, [store, nodeIds]);
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: nodeIds is the signal that the tile set changed — a re-tile moves tiles without resizing any — not a value this reads
+  useEffect(() => {
+    if (!surface) return;
+    surface.invalidateRects();
+    return store.events.on('node.placementChanged', () => surface.invalidateRects());
+  }, [store, surface, nodeIds]); // eslint-disable-line react-hooks/exhaustive-deps
+
   useEffect(() => {
     if (!onLayoutChange) return;
     return store.events.on('node.placementChanged', () => {

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']),
@@ -89,6 +89,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 +114,9 @@ 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();
     },

package/src/state/types.ts

@@ -7,12 +7,14 @@ 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;
   undoStack: UndoStack;
 }
 

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 } };
+}