@weasel-js/labkit 1.8.0 → 1.8.1

package/src/surface/useTiledSurface.test.tsx

@@ -109,6 +109,40 @@ describe('useTiledSurface', () => {
     expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
   });
 
+  it('narrows to the tiles inside a scope, retiling, and widens back', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    const h = (): SurfaceHandle | null => handle;
+    const { getByTestId } = render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    const heard = vi.fn();
+    act(() => {
+      h()?.subscribeScope(heard);
+    });
+    frames.length = 0;
+
+    act(() => h()?.scope(getByTestId('a')));
+    flushFrames();
+    expect(heard).toHaveBeenCalledTimes(1);
+    expect(h()?.inScope('a')).toBe(true);
+    expect(h()?.inScope('b')).toBe(false);
+    expect([...(frames[0]?.rects.keys() ?? [])]).toEqual(['a']);
+    expect(frames[0]?.retiled).toBe(true);
+
+    frames.length = 0;
+    act(() => h()?.scope(null));
+    flushFrames();
+    expect(h()?.inScope('b')).toBe(true);
+    expect([...(frames[0]?.rects.keys() ?? [])].sort()).toEqual(['a', 'b']);
+  });
+
   it('fires nothing on a clean tick', () => {
     const frames: SurfaceFrame[] = [];
     render(<Harness frames={frames} onHandle={() => {}} />);
@@ -207,6 +241,37 @@ describe('useTiledSurface', () => {
     expect(frames[0]?.rects.get('b')).toEqual({ x: 320, y: 0, w: 400, h: 600 });
   });
 
+  it('marks only the tiles a viewport box overlaps, measured from the container', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    const { getByTestId } = render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    // The page scrolled: the container now sits at (100, 50). x 450 is 350 into it, inside a.
+    stubBox(getByTestId('stage'), 100, 50, 800, 600);
+    act(() => handle?.invalidateBox({ left: 450, top: 100, width: 40, height: 40 }));
+    flushFrames();
+    expect([...(frames[0]?.dirty ?? [])]).toEqual(['a']);
+
+    frames.length = 0;
+    act(() => handle?.invalidateBox({ left: 480, top: 100, width: 40, height: 40 }));
+    flushFrames();
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+
+    frames.length = 0;
+    act(() => handle?.invalidateBox({ left: 0, top: 0, width: 40, height: 40 }));
+    flushFrames();
+    expect(frames).toHaveLength(0);
+  });
+
   it('drops a tile that unregisters', () => {
     const frames: SurfaceFrame[] = [];
     let handle: SurfaceHandle | null = null;

package/src/surface/useTiledSurface.ts

@@ -27,6 +27,9 @@ export interface SurfaceHandle {
   invalidate: (id: string) => void;
   /** Mark every tile — what a resize or a tile-set change means. */
   invalidateAll: () => void;
+  /** Mark every tile overlapping `box`, in viewport px as `getBoundingClientRect`
+   *  gives them: what something drawn over the tiles leaves behind when it moves. */
+  invalidateBox: (box: Box) => void;
   /** Re-measure before the next frame. The escape hatch for a host that knows it
    *  moved something a ResizeObserver cannot see. */
   invalidateRects: () => void;
@@ -45,6 +48,15 @@ export interface SurfaceHandle {
   /** The element tile rects are measured against, and so the one a tile's own
    *  chrome positions itself inside. Null before the owner attaches it. */
   getContainer: () => HTMLElement | null;
+  /** Narrow the surface to the tiles inside `el`, or widen it back with
+   *  `null`. A tile outside drops out of the frame's `rects` and is not
+   *  painted, and the frame is retiled so the buffer is cleared of it — what
+   *  an expanded tile needs, with the buffers lifted over the rest. */
+  scope: (el: HTMLElement | null) => void;
+  /** Whether the tile is inside the current scope. Everything is, unscoped. */
+  inScope: (id: string) => boolean;
+  /** Called whenever the scope changes. Returns the unsubscribe. */
+  subscribeScope: (listener: () => void) => () => void;
 }
 
 /** What a tile's painter is handed: where it sits on the surface now, and the
@@ -78,6 +90,8 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
   const needsMeasure = useRef(true);
   const observer = useRef<ResizeObserver | null>(null);
   const lastDpr = useRef(0);
+  const scopeEl = useRef<HTMLElement | null>(null);
+  const scopeListeners = useRef(new Set<() => void>());
 
   // Held in a ref so a caller passing an inline closure does not re-create every
   // callback below on each render.
@@ -87,7 +101,10 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     const el = container.current;
     if (!el) return false;
     const boxes = new Map<string, Box>();
-    for (const [id, tile] of tiles.current) boxes.set(id, tile.getBoundingClientRect());
+    for (const [id, tile] of tiles.current) {
+      if (scopeEl.current && !scopeEl.current.contains(tile)) continue;
+      boxes.set(id, tile.getBoundingClientRect());
+    }
     const next = composeRects(el.getBoundingClientRect(), boxes);
     let changed = next.size !== rects.current.size;
     for (const [id, rect] of next) {
@@ -176,6 +193,25 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     schedule();
   }, [schedule]);
 
+  const invalidateBox = useCallback(
+    (box: Box) => {
+      const el = container.current;
+      if (!el) return;
+      const at = el.getBoundingClientRect();
+      const x = box.left - at.left;
+      const y = box.top - at.top;
+      let hit = false;
+      for (const [id, r] of rects.current) {
+        if (x < r.x + r.w && r.x < x + box.width && y < r.y + r.h && r.y < y + box.height) {
+          dirty.current.add(id);
+          hit = true;
+        }
+      }
+      if (hit) schedule();
+    },
+    [schedule],
+  );
+
   const invalidateRects = useCallback(() => {
     needsMeasure.current = true;
     schedule();
@@ -216,6 +252,29 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
 
   const getContainer = useCallback(() => container.current, []);
 
+  const scope = useCallback(
+    (el: HTMLElement | null) => {
+      if (scopeEl.current === el) return;
+      scopeEl.current = el;
+      needsMeasure.current = true;
+      schedule();
+      for (const listener of scopeListeners.current) listener();
+    },
+    [schedule],
+  );
+
+  const inScope = useCallback((id: string) => {
+    const tile = tiles.current.get(id);
+    return !scopeEl.current || (tile !== undefined && scopeEl.current.contains(tile));
+  }, []);
+
+  const subscribeScope = useCallback((listener: () => void) => {
+    scopeListeners.current.add(listener);
+    return () => {
+      scopeListeners.current.delete(listener);
+    };
+  }, []);
+
   const containerRef = useCallback(
     (el: HTMLElement | null) => {
       if (container.current === el) return;
@@ -247,22 +306,30 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     () => ({
       invalidate,
       invalidateAll,
+      invalidateBox,
       invalidateRects,
       registerTile,
       registerClear,
       registerPainter,
       containerRef,
       getContainer,
+      scope,
+      inScope,
+      subscribeScope,
     }),
     [
       invalidate,
       invalidateAll,
+      invalidateBox,
       invalidateRects,
       registerTile,
       registerClear,
       registerPainter,
       containerRef,
       getContainer,
+      scope,
+      inScope,
+      subscribeScope,
     ],
   );
 }

package/src/trial/Trial.stories.tsx

@@ -23,7 +23,6 @@ const record: TrialRecord = {
   config: {},
   state: {},
   view: { zoom: 1, pan: { x: 0, y: 0 } },
-  undoStack: { past: [], future: [] },
 };
 
 function Harness() {

package/src/trial/Trial.test.tsx

@@ -27,7 +27,6 @@ const stubRecord: TrialRecord = {
   config: {},
   state: {},
   view: { zoom: 1, pan: { x: 0, y: 0 } },
-  undoStack: { past: [], future: [] },
 };
 
 type ChromeProps = Parameters<typeof TrialChrome>[0];
@@ -37,8 +36,7 @@ type ChromeProps = Parameters<typeof TrialChrome>[0];
  *  keeps its own store and hands it to both. */
 function makeChromeStore() {
   const store = createLabStore();
-  const { undoStack: _undo, ...seed } = stubRecord;
-  store.getState().addTrial(seed);
+  store.getState().addTrial(stubRecord);
   return store;
 }
 
@@ -357,3 +355,42 @@ describe('<TrialChrome> — state that outlives a mount', () => {
     expect(screen.getByTestId('notes-body')).toBeInTheDocument();
   });
 });
+
+describe('state undo in a mounted lab', () => {
+  const counter: Instrument<{ n: number }> = {
+    name: 'Counter',
+    defaultConfig: () => ({}),
+    initialState: () => ({ n: 0 }),
+    undo: { snapshotOn: ['bump'] },
+    render: (ctx) => (
+      <button
+        type="button"
+        onClick={() => {
+          ctx.emit('bump');
+          ctx.setState((s) => ({ n: s.n + 1 }));
+        }}
+      >
+        {`n=${ctx.state.n}`}
+      </button>
+    ),
+  };
+
+  it('undoes and redoes a change through the trial history', async () => {
+    await renderSettled(<Lab title="T" instruments={[counter]} defaultInstrument="Counter" />);
+    const undo = screen.getByRole('button', { name: 'Undo' });
+    const redo = screen.getByRole('button', { name: 'Redo' });
+    expect(undo).toBeDisabled();
+    fireEvent.click(screen.getByRole('button', { name: 'n=0' }));
+    fireEvent.click(screen.getByRole('button', { name: 'n=1' }));
+    expect(undo).not.toBeDisabled();
+    fireEvent.click(undo);
+    expect(screen.getByRole('button', { name: 'n=1' })).toBeInTheDocument();
+    fireEvent.click(undo);
+    expect(screen.getByRole('button', { name: 'n=0' })).toBeInTheDocument();
+    expect(undo).toBeDisabled();
+    fireEvent.click(redo);
+    fireEvent.click(redo);
+    expect(screen.getByRole('button', { name: 'n=2' })).toBeInTheDocument();
+    expect(redo).toBeDisabled();
+  });
+});

package/src/trial/Trial.tsx

@@ -1,5 +1,7 @@
 import {
+  createHistory,
   createPointerStore,
+  type History,
   PointerContextProvider,
   useLatest,
   WeaselProvider,
@@ -13,6 +15,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import { useStore } from 'zustand/react';
 import { AnnotationsContext } from '../annotations/AnnotationsContext';
@@ -28,6 +31,8 @@ import { fitStage, Stage } from '../canvas/Stage';
 import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
 import { applyCamera, type ViewportSize } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
+import { ClockRegistryContext, TrialClockContext } from '../clock/clockRegistry';
+import { createTrialClock } from '../clock/trialClock';
 import { useConfigSchema } from '../config/useConfigSchema';
 import { useResolvedConfig } from '../config/useResolvedConfig';
 import { DragOverlay, useDragDrop } from '../dragdrop/DragDropRuntime';
@@ -48,7 +53,7 @@ import type { TrialRecord } from '../state/types';
 import { as2DView, DEFAULT_VIEW, withZoom } from '../state/view';
 import { resolveLabTool } from '../tools/labTool';
 import { createEventBus, type EventBus } from '../undo/eventBus';
-import { pushSnapshot, redo as undoRedo, undo as undoUndo } from '../undo/undoStack';
+import { stateOp } from '../undo/stateOp';
 import { LoupeSwitchContext } from './loupeSwitch';
 import type { LoupeBindings, UndoBindings } from './TrialChrome';
 import { TrialChrome } from './TrialChrome';
@@ -161,7 +166,8 @@ function TrialRuntime({
   const updateTrialState = useStore(store, (s) => s.updateTrialState);
   const updateTrialConfig = useStore(store, (s) => s.updateTrialConfig);
   const updateTrialView = useStore(store, (s) => s.updateTrialView);
-  const updateTrialUndoStack = useStore(store, (s) => s.updateTrialUndoStack);
+  const setTrialHistory = useStore(store, (s) => s.setTrialHistory);
+  const updateTrialClock = useStore(store, (s) => s.updateTrialClock);
   const updateTrialAnnotations = useStore(store, (s) => s.updateTrialAnnotations);
   const labToolId = useStore(store, (s) => s.activeToolId);
   const setLabTool = useStore(store, (s) => s.setLabTool);
@@ -194,6 +200,28 @@ function TrialRuntime({
     [instrument.canvas, layerVisibility],
   );
 
+  // Read once: `record.clock` is where a reopened trial's clock stood, and the
+  // clock is the truth from then on. A swap mounts a new trial under a new id.
+  const [clockHandle] = useState(() =>
+    instrument.clock ? createTrialClock(instrument.clock, record.clock) : null,
+  );
+  const clocks = useContext(ClockRegistryContext);
+  useEffect(() => {
+    if (!clockHandle || !clocks) return;
+    return clocks.register(record.id, clockHandle);
+  }, [clocks, clockHandle, record.id]);
+  useEffect(() => {
+    if (!clockHandle) return;
+    const { clock } = clockHandle;
+    return clock.subscribe(() =>
+      updateTrialClock(record.id, { elapsed: clock.elapsed, rate: clock.rate }),
+    );
+  }, [clockHandle, record.id, updateTrialClock]);
+  const ticks = useMemo(
+    () => (clockHandle ? (fn: () => void) => clockHandle.onFrame(() => fn()) : undefined),
+    [clockHandle],
+  );
+
   const undoCap = instrument.undo;
   const undoEvents = useMemo(() => new Set(undoCap?.snapshotOn ?? ['state.change']), [undoCap]);
   const maxDepth = undoCap?.maxDepth ?? 50;
@@ -202,8 +230,14 @@ function TrialRuntime({
     if (!undoCap || !undoEvents.has(event)) return;
     const current = store.getState().trials.find((w) => w.id === record.id);
     if (!current) return;
-    const snap = structuredClone(current.state);
-    updateTrialUndoStack(record.id, (prev) => pushSnapshot(prev, snap, maxDepth));
+    let history = current.history;
+    if (!history) {
+      history = createHistory(null, { historyLimit: maxDepth });
+      setTrialHistory(record.id, history);
+    }
+    const read = () => store.getState().trials.find((w) => w.id === record.id)?.state;
+    const write = (state: unknown) => updateTrialState(record.id, state as never);
+    history.recordEntry([stateOp(structuredClone(current.state), read, write)], event);
   };
 
   const setView = (v: unknown): void => updateTrialView(record.id, v);
@@ -383,6 +417,7 @@ function TrialRuntime({
       activeToolId: resolvedToolId,
       visibleLayers,
       pointer,
+      ...(clockHandle ? { clock: clockHandle.clock } : {}),
     },
     emit: (event) => {
       snapshotIfNeeded(event);
@@ -395,31 +430,20 @@ function TrialRuntime({
   // stack — the spec's rule, and the reason a mark scene is the truth. A trial
   // declaring both takes the marks first: the most recent thing the user did
   // is what undo is for, and only a mark change moves the mark history.
-  const undoState = () => {
-    const result = undoUndo(record.undoStack, structuredClone(record.state));
-    if (!result) return;
-    updateTrialState(record.id, result.snapshot as never);
-    updateTrialUndoStack(record.id, result.stack);
-  };
-  const redoState = () => {
-    const result = undoRedo(record.undoStack, structuredClone(record.state));
-    if (!result) return;
-    updateTrialState(record.id, result.snapshot as never);
-    updateTrialUndoStack(record.id, result.stack);
-  };
+  const stateHistory = useHistoryVersion(record.history);
 
   const undoBindings: UndoBindings | undefined =
     undoCap || annotationsCap
       ? {
-          canUndo: markMoves.undo || (undoCap ? record.undoStack.past.length > 0 : false),
-          canRedo: markMoves.redo || (undoCap ? record.undoStack.future.length > 0 : false),
+          canUndo: markMoves.undo || (undoCap ? (stateHistory?.canUndo() ?? false) : false),
+          canRedo: markMoves.redo || (undoCap ? (stateHistory?.canRedo() ?? false) : false),
           undo: () => {
             if (annotationsCap && annotations.undo()) return;
-            if (undoCap) undoState();
+            if (undoCap) stateHistory?.undo();
           },
           redo: () => {
             if (annotationsCap && annotations.redo()) return;
-            if (undoCap) redoState();
+            if (undoCap) stateHistory?.redo();
           },
         }
       : undefined;
@@ -433,17 +457,26 @@ function TrialRuntime({
     const ordered = layerOrder
       ? [...baseLayers].sort((a, b) => layerOrder.indexOf(a.id) - layerOrder.indexOf(b.id))
       : baseLayers;
+    const clock = clockHandle?.clock;
     return ordered.map((layer) => ({
       id: layer.id,
       visible: layerVisibility[layer.id] !== false,
+      timed: layer.timed === true,
       render: (ctx, view, frame) => {
         // Camera applied here, so a layer draws in world coordinates. `zoom`
         // stays in the args for line widths, which must not scale with it.
         applyCamera(ctx, view, frame);
-        layer.draw(ctx, { state: record.state, config, zoom: view.zoom });
+        layer.draw(ctx, {
+          state: record.state,
+          config,
+          zoom: view.zoom,
+          elapsed: clock?.elapsed ?? 0,
+          pass: clock?.pass ?? 0,
+          phase: clock?.phase ?? 0,
+        });
       },
     }));
-  }, [instrument.canvas, record.state, config, layerVisibility, layerOrder]);
+  }, [instrument.canvas, record.state, config, layerVisibility, layerOrder, clockHandle]);
 
   const layerDescriptors: LayerDescriptor[] = useMemo(() => {
     if (!instrument.layers) return [];
@@ -528,6 +561,7 @@ function TrialRuntime({
           onResize={placeView}
           minZoom={instrument.canvas.minZoom}
           maxZoom={instrument.canvas.maxZoom}
+          ticks={ticks}
         >
           {instrument.render(renderCtx)}
         </CanvasStack>
@@ -625,27 +659,37 @@ function TrialRuntime({
 
   return (
     <TrialIdProvider trialId={record.id}>
-      <AnnotationsContext.Provider value={annotationsCap ? provided : null}>
-        <CameraWheelContext.Provider value={wheelSlot}>
-          <TrialChrome
-            job={jobCap ? job : undefined}
-            loupe={loupeBindings}
-            trialId={record.id}
-            record={record}
-            instrument={instrument}
-            isLastTrial={isLast}
-            undoBindings={undoBindings}
-            trialChrome={extraChrome}
-            chrome={chrome}
-            suppress={suppress}
-            activeToolId={resolvedToolId}
-            setActiveTool={setActiveTool}
-          >
-            {scopedBody}
-            {annotationOverlays}
-          </TrialChrome>
-        </CameraWheelContext.Provider>
-      </AnnotationsContext.Provider>
+      <TrialClockContext.Provider value={clockHandle}>
+        <AnnotationsContext.Provider value={annotationsCap ? provided : null}>
+          <CameraWheelContext.Provider value={wheelSlot}>
+            <TrialChrome
+              job={jobCap ? job : undefined}
+              loupe={loupeBindings}
+              trialId={record.id}
+              record={record}
+              instrument={instrument}
+              isLastTrial={isLast}
+              undoBindings={undoBindings}
+              trialChrome={extraChrome}
+              chrome={chrome}
+              suppress={suppress}
+              activeToolId={resolvedToolId}
+              setActiveTool={setActiveTool}
+            >
+              {scopedBody}
+              {annotationOverlays}
+            </TrialChrome>
+          </CameraWheelContext.Provider>
+        </AnnotationsContext.Provider>
+      </TrialClockContext.Provider>
     </TrialIdProvider>
   );
 }
+
+const NO_SUBSCRIBE = () => () => {};
+
+/** `history`, re-rendering the caller whenever it changes. */
+function useHistoryVersion(history: History | undefined): History | undefined {
+  useSyncExternalStore(history?.subscribe ?? NO_SUBSCRIBE, () => history?.getVersion() ?? 0);
+  return history;
+}

package/src/trial/TrialChrome.tsx

@@ -24,6 +24,8 @@ import { useResolvedConfig } from '../config/useResolvedConfig';
 import type { Instrument } from '../instrument/types';
 import type { JobHandle } from '../job/types';
 import { useLabContext } from '../lab/LabContext';
+import { usePresentedTrial } from '../lab/presentation';
+import { useLightboxControl } from '../lightbox/LightboxContext';
 import { JobProgress } from '../primitives/JobProgress';
 import { LabStoreContext } from '../state/context';
 import type { TrialRecord } from '../state/types';
@@ -98,6 +100,7 @@ export function TrialChrome({
   children,
 }: TrialChromeProps) {
   const lab = useLabContext();
+  const { presented, ref: presentedRef } = usePresentedTrial(trialId);
   const storeCtx = useContext(LabStoreContext);
   if (!storeCtx) throw new Error('[labkit] TrialChrome requires <LabStoreProvider>');
   const updateTrialView = useStore(storeCtx.store, (s) => s.updateTrialView);
@@ -141,6 +144,9 @@ export function TrialChrome({
     () => cameras?.get(trialId) ?? null,
   );
 
+  // The title bar carries the expand toggle, so the lightbox drops its own.
+  const lightbox = useLightboxControl();
+
   const ctx = useMemo<TrialChromeContext>(() => {
     const setZoom = (z: number): void => {
       if (camera) zoomCameraTo(camera, z);
@@ -161,6 +167,9 @@ export function TrialChrome({
       hasLoupe: loupe != null,
       loupeOn: loupe?.on ?? false,
       toggleLoupe: loupe?.toggle ?? NO_OP,
+      canExpand: lightbox != null,
+      expanded: lightbox?.expanded ?? false,
+      toggleExpanded: lightbox?.toggle ?? NO_OP,
       configSchema,
       configFields: instrument.config ? [] : (instrument.configSchema?.() ?? []),
       config: record.config,
@@ -210,6 +219,7 @@ export function TrialChrome({
     updateTrialState,
     undoBindings,
     loupe,
+    lightbox,
     view2d,
     activeToolId,
     setActiveTool,
@@ -245,7 +255,8 @@ export function TrialChrome({
 
   const handleKeyDown = (e: KeyboardEvent<HTMLElement>): void => {
     const mod = e.metaKey || e.ctrlKey;
-    if (!mod) return;
+    // A presented trial has no chrome, so nothing the chrome's keys act on.
+    if (!mod || presented) return;
     if (e.key === 'z' || e.key === 'Z') {
       e.preventDefault();
       if (e.shiftKey) ctx.redo();
@@ -258,9 +269,11 @@ export function TrialChrome({
 
   return (
     <section
+      ref={presentedRef}
       className="lk-trial"
       data-trial-id={trialId}
       data-focused={lab.trials.length > 1 && lab.focusedTrialId === trialId ? 'true' : undefined}
+      data-lk-presented={presented ? '' : undefined}
       aria-label={`Trial ${title}`}
       tabIndex={-1}
       onKeyDown={handleKeyDown}
@@ -280,7 +293,12 @@ export function TrialChrome({
           width={record.sidebarWidth}
           onWidthChange={(w) => updateTrialSidebarWidth(trialId, w)}
           contentClassName={
-            instrument.canvas || instrument.stage ? 'lk-trial__content--flush' : undefined
+            [
+              instrument.canvas || instrument.stage ? 'lk-trial__content--flush' : '',
+              presented ? 'lk-trial__stage' : '',
+            ]
+              .filter(Boolean)
+              .join(' ') || undefined
           }
           sidebar={
             <>

package/src/trial/trialOps.test.ts

@@ -258,7 +258,6 @@ describe('reorderTrials', () => {
       config: {},
       state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
-      undoStack: { past: [], future: [] },
     }) as never;
 
   it('reorders to match the given ids', () => {
@@ -322,7 +321,7 @@ describe('swapTrial', () => {
     expect(swapped.config).toEqual({ subject: 'moon', zoom: 1 });
     expect(swapped.state).toEqual({ label: 'MOON' });
     expect(swapped.configSeed).toEqual({ subject: 'moon' });
-    expect(swapped.undoStack).toEqual({ past: [], future: [] });
+    expect(swapped.history).toBeUndefined();
   });
 
   it('keeps the width the trial’s sidebar was dragged to', () => {

package/src/trial/trialOps.ts

@@ -89,7 +89,6 @@ export function addTrial(
     config,
     state,
     view: initialView(instrument),
-    undoStack: { past: [], future: [] },
   };
   if (options.config) record.configSeed = seeded.config;
   if (seeded.autoPaths.length > 0) record.autoSeed = seeded.autoPaths;
@@ -103,13 +102,13 @@ export function cloneTrial(trials: TrialRecord[], id: string): TrialRecord[] {
   const sourceIdx = trials.findIndex((w) => w.id === id);
   const source = trials[sourceIdx];
   if (!source) return trials;
+  const { history: _history, ...rest } = source;
   const clone: TrialRecord = {
-    ...source,
+    ...rest,
     id: newId(),
     config: structuredClone(source.config),
     state: structuredClone(source.state),
     view: structuredClone(source.view),
-    undoStack: { past: [], future: [] },
   };
   return [...trials.slice(0, sourceIdx + 1), clone, ...trials.slice(sourceIdx + 1)];
 }

package/src/undo/stateOp.ts

@@ -0,0 +1,21 @@
+import type { Op } from '@weasel-js/core';
+
+/**
+ * An undo entry over a trial's whole `state`: it holds the state as it stood
+ * `before`, and catches the state to redo to each time it is undone, since a
+ * snapshot is taken when an undoable event fires, before the change it
+ * announces has necessarily landed. Never serialized: trial undo is
+ * session-only.
+ */
+export function stateOp(before: unknown, read: () => unknown, write: (state: unknown) => void): Op {
+  let after: unknown;
+  const forward: Op = {
+    label: 'state',
+    apply: () => write(structuredClone(after)),
+    invert: () => {
+      after = structuredClone(read());
+      return { label: 'state', apply: () => write(structuredClone(before)), invert: () => forward };
+    },
+  };
+  return forward;
+}