@weasel-js/labkit 1.4.4 → 1.5.1

package/src/state/store.test.ts

@@ -1,17 +1,15 @@
-import { describe, expect, it, vi } from 'vitest';
-import { createMemoryAdapter } from './adapters';
-import { CURRENT_DOCUMENT_VERSION, labDocumentKey, quarantineKey } from './document';
-import { labStorageKey } from './helpers';
+import { describe, expect, it } from 'vitest';
+import { auto } from '../config/auto';
+import type { Instrument } from '../instrument/types';
 import { createLabStore } from './store';
+import type { CreateLabStoreOptions } from './types';
 
-function makeStore(overrides?: Partial<Parameters<typeof createLabStore>[0]>) {
-  return createLabStore({
-    storageKey: 'test',
-    storage: createMemoryAdapter(),
-    ...overrides,
-  });
+function makeStore(overrides?: CreateLabStoreOptions) {
+  return createLabStore({ ...overrides });
 }
 
+const VIEW = { zoom: 1, pan: { x: 0, y: 0 } };
+
 describe('createLabStore — initial state', () => {
   it('starts with empty trials and saves', () => {
     const s = makeStore();
@@ -125,104 +123,12 @@ describe('updateTrialConfig', () => {
   });
 });
 
-describe('createLabStore - config defaults', () => {
-  const stored = (config: unknown) =>
-    JSON.stringify({
-      version: CURRENT_DOCUMENT_VERSION,
-      trials: [
-        {
-          id: 'w1',
-          instrumentName: 'T',
-          config,
-          state: {},
-          view: { zoom: 1, pan: { x: 0, y: 0 } },
-        },
-      ],
-      saves: [
-        {
-          id: 's1',
-          name: 'saved',
-          trialId: 'w1',
-          instrumentName: 'T',
-          config,
-          state: {},
-          savedAt: 1,
-        },
-      ],
-      layout: {},
-      undockedPanels: {},
-      mode: 'auto',
-    });
-
-  it('fills a branch a config stored before the schema nested it never had', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), stored({ showGrid: false, gridSize: 40 }));
-    const s = createLabStore({
-      storageKey: 'test',
-      storage,
-      configDefaults: { T: () => ({ showGrid: true, grid: { size: 20, color: '#fff' } }) },
-    });
-    expect(s.getState().trials[0]?.config).toEqual({
-      showGrid: false,
-      gridSize: 40,
-      grid: { size: 20, color: '#fff' },
-    });
-  });
-
-  it('fills the config on a saved snapshot the same way', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), stored({ grid: { size: 40 } }));
-    const s = createLabStore({
-      storageKey: 'test',
-      storage,
-      configDefaults: { T: () => ({ grid: { size: 20, color: '#fff' } }) },
-    });
-    expect(s.getState().savedSnapshots[0]?.config).toEqual({
-      grid: { size: 40, color: '#fff' },
-    });
-  });
-
-  it('hands a deserializer the filled config, not the stored one', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), stored({ grid: { size: 40 } }));
-    const seen: unknown[] = [];
-    createLabStore({
-      storageKey: 'test',
-      storage,
-      configDefaults: { T: () => ({ grid: { size: 20, color: '#fff' } }) },
-      serializers: {
-        T: {
-          deserialize: (state, config) => {
-            seen.push(config);
-            return state;
-          },
-        },
-      },
-    });
-    expect(seen).toEqual([{ grid: { size: 40, color: '#fff' } }]);
-  });
-
-  it('leaves a config alone when no defaults are registered for its instrument', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), stored({ only: 1 }));
-    const s = createLabStore({ storageKey: 'test', storage });
-    expect(s.getState().trials[0]?.config).toEqual({ only: 1 });
-  });
-});
-
 describe('setMode', () => {
   it('updates mode', () => {
     const s = makeStore();
     s.getState().setMode('dark');
     expect(s.getState().mode).toBe('dark');
   });
-
-  it('hydrates a stored interstellar preference as dark', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('test', 'theme'), 'interstellar');
-    const s = createLabStore({ storageKey: 'test', storage });
-    expect(s.getState().mode).toBe('dark');
-  });
 });
 
 describe('save/load/delete snapshots', () => {
@@ -258,133 +164,90 @@ describe('save/load/delete snapshots', () => {
     expect((s.getState().trials[0]?.state as { n: number }).n).toBe(5);
   });
 
-  it('loadSnapshot blocks cross-instrument load', () => {
+  it('loadSnapshot restores the auto paths the trial had when saved', () => {
     const s = makeStore();
     s.getState().addTrial({
       id: 'w1',
-      instrumentName: 'A',
-      config: {},
-      state: { n: 1 },
+      instrumentName: 'T',
+      config: { x: 1, y: 2 },
+      state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
+      auto: ['x'],
     });
-    s.getState().saveSnapshot('w1', 'snap-a');
-    s.getState().setTrialInstrument('w1', 'B');
+    s.getState().saveSnapshot('w1', 'snap1');
+    expect(s.getState().savedSnapshots[0]?.auto).toEqual(['x']);
     const snapId = s.getState().savedSnapshots[0]?.id ?? '';
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    s.getState().loadSnapshot(snapId, 'w1');
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
+
+    const w = s.getState().trials[0];
+    s.getState().addTrial({ ...(w as NonNullable<typeof w>), id: 'w2', auto: ['y'] });
+    s.getState().loadSnapshot(snapId, 'w2');
+    expect(s.getState().trials[1]?.auto).toEqual(['x']);
   });
 
-  it('deleteSnapshot removes the snapshot', () => {
+  it('a snapshot saved with nothing auto pins every field on load', () => {
     const s = makeStore();
     s.getState().addTrial({
       id: 'w1',
       instrumentName: 'T',
-      config: {},
+      config: { x: 1 },
       state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    s.getState().saveSnapshot('w1', 'snap');
-    const id = s.getState().savedSnapshots[0]?.id ?? '';
-    s.getState().deleteSnapshot(id);
-    expect(s.getState().savedSnapshots).toHaveLength(0);
+    s.getState().saveSnapshot('w1', 'snap1');
+    expect(s.getState().savedSnapshots[0]?.auto).toEqual([]);
+    const snapId = s.getState().savedSnapshots[0]?.id ?? '';
+    s.getState().updateTrialConfig('w1', 'x', auto);
+    expect(s.getState().trials[0]?.auto).toEqual(['x']);
+    s.getState().loadSnapshot(snapId, 'w1');
+    expect(s.getState().trials[0]?.auto).toBeUndefined();
   });
 
-  it('listSnapshots returns newest first', () => {
-    const s = makeStore();
-    s.getState().addTrial({
-      id: 'w1',
+  it("a snapshot saved before snapshots carried auto paths leaves the trial's own", () => {
+    const snap = {
+      id: 'old',
+      name: 'old',
+      trialId: 'w1',
       instrumentName: 'T',
-      config: {},
+      config: { x: 7 },
       state: {},
-      view: { zoom: 1, pan: { x: 0, y: 0 } },
+      savedAt: 1,
+    };
+    const s = makeStore({
+      initial: { version: 1, trials: [], saves: [snap], mode: 'auto' } as never,
     });
-    s.getState().saveSnapshot('w1', 'first');
-    s.getState().saveSnapshot('w1', 'second');
-    const list = s.getState().listSnapshots('w1');
-    expect(list[0]?.name).toBe('second');
-  });
-});
-
-describe('persistence — hydration', () => {
-  it('hydrates trials from storage on construction', () => {
-    vi.useFakeTimers();
-    const mem = createMemoryAdapter();
-    const seedStore = createLabStore({ storageKey: 'test', storage: mem });
-    seedStore.getState().addTrial({
+    s.getState().addTrial({
       id: 'w1',
       instrumentName: 'T',
-      config: {},
-      state: { n: 7 },
+      config: { x: 1 },
+      state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
+      auto: ['x'],
     });
-    vi.advanceTimersByTime(500);
-    vi.useRealTimers();
-
-    const hydrated = createLabStore({ storageKey: 'test', storage: mem });
-    expect(hydrated.getState().trials).toHaveLength(1);
-    expect((hydrated.getState().trials[0]?.state as { n: number }).n).toBe(7);
+    s.getState().loadSnapshot('old', 'w1');
+    expect(s.getState().trials[0]?.config).toEqual({ x: 7 });
+    expect(s.getState().trials[0]?.auto).toEqual(['x']);
   });
 
-  // An instrument holding a Map, a Set or anything else JSON drops needs these
-  // to run at both ends. They are read while the store is being built, which
-  // is why they arrive as an option rather than being registered afterwards.
-  it("runs an instrument's serializers at flush and at hydrate", () => {
-    vi.useFakeTimers();
-    const mem = createMemoryAdapter();
-    const serializers = {
-      T: {
-        serialize: (state: unknown) => [...(state as Map<string, number>)],
-        deserialize: (data: unknown) => new Map(data as [string, number][]),
-      },
-    };
-
-    const seed = createLabStore({ storageKey: 'test', storage: mem, serializers });
-    seed.getState().addTrial({
+  it('loadSnapshot blocks cross-instrument load', () => {
+    const s = makeStore();
+    s.getState().addTrial({
       id: 'w1',
-      instrumentName: 'T',
+      instrumentName: 'A',
       config: {},
-      state: new Map([['a', 1]]),
-      view: { zoom: 1, pan: { x: 0, y: 0 } },
-    });
-    vi.advanceTimersByTime(500);
-    vi.useRealTimers();
-
-    const written = mem.read(labDocumentKey('test')) ?? '';
-    expect(written).toContain('[["a",1]]');
-
-    const hydrated = createLabStore({ storageKey: 'test', storage: mem, serializers });
-    expect(hydrated.getState().trials[0]?.state).toEqual(new Map([['a', 1]]));
-  });
-
-  it('hands `deserialize` the config the state was saved against', () => {
-    vi.useFakeTimers();
-    const mem = createMemoryAdapter();
-    const deserialize = vi.fn((data: unknown) => data);
-    const seed = createLabStore({ storageKey: 'test', storage: mem });
-    seed.getState().addTrial({
-      id: 'w1',
-      instrumentName: 'T',
-      config: { scale: 4 },
       state: { n: 1 },
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    vi.advanceTimersByTime(500);
-    vi.useRealTimers();
-
-    createLabStore({ storageKey: 'test', storage: mem, serializers: { T: { deserialize } } });
-    expect(deserialize).toHaveBeenCalledWith({ n: 1 }, { scale: 4 });
+    s.getState().saveSnapshot('w1', 'snap-a');
+    s.getState().setTrialInstrument('w1', 'B');
+    const snapId = s.getState().savedSnapshots[0]?.id ?? '';
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    s.getState().loadSnapshot(snapId, 'w1');
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
   });
-});
-
-describe('persistence — debounced writes', () => {
-  it('multiple rapid mutations produce one write call', () => {
-    vi.useFakeTimers();
-    const mem = createMemoryAdapter();
-    const writeSpy = vi.spyOn(mem, 'write');
-    const s = createLabStore({ storageKey: 'test', storage: mem });
 
+  it('deleteSnapshot removes the snapshot', () => {
+    const s = makeStore();
     s.getState().addTrial({
       id: 'w1',
       instrumentName: 'T',
@@ -392,415 +255,25 @@ describe('persistence — debounced writes', () => {
       state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    s.getState().updateTrialState('w1', { n: 1 });
-    s.getState().updateTrialState('w1', { n: 2 });
-    s.getState().updateTrialState('w1', { n: 3 });
-
-    const writesBefore = writeSpy.mock.calls.length;
-    vi.advanceTimersByTime(400);
-    const writesAfter = writeSpy.mock.calls.length;
-
-    // One flush, one document.
-    expect(writesAfter - writesBefore).toBe(1);
-    vi.useRealTimers();
-  });
-});
-
-describe('createLabStore — hydrating', () => {
-  it('reads a current-version document', () => {
-    const storage = createMemoryAdapter();
-    storage.write(
-      labDocumentKey('test'),
-      JSON.stringify({
-        version: CURRENT_DOCUMENT_VERSION,
-        trials: [
-          {
-            id: 'w1',
-            instrumentName: 'Test',
-            config: {},
-            state: {},
-            view: { zoom: 2, pan: { x: 0, y: 0 } },
-          },
-        ],
-        saves: [],
-        layout: { w1: { h: 3 } },
-        mode: 'dark',
-      }),
-    );
-
-    const s = makeStore({ storage }).getState();
-    expect(s.trials).toHaveLength(1);
-    expect(s.trials[0].undoStack).toEqual({ past: [], future: [] });
-    expect(s.layout).toEqual({ w1: { h: 3 } });
-    expect(s.mode).toBe('dark');
-  });
-
-  it('opens a version-1 document, whose tiles were still called workspaces', () => {
-    const storage = createMemoryAdapter();
-    storage.write(
-      labDocumentKey('test'),
-      JSON.stringify({
-        version: 1,
-        workspaces: [
-          {
-            id: 'w1',
-            instrumentName: 'Test',
-            config: { gain: 3 },
-            state: { n: 7 },
-            view: { zoom: 2, pan: { x: 0, y: 0 } },
-          },
-        ],
-        saves: [{ id: 's1', name: 'a save', trialId: 'w1' }],
-        layout: { w1: { h: 3 } },
-        mode: 'dark',
-      }),
-    );
-
-    const s = makeStore({ storage }).getState();
-    expect(s.trials).toHaveLength(1);
-    expect(s.trials[0]).toMatchObject({ id: 'w1', config: { gain: 3 }, state: { n: 7 } });
-    expect(s.savedSnapshots).toHaveLength(1);
-    expect(s.layout).toEqual({ w1: { h: 3 } });
-    expect(s.mode).toBe('dark');
-  });
-
-  it('folds the four legacy keys into state', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('test', 'workspaces'), JSON.stringify([]));
-    storage.write(labStorageKey('test', 'theme'), 'interstellar');
-
-    const s = makeStore({ storage }).getState();
-    expect(s.mode).toBe('dark');
-  });
-
-  it('honors initialMode when a folded legacy lab never set a theme', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('test', 'workspaces'), JSON.stringify([]));
-
-    const s = makeStore({ storage, initialMode: 'dark' }).getState();
-    expect(s.mode).toBe('dark');
-  });
-
-  it('starts empty and preserves a document from a future version', () => {
-    const storage = createMemoryAdapter();
-    const future = JSON.stringify({ version: 999, trials: [{ id: 'w1' }] });
-    storage.write(labDocumentKey('test'), future);
-
-    const store = makeStore({ storage });
-    expect(store.getState().trials).toEqual([]);
-    expect(storage.read(labDocumentKey('test'))).toBe(future);
-  });
-
-  it('quarantines a document that fails to parse', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), '{{{not json');
-
-    const s = makeStore({ storage }).getState();
-    expect(s.trials).toEqual([]);
-    expect(storage.read(quarantineKey('test'))).toBe('{{{not json');
-  });
-});
-
-describe('createLabStore — flushing', () => {
-  it('writes one document and no legacy keys', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const s = makeStore({ storage });
-    s.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.version).toBe(CURRENT_DOCUMENT_VERSION);
-    expect(doc.mode).toBe('light');
-  });
-
-  it('deletes the legacy keys once the folded document is written', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('test', 'workspaces'), JSON.stringify([]));
-    storage.write(labStorageKey('test', 'theme'), 'interstellar');
-
-    const s = makeStore({ storage });
-    s.getState().setMode('dark');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(labDocumentKey('test'))).not.toBeNull();
-    expect(storage.read(labStorageKey('test', 'workspaces'))).toBeNull();
-    expect(storage.read(labStorageKey('test', 'theme'))).toBeNull();
-  });
-
-  it('does not write when the stored document is from the future', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const future = JSON.stringify({ version: 999 });
-    storage.write(labDocumentKey('test'), future);
-
-    const s = makeStore({ storage });
-    s.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(labDocumentKey('test'))).toBe(future);
-  });
-
-  it('keeps the legacy keys when the document write silently fails', () => {
-    vi.useFakeTimers();
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const storage = createMemoryAdapter();
-    const write = storage.write.bind(storage);
-    // A quota failure as localStorageAdapter reports one: swallowed, void.
-    storage.write = (key, value) => {
-      if (key === labDocumentKey('test')) return;
-      write(key, value);
-    };
-    storage.write(labStorageKey('test', 'workspaces'), JSON.stringify([]));
-    storage.write(labStorageKey('test', 'theme'), 'interstellar');
-
-    const s = makeStore({ storage });
-    s.getState().setMode('dark');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(labDocumentKey('test'))).toBeNull();
-    expect(storage.read(labStorageKey('test', 'workspaces'))).toBe('[]');
-    expect(storage.read(labStorageKey('test', 'theme'))).toBe('interstellar');
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
+    s.getState().saveSnapshot('w1', 'snap');
+    const id = s.getState().savedSnapshots[0]?.id ?? '';
+    s.getState().deleteSnapshot(id);
+    expect(s.getState().savedSnapshots).toHaveLength(0);
   });
-});
-
-const VIEW = { zoom: 1, pan: { x: 0, y: 0 } };
-
-const SNAPSHOT = {
-  id: 's1',
-  name: 'saved',
-  trialId: 'w1',
-  instrumentName: 'T',
-  config: { x: 1 },
-  state: { n: 5 },
-  savedAt: 1000,
-};
-
-function writeDocument(
-  storage: ReturnType<typeof createMemoryAdapter>,
-  doc: Record<string, unknown>,
-  storageKey = 'test',
-): void {
-  storage.write(
-    labDocumentKey(storageKey),
-    JSON.stringify({ version: CURRENT_DOCUMENT_VERSION, ...doc }),
-  );
-}
-
-describe('createLabStore — labs whose keys once aliased', () => {
-  it("keeps a document out of a sibling lab's legacy bucket", () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
 
-    // Lab "a:saves" writes where lab "a"'s legacy saves bucket used to live.
-    const sibling = createLabStore({ storageKey: 'a:saves', storage });
-    sibling.getState().addTrial({
-      id: 'sw',
+  it('listSnapshots returns newest first', () => {
+    const s = makeStore();
+    s.getState().addTrial({
+      id: 'w1',
       instrumentName: 'T',
       config: {},
-      state: { n: 1 },
-      view: VIEW,
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    vi.advanceTimersByTime(400);
-    const siblingDocument = storage.read(labDocumentKey('a:saves'));
-    expect(siblingDocument).not.toBeNull();
-
-    storage.write(labStorageKey('a', 'workspaces'), JSON.stringify([]));
-    storage.write(labStorageKey('a', 'theme'), 'dark');
-
-    const lab = createLabStore({ storageKey: 'a', storage });
-    // Lab "a" does not read the sibling's document as its own saves bucket.
-    expect(lab.getState().savedSnapshots).toEqual([]);
-    expect(lab.getState().trials).toEqual([]);
-
-    lab.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    // Folding lab "a" deletes its own legacy keys, not the sibling's document.
-    expect(storage.read(labStorageKey('a', 'workspaces'))).toBeNull();
-    expect(storage.read(labDocumentKey('a:saves'))).toBe(siblingDocument);
-    const rehydrated = createLabStore({ storageKey: 'a:saves', storage });
-    expect(rehydrated.getState().trials).toHaveLength(1);
-  });
-});
-
-describe('createLabStore — hydrating an incomplete current-version document', () => {
-  it('hydrates a document with no saves as an empty snapshot list', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, { trials: [], layout: {}, mode: 'dark' });
-
-    const s = makeStore({ storage }).getState();
-    expect(s.savedSnapshots).toEqual([]);
-    expect(s.listSnapshots()).toEqual([]);
-  });
-
-  it('hydrates a document with no layout as an empty layout', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, { trials: [], saves: [], mode: 'dark' });
-
-    expect(makeStore({ storage }).getState().layout).toEqual({});
-  });
-
-  it('falls back to initialMode when the document has no mode', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, { trials: [], saves: [], layout: {} });
-
-    expect(makeStore({ storage, initialMode: 'light' }).getState().mode).toBe('light');
-  });
-
-  it('hydrates a document holding nothing but its version', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, {});
-
-    const s = makeStore({ storage }).getState();
-    expect(s.trials).toEqual([]);
-    expect(s.savedSnapshots).toEqual([]);
-    expect(s.layout).toEqual({});
-    expect(s.mode).toBe('auto');
-    expect(s.listSnapshots()).toEqual([]);
-  });
-
-  it('can save a snapshot into a document that had no saves', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, {});
-
-    const s = makeStore({ storage });
-    s.getState().addTrial({ id: 'w1', instrumentName: 'T', config: {}, state: {}, view: VIEW });
-    s.getState().saveSnapshot('w1', 'first');
-    expect(s.getState().listSnapshots('w1')).toHaveLength(1);
-  });
-});
-
-describe('persistence — saves and layout round-trip', () => {
-  it('hydrates a populated saves array into the store', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, { trials: [], saves: [SNAPSHOT], layout: {}, mode: 'auto' });
-
-    const s = makeStore({ storage }).getState();
-    expect(s.savedSnapshots).toEqual([SNAPSHOT]);
-    expect(s.listSnapshots('w1')).toEqual([SNAPSHOT]);
-  });
-
-  it('writes the hydrated saves back out on the next flush', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    writeDocument(storage, { trials: [], saves: [SNAPSHOT], layout: {}, mode: 'auto' });
-
-    const s = makeStore({ storage });
-    s.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.saves).toEqual([SNAPSHOT]);
-  });
-
-  it('writes a snapshot saved this session out on flush', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const s = makeStore({ storage });
-    s.getState().addTrial({ id: 'w1', instrumentName: 'T', config: {}, state: {}, view: VIEW });
     s.getState().saveSnapshot('w1', 'first');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.saves).toHaveLength(1);
-    expect(doc.saves[0].name).toBe('first');
-  });
-
-  it('writes the layout out on flush', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const s = makeStore({ storage });
-    s.getState().setLayout({ w1: { h: 9 } });
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.layout).toEqual({ w1: { h: 9 } });
-  });
-});
-
-describe('createLabStore — quarantining an unusable document', () => {
-  it('persists again once the unusable document is safely quarantined', () => {
-    vi.useFakeTimers();
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const storage = createMemoryAdapter();
-    storage.write(labDocumentKey('test'), '{{{not json');
-
-    const s = makeStore({ storage });
-    s.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(quarantineKey('test'))).toBe('{{{not json');
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.mode).toBe('light');
-    warn.mockRestore();
-  });
-
-  it('leaves the original alone when the quarantine copy cannot be written', () => {
-    vi.useFakeTimers();
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const storage = createMemoryAdapter();
-    const write = storage.write.bind(storage);
-    // A quota failure as localStorageAdapter reports one: swallowed, void.
-    storage.write = (key, value) => {
-      if (key === quarantineKey('test')) return;
-      write(key, value);
-    };
-    storage.write(labDocumentKey('test'), '{{{not json');
-
-    const s = makeStore({ storage });
-    s.getState().setMode('light');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(labDocumentKey('test'))).toBe('{{{not json');
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
-  });
-});
-
-describe('createLabStore — folding without a mutation', () => {
-  it('completes the fold on first load alone', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('test', 'workspaces'), JSON.stringify([]));
-    storage.write(labStorageKey('test', 'theme'), 'interstellar');
-
-    makeStore({ storage });
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    const doc = JSON.parse(storage.read(labDocumentKey('test')) as string);
-    expect(doc.mode).toBe('dark');
-    expect(storage.read(labStorageKey('test', 'workspaces'))).toBeNull();
-    expect(storage.read(labStorageKey('test', 'theme'))).toBeNull();
-  });
-
-  it('does not schedule a write for a document from the future', () => {
-    vi.useFakeTimers();
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const storage = createMemoryAdapter();
-    const future = JSON.stringify({ version: 999 });
-    storage.write(labDocumentKey('test'), future);
-
-    makeStore({ storage });
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(storage.read(labDocumentKey('test'))).toBe(future);
-    warn.mockRestore();
+    s.getState().saveSnapshot('w1', 'second');
+    const list = s.getState().listSnapshots('w1');
+    expect(list[0]?.name).toBe('second');
   });
 });
 
