@weasel-js/labkit 1.4.3 → 1.5.0

package/src/surface/useTiledSurface.test.tsx

@@ -286,4 +286,179 @@ describe('useTiledSurface', () => {
     flushFrames();
     expect(paint).toHaveBeenCalledTimes(1);
   });
+
+  /**
+   * The surface owner resizes the shared buffer from inside `onFrame`, which
+   * costs every tile its pixels. Both tests below are about the two ways that
+   * loss goes unrepaired.
+   */
+  describe('when the buffer loses its contents', () => {
+    it('keeps an invalidation the owner makes from inside onFrame', () => {
+      let handle: SurfaceHandle | null = null;
+      let claimAll = false;
+      function Owner() {
+        const surface = useTiledSurface({
+          onFrame: () => {
+            if (!claimAll) return;
+            claimAll = false;
+            // What `Lab` does after sizing the canvas: the buffer is blank, so
+            // every tile owes a repaint, not only the one that moved.
+            surface.invalidateAll();
+          },
+        });
+        handle = surface;
+        return (
+          <div
+            ref={(el) => {
+              if (!el) return;
+              stubBox(el, 0, 0, 800, 600);
+              surface.containerRef(el);
+            }}
+          >
+            <div ref={(el) => { if (!el) return; stubBox(el, 0, 0, 400, 600); surface.registerTile('a', el); }} />
+            <div ref={(el) => { if (!el) return; stubBox(el, 400, 0, 400, 600); surface.registerTile('b', el); }} />
+          </div>
+        );
+      }
+      render(<Owner />);
+      flushFrames();
+
+      const paintA = vi.fn();
+      act(() => {
+        handle?.registerPainter('a', paintA);
+        handle?.registerPainter('b', vi.fn());
+      });
+      flushFrames();
+      paintA.mockClear();
+
+      // Only b is dirty; the owner resizes the buffer during the frame, which
+      // blanks a as well.
+      claimAll = true;
+      act(() => handle?.invalidate('b'));
+      flushFrames();
+      flushFrames();
+
+      expect(paintA).toHaveBeenCalled();
+    });
+
+    it('tells the owner when the tile geometry changed, so it can clear', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+      );
+      flushFrames();
+      frames.length = 0;
+
+      // A plain repaint leaves every tile where it was.
+      act(() => handle?.invalidate('a'));
+      flushFrames();
+      expect(frames[0]?.retiled).toBe(false);
+      frames.length = 0;
+
+      // A tile moving strands its old pixels in the gutter; nothing but the
+      // owner can clear those, and this is how it hears about it.
+      stubBox(getByTestId('b'), 300, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(frames[0]?.retiled).toBe(true);
+    });
+
+    it('runs every registered clear before any painter, and only on a re-tile', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+      );
+      flushFrames();
+
+      const order: string[] = [];
+      const clearA = vi.fn(() => order.push('clearA'));
+      const clearB = vi.fn(() => order.push('clearB'));
+      act(() => {
+        handle?.registerClear('a', clearA);
+        handle?.registerClear('b', clearB);
+        handle?.registerPainter('a', () => order.push('paintA'));
+        handle?.registerPainter('b', () => order.push('paintB'));
+      });
+      flushFrames();
+      order.length = 0;
+      clearA.mockClear();
+
+      // A repaint of one tile leaves every other tile's pixels valid.
+      act(() => handle?.invalidate('a'));
+      flushFrames();
+      expect(clearA).not.toHaveBeenCalled();
+      expect(order).toEqual(['paintA']);
+      order.length = 0;
+
+      stubBox(getByTestId('b'), 300, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+
+      // Both tenants share the buffer, so both clears run — and a clear after
+      // a painter would erase the tile that just drew.
+      expect(order.slice(0, 2).sort()).toEqual(['clearA', 'clearB']);
+      expect(order.slice(2).sort()).toEqual(['paintA', 'paintB']);
+      expect(clearA).toHaveBeenCalledWith({ width: 800, height: 600 }, expect.any(Number));
+    });
+
+    it('keeps measuring while a tile is still moving, and stops when it settles', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+      );
+      flushFrames();
+
+      const seen: number[] = [];
+      act(() => {
+        handle?.registerPainter('b', (rect) => seen.push(rect.x));
+      });
+
+      // A panel whose size is already final but whose position is still
+      // animating: `ResizeObserver` has nothing left to report, so the only
+      // thing that can catch the last 60px is the surface measuring again.
+      const b = getByTestId('b');
+      const stops = [340, 370, 400, 400, 400];
+      let call = 0;
+      vi.spyOn(b, 'getBoundingClientRect').mockImplementation(() => {
+        const left = stops[Math.min(call++, stops.length - 1)]!;
+        return { left, top: 0, width: 400, height: 600, right: left + 400, bottom: 600, x: left, y: 0, toJSON: () => ({}) } as DOMRect;
+      });
+
+      seen.length = 0;
+      act(() => handle?.invalidateRects());
+      // One flush per animation frame; nothing else invalidates in between.
+      flushFrames();
+      flushFrames();
+      flushFrames();
+      flushFrames();
+
+      expect(seen.at(-1)).toBe(400);
+    });
+
+    it('stops calling a clear that unregisters', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+      );
+      flushFrames();
+
+      const clear = vi.fn();
+      let off: (() => void) | undefined;
+      act(() => { off = handle?.registerClear('a', clear); });
+      stubBox(getByTestId('b'), 310, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(clear).toHaveBeenCalledTimes(1);
+
+      act(() => off?.());
+      stubBox(getByTestId('b'), 320, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(clear).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/surface/useTiledSurface.ts

@@ -14,6 +14,11 @@ export interface SurfaceFrame {
   rects: ReadonlyMap<string, Rect>;
   dpr: number;
   size: { width: number; height: number };
+  /** The tile geometry changed this frame — a tile moved, resized, appeared or
+   *  went away, or the dpr did. Every tile is dirty on such a frame, but the
+   *  pixels a tile vacated are in no tile's scissor now, so the owner clears
+   *  the whole buffer. `<Lab>` does; a host owning its own surface must too. */
+  retiled: boolean;
 }
 
 /** The invalidators and the two ref callbacks that publish geometry. */
@@ -26,6 +31,12 @@ export interface SurfaceHandle {
    *  moved something a ResizeObserver cannot see. */
   invalidateRects: () => void;
   registerTile: (id: string, el: HTMLElement | null) => void;
+  /** Register a tenant's whole-buffer clear. Every one registered runs, before
+   *  any painter, on a frame where the tile geometry changed — the pixels a
+   *  tile vacated are in no scissor now, and only the context that drew them
+   *  can erase them. Backend-agnostic by necessity: labkit owns the canvas,
+   *  never the context. */
+  registerClear: (id: string, clear: SurfaceClear) => () => void;
   /** Subscribe a tile to the frames it is dirty on. A tile paints on its own
    *  loop, so this is how the surface wakes one: a resize of the shared buffer
    *  clears every tile, not only the one that moved. */
@@ -40,6 +51,10 @@ export interface SurfaceHandle {
  *  frame that dirtied it. */
 export type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
 
+/** Erase the whole shared buffer. Device pixels, because that is what a GL
+ *  viewport takes. */
+export type SurfaceClear = (size: { width: number; height: number }, dpr: number) => void;
+
 export interface UseTiledSurfaceOptions {
   onFrame: (frame: SurfaceFrame) => void;
 }
@@ -50,6 +65,7 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
   const rects = useRef(new Map<string, Rect>());
   const dirty = useRef(new Set<string>());
   const painters = useRef(new Map<string, TilePainter>());
+  const clears = useRef(new Map<string, SurfaceClear>());
   const needsMeasure = useRef(true);
   const observer = useRef<ResizeObserver | null>(null);
   const lastDpr = useRef(0);
@@ -80,13 +96,25 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
         dirty.current.clear();
         return;
       }
+      let retiled = false;
       if (needsMeasure.current) {
         needsMeasure.current = false;
-        if (measure()) for (const id of rects.current.keys()) dirty.current.add(id);
+        if (measure()) {
+          retiled = true;
+          for (const id of rects.current.keys()) dirty.current.add(id);
+          // Geometry that changed may still be moving: a panel whose size has
+          // settled while its position animates gives `ResizeObserver` nothing
+          // more to report, and the tile would hold the frame it was caught
+          // mid-flight at. Measure again next frame, and keep going until a
+          // measurement finds nothing moved.
+          needsMeasure.current = true;
+          schedule();
+        }
       }
       const dpr = globalThis.devicePixelRatio ?? 1;
       if (dpr !== lastDpr.current) {
         lastDpr.current = dpr;
+        retiled = true;
         for (const id of rects.current.keys()) dirty.current.add(id);
       }
       if (dirty.current.size === 0) return;
@@ -96,14 +124,27 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
         rects: new Map(rects.current),
         dpr,
         size: { width: box.width, height: box.height },
+        retiled,
       };
+      // Cleared before the owner runs, not after the painters: sizing the
+      // buffer blanks every tile, so the owner answers with `invalidateAll`,
+      // and a set cleared at the end of the frame would swallow it.
+      dirty.current.clear();
       onFrameRef.current(frame);
-      // After the owner, which is what resized the buffer this frame.
-      for (const id of frame.dirty) {
-        const rect = frame.rects.get(id);
-        if (rect) painters.current.get(id)?.(rect, frame);
+      // After the owner sized the buffer, before anything paints into it.
+      if (retiled) {
+        for (const clear of clears.current.values()) clear(frame.size, dpr);
       }
+      // After the owner, which is what resized the buffer this frame — and
+      // whatever it just dirtied paints now rather than a frame later.
+      const painting = new Set(frame.dirty);
+      for (const id of dirty.current) painting.add(id);
       dirty.current.clear();
+      const paintFrame: SurfaceFrame = { ...frame, dirty: painting };
+      for (const id of painting) {
+        const rect = frame.rects.get(id);
+        if (rect) painters.current.get(id)?.(rect, paintFrame);
+      }
     },
     // The host attaches its container through `containerRef`, which may land
     // well after this hook's first effect; the gate re-resolves it per request.
@@ -151,6 +192,13 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     [schedule],
   );
 
+  const registerClear = useCallback((id: string, clear: SurfaceClear) => {
+    clears.current.set(id, clear);
+    return () => {
+      if (clears.current.get(id) === clear) clears.current.delete(id);
+    };
+  }, []);
+
   const registerPainter = useCallback((id: string, paint: TilePainter) => {
     painters.current.set(id, paint);
     return () => {
@@ -192,6 +240,7 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     invalidateAll,
     invalidateRects,
     registerTile,
+    registerClear,
     registerPainter,
     containerRef,
     getContainer,

package/src/theme/Interstellar.stories.tsx

@@ -55,16 +55,16 @@ const ACCENT_TOKENS: Swatch[] = [
 ];
 
 const PALETTE_TOKENS: Swatch[] = [
+  { name: 'fuchsia', cssVar: '--wzl-swatch-fuchsia' },
   { name: 'green', cssVar: '--wzl-swatch-green' },
-  { name: 'pink', cssVar: '--wzl-swatch-pink' },
-  { name: 'cyan', cssVar: '--wzl-swatch-cyan' },
-  { name: 'gold', cssVar: '--wzl-swatch-gold' },
+  { name: 'sky', cssVar: '--wzl-swatch-sky' },
   { name: 'amber', cssVar: '--wzl-swatch-amber' },
+  { name: 'teal', cssVar: '--wzl-swatch-teal' },
+  { name: 'red', cssVar: '--wzl-swatch-red' },
+  { name: 'blue', cssVar: '--wzl-swatch-blue' },
+  { name: 'citron', cssVar: '--wzl-swatch-citron' },
+  { name: 'rose', cssVar: '--wzl-swatch-rose' },
   { name: 'violet', cssVar: '--wzl-swatch-violet' },
-  { name: 'mint', cssVar: '--wzl-swatch-mint' },
-  { name: 'sky', cssVar: '--wzl-swatch-sky' },
-  { name: 'orange', cssVar: '--wzl-swatch-orange' },
-  { name: 'magenta', cssVar: '--wzl-swatch-magenta' },
 ];
 
 function SwatchGrid({ tokens, title }: { tokens: readonly Swatch[]; title: string }) {

package/src/theme/base.less

@@ -79,13 +79,13 @@
     &::-webkit-slider-runnable-track {
       height: var(--wzl-slider-track-h);
       border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
     }
 
     &::-moz-range-track {
       height: var(--wzl-slider-track-h);
       border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
     }
 
     &::-webkit-slider-thumb {
@@ -95,7 +95,7 @@
       height: var(--wzl-slider-thumb-size);
       border: none;
       border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
       margin-top: calc((var(--wzl-slider-track-h) - var(--wzl-slider-thumb-size)) / 2);
     }
 
@@ -104,7 +104,7 @@
       height: var(--wzl-slider-thumb-size);
       border: none;
       border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
     }
   }
 }

package/src/theme/interstellar.test.ts

@@ -15,7 +15,7 @@ describe('interstellarTheme', () => {
 
     // Inherited from weasel — interstellar overrides values, not the token set.
     expect(dark['--wzl-space-md']).toBe('12px');
-    expect(dark['--wzl-swatch-cyan']).toBe('#00dfff');
+    expect(dark['--wzl-swatch-teal']).toBe('#3ee1cb');
 
     // Deliberate divergences from the base.
     expect(dark['--wzl-radius-md']).toBe('6px');

package/src/theme/interstellar.tokens.json

@@ -30,7 +30,7 @@
         "accent-hover": { "$value": "#c6a3ee" },
         "focus-ring": { "$value": "rgba(176, 138, 219, 0.45)" },
         "shadow": { "$value": "rgba(0, 0, 0, 0.7)" },
-        "border-raised": { "$value": "rgba(255, 255, 255, 0.36)" }
+        "border-strong": { "$value": "rgba(255, 255, 255, 0.36)" }
       },
       "gradient": {
         "$type": "gradient",
@@ -54,7 +54,7 @@
         "accent-hover": { "$value": "#c2854f" },
         "focus-ring": { "$value": "rgba(168, 111, 60, 0.35)" },
         "shadow": { "$value": "rgba(80, 60, 40, 0.18)" },
-        "border-raised": { "$value": "#9e8b71" }
+        "border-strong": { "$value": "#9e8b71" }
       }
     }
   }

package/src/tools/labTool.ts

@@ -0,0 +1,11 @@
+import type { InstrumentList } from '../instrument/types';
+
+/**
+ * The tool the lab's slot holds, once its default is applied: a lab with any
+ * annotating instrument starts in `select`, so a first click on a picture
+ * selects rather than draws.
+ */
+export function resolveLabTool(slot: string | null, instruments: InstrumentList): string | null {
+  if (slot !== null) return slot;
+  return instruments.some((i) => i.annotations != null) ? 'select' : null;
+}

package/src/trial/Trial.annotations.persist.test.tsx

@@ -4,15 +4,16 @@
  * is written on a trailing debounce: a write per scene notification re-renders
  * every trial on every frame of a drag.
  */
-import { act, render } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { useAnnotations } from '../annotations/AnnotationsContext';
 import type { AnnotationsApi, SerializedAnnotations } from '../annotations/types';
 import { defineInstrument } from '../instrument/defineInstrument';
 import type { InstrumentList } from '../instrument/types';
 import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
 import { createMemoryAdapter } from '../state/adapters';
-import type { StorageAdapter } from '../state/types';
+import { labPrefix } from '../state/labRecords';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(
@@ -21,12 +22,24 @@ beforeAll(() => {
 });
 
 let api: AnnotationsApi | null = null;
+let lab: LabContextValue | null = null;
 
 function Pane() {
   api = useAnnotations();
   return <div data-testid="pane" />;
 }
 
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        lab = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
 /** Read through a call, so TypeScript does not narrow the module-level `api`
  *  to `null` across the remounts these tests are about. */
 function marks(): AnnotationsApi {
@@ -46,6 +59,8 @@ const inspector = defineInstrument<Record<string, never>, { angle: number }>({
 
 /** The instrument keeps its own marks, so labkit must not keep them too. */
 let owned: SerializedAnnotations | null = null;
+let loads = 0;
+let gate: Promise<void> = Promise.resolve();
 const selfStoring = defineInstrument<Record<string, never>, Record<string, never>>({
   name: 'SelfStoring',
   defaultConfig: () => ({}),
@@ -54,7 +69,11 @@ const selfStoring = defineInstrument<Record<string, never>, Record<string, never
   annotations: {
     targets: () => [TARGET],
     storage: {
-      load: () => owned,
+      load: async () => {
+        loads++;
+        await gate;
+        return owned;
+      },
       save: (doc) => {
         owned = doc;
       },
@@ -62,42 +81,51 @@ const selfStoring = defineInstrument<Record<string, never>, Record<string, never
   },
 });
 
-function mount(storage: StorageAdapter, which: InstrumentList[number] = inspector) {
-  return render(
+async function mount(backing: Map<string, unknown>, which: InstrumentList[number] = inspector) {
+  api = null;
+  const view = render(
     <Lab
       instruments={[which]}
       defaultInstrument={which.name}
-      storage={storage}
+      storage={createMemoryAdapter(backing)}
       storageKey="persist-test"
-    />,
+    >
+      <CaptureLab />
+    </Lab>,
   );
+  await waitFor(() => expect(api).not.toBeNull());
+  return view;
+}
+
+function storedTrial(backing: Map<string, unknown>): Record<string, unknown> | undefined {
+  const prefix = `${labPrefix('persist-test')}trial:`;
+  return [...backing].find(([key]) => key.startsWith(prefix))?.[1] as
+    | Record<string, unknown>
+    | undefined;
 }
 
 const MARK = { target: 'pane', kind: 'rect' as const, frac: { x: 0.2, y: 0.3, w: 0.1, h: 0.1 } };
 
 describe('a trial that persists its marks', () => {
   beforeEach(() => {
-    vi.useFakeTimers();
     api = null;
+    lab = null;
     owned = null;
+    loads = 0;
+    gate = Promise.resolve();
   });
   afterEach(() => {
     vi.useRealTimers();
   });
 
-  it('brings them back on a remount from the same storage', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('brings them back on a remount from the same storage', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing);
     const id = marks().add(MARK, { angle: 12 });
-
-    // Past both debounces: labkit's write-back, then the document flush.
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
     first.unmount();
+    await waitFor(() => expect(storedTrial(backing)?.annotations).toBeDefined());
 
-    api = null;
-    mount(storage);
+    await mount(backing);
     const back = marks().get(id);
     expect(back).toMatchObject({ id, target: 'pane', kind: 'rect', frac: MARK.frac });
     // The staleness snapshot has to survive too, or every restored mark reads
@@ -107,60 +135,74 @@ describe('a trial that persists its marks', () => {
     expect(marks().isStale(back, { angle: 45 })).toBe(true);
   });
 
-  it('writes nothing before the debounce elapses', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('keeps a mark out of storage until both debounces pass, while the lab stays open', async () => {
+    const backing = new Map<string, unknown>();
+    await mount(backing);
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
     marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(20);
-    });
-    first.unmount();
-
-    api = null;
-    mount(storage);
-    // Not a claim about the debounce interval — a claim that one exists, and
-    // that a store write is not synchronous with a scene notification.
-    //
-    // It is also the no-migration claim: the document this remount reads was
-    // written with trials and no `annotations` field, exactly as every
-    // document from before this arc is, and the trial opens on an empty store
-    // rather than failing to load.
-    expect(marks().query()).toHaveLength(0);
+    await act(() => vi.advanceTimersByTimeAsync(20));
+    // Not a claim about either interval — a claim that a store write is not
+    // synchronous with a scene notification.
+    expect(storedTrial(backing)?.annotations).toBeUndefined();
+    await act(() => vi.advanceTimersByTimeAsync(2000));
+    expect(storedTrial(backing)?.annotations).toBeDefined();
   });
 
-  it('flushes on unmount, so the last mark before a close is not lost', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('flushes on unmount, so the last mark before a close is not lost', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing);
     const id = marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     marks().add({ ...MARK, frac: { x: 0.6, y: 0.6, w: 0.1, h: 0.1 } });
     first.unmount();
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
+    // Nothing was written before the unmount: neither debounce had elapsed.
+    await waitFor(() => expect(storedTrial(backing)?.annotations).toBeDefined());
 
-    api = null;
-    mount(storage);
+    await mount(backing);
     expect(marks().query()).toHaveLength(2);
     expect(marks().get(id)).toBeDefined();
   });
 
-  it('leaves the slot alone when the instrument owns the storage', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage, selfStoring);
+  it('leaves the slot alone when the instrument owns the storage', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing, selfStoring);
     marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
     first.unmount();
+    await waitFor(() => expect(owned?.version).toBe(1));
+    await waitFor(() => expect(storedTrial(backing)).toBeDefined());
+    expect(storedTrial(backing)).not.toHaveProperty('annotations');
 
-    expect(owned?.version).toBe(1);
-    expect(storage.read('lk:persist-test:doc')).not.toContain('"annotations"');
-
-    api = null;
-    mount(storage, selfStoring);
+    await mount(backing, selfStoring);
     expect(marks().query()).toHaveLength(1);
   });
+
+  it('loads instrument-owned marks before the lab shows, and a later trial before its body', async () => {
+    const backing = new Map<string, unknown>();
+    let release = (): void => {};
+    gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    render(
+      <Lab
+        instruments={[selfStoring]}
+        defaultInstrument="SelfStoring"
+        storage={createMemoryAdapter(backing)}
+        storageKey="persist-test"
+      >
+        <CaptureLab />
+      </Lab>,
+    );
+    await waitFor(() => expect(loads).toBe(1));
+    expect(screen.queryByTestId('pane')).toBeNull();
+    await act(async () => release());
+    expect(await screen.findByTestId('pane')).toBeInTheDocument();
+
+    gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    act(() => lab?.addTrial('SelfStoring'));
+    expect(document.querySelectorAll('.lk-trial--loading')).toHaveLength(1);
+    await act(async () => release());
+    await waitFor(() => expect(screen.getAllByTestId('pane')).toHaveLength(2));
+    expect(loads).toBe(2);
+  });
 });