@@ -846,18 +319,6 @@ describe('setTrialTitle', () => {
     s.getState().setTrialTitle('w1', 'Sprocket 7');
     expect(s.getState().trials[0]).toBe(before);
   });
-
-  it('round-trips through storage', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const first = makeStore({ storage });
-    first.getState().addTrial({ id: 'w1', instrumentName: 'T', config: {}, state: {}, view: VIEW });
-    first.getState().setTrialTitle('w1', 'Sprocket 7');
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(makeStore({ storage }).getState().trials[0]?.title).toBe('Sprocket 7');
-  });
 });
 
 describe('setTrialSectionCollapsed', () => {
@@ -877,31 +338,104 @@ describe('setTrialSectionCollapsed', () => {
     s.getState().setTrialSectionCollapsed('w1', 'settings', true);
     expect(s.getState().trials[0]).toBe(before);
   });
+});
 
-  it('round-trips through storage', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
-    const first = makeStore({ storage });
-    first.getState().addTrial({ id: 'w1', instrumentName: 'T', config: {}, state: {}, view: VIEW });
-    first.getState().setTrialSectionCollapsed('w1', 'settings/Shape', true);
-    vi.advanceTimersByTime(400);
-    vi.useRealTimers();
-
-    expect(makeStore({ storage }).getState().trials[0]?.collapsedSections).toEqual({
-      'settings/Shape': true,
-    });
-  });
-
-  it('hydrates a version-3 trial, which carries neither field', () => {
-    const storage = createMemoryAdapter();
-    writeDocument(storage, {
-      trials: [{ id: 'w1', instrumentName: 'T', config: {}, state: {}, view: VIEW }],
-      saves: [],
-      layout: {},
-      mode: 'auto',
+describe('setInstruments', () => {
+  const small: Instrument = {
+    name: 'Grid',
+    defaultConfig: () => ({ size: 10 }),
+    initialState: () => ({}),
+    render: () => null,
+  };
+  const other: Instrument = { ...small, name: 'Other', defaultConfig: () => ({ n: 1 }) };
+
+  function trial(id: string, instrumentName: string, config: unknown) {
+    return { id, instrumentName, config, state: {}, view: null };
+  }
+
+  it('fills a replaced instrument’s open trials from its new defaults', () => {
+    const store = createLabStore({ instruments: [small, other] });
+    store.getState().addTrial(trial('a', 'Grid', { size: 4 }));
+    store.getState().addTrial(trial('b', 'Other', { n: 2 }));
+    const untouched = store.getState().trials[1];
+
+    const grown: Instrument = { ...small, defaultConfig: () => ({ size: 10, color: 'red' }) };
+    store.getState().setInstruments([grown, other]);
+
+    expect(store.getState().trials[0]?.config).toEqual({ size: 4, color: 'red' });
+    expect(store.getState().trials[1]).toBe(untouched);
+    expect(store.getState().instruments).toEqual([grown, other]);
+  });
+
+  it('serializes an instrument added after the store was built', () => {
+    const store = createLabStore({ instruments: [small] });
+    const mapped: Instrument = {
+      ...small,
+      name: 'Mapped',
+      serialize: (s) => ({ seen: [...(s as { seen: Set<string> }).seen] }),
+    };
+    store.getState().setInstruments([small, mapped]);
+    store.getState().addTrial({
+      id: 'm',
+      instrumentName: 'Mapped',
+      config: { size: 10 },
+      state: { seen: new Set(['a']) },
+      view: null,
     });
-    const trial = makeStore({ storage }).getState().trials[0];
-    expect(trial?.title).toBeUndefined();
-    expect(trial?.collapsedSections).toBeUndefined();
+    store.getState().saveSnapshot('m', 'one');
+    expect(store.getState().savedSnapshots[0]?.state).toEqual({ seen: ['a'] });
+  });
+
+  it('is a no-op for the list it already holds', () => {
+    const list = [small];
+    const store = createLabStore({ instruments: list });
+    const before = store.getState();
+    store.getState().setInstruments(list);
+    expect(store.getState()).toBe(before);
+  });
+
+  const mapped: Instrument = {
+    ...small,
+    name: 'Mapped',
+    serialize: (s) => ({ seen: [...(s as { seen: Set<string> }).seen] }),
+  };
+  const mappedTrial = {
+    id: 'm',
+    instrumentName: 'Mapped',
+    config: { size: 10 },
+    state: { seen: new Set(['a']) },
+    view: null,
+  };
+
+  it('keeps the hooks of an instrument that leaves the list while its trials remain', () => {
+    const store = createLabStore({ instruments: [mapped] });
+    store.getState().addTrial(mappedTrial);
+    store.getState().setInstruments([]);
+    store.getState().saveSnapshot('m', 'one');
+    expect(store.getState().savedSnapshots[0]?.state).toEqual({ seen: ['a'] });
+  });
+
+  it('drops the serializer of an instrument replaced by one that declares none', () => {
+    const store = createLabStore({ instruments: [mapped] });
+    store.getState().addTrial(mappedTrial);
+    store.getState().setInstruments([{ ...small, name: 'Mapped' }]);
+    store.getState().saveSnapshot('m', 'one');
+    expect(store.getState().savedSnapshots[0]?.state).toEqual({ seen: new Set(['a']) });
+  });
+
+  it('changes neither hooks nor state when a new default config throws', () => {
+    const store = createLabStore({ instruments: [small, other] });
+    store.getState().addTrial(trial('a', 'Grid', { size: 4 }));
+    const before = store.getState();
+    const hooks = store.getState().instrumentHooks();
+    const broken: Instrument = {
+      ...small,
+      defaultConfig: () => {
+        throw new Error('boom');
+      },
+    };
+    expect(() => store.getState().setInstruments([broken, mapped])).toThrow('boom');
+    expect(store.getState()).toBe(before);
+    expect(store.getState().instrumentHooks()).toBe(hooks);
   });
 });