@weasel-js/labkit 0.1.0

package/src/state/helpers.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decodeUrlHash,
+  deserializeWorkspaces,
+  emptyUndoStack,
+  encodeUrlHash,
+  labStorageKey,
+  serializeWorkspaces,
+} from './helpers';
+import type { WorkspaceRecord } from './types';
+
+describe('labStorageKey', () => {
+  it('produces namespaced keys', () => {
+    expect(labStorageKey('my-lab', 'workspaces')).toBe('lk:my-lab:workspaces');
+    expect(labStorageKey('my-lab', 'saves')).toBe('lk:my-lab:saves');
+    expect(labStorageKey('my-lab', 'theme')).toBe('lk:my-lab:theme');
+  });
+});
+
+describe('encodeUrlHash / decodeUrlHash', () => {
+  it('round-trips a string', () => {
+    const original = JSON.stringify({ workspaces: '[]', saves: '[]' });
+    expect(decodeUrlHash(encodeUrlHash(original))).toBe(original);
+  });
+
+  it('returns null for an empty or invalid hash', () => {
+    expect(decodeUrlHash('')).toBeNull();
+    expect(decodeUrlHash('not-base64!!!')).toBeNull();
+  });
+});
+
+describe('emptyUndoStack', () => {
+  it('returns an empty stack', () => {
+    expect(emptyUndoStack()).toEqual({ past: [], future: [] });
+  });
+});
+
+describe('serializeWorkspaces / deserializeWorkspaces', () => {
+  const ws: WorkspaceRecord = {
+    id: 'w1',
+    instrumentName: 'Test',
+    config: { x: 1 },
+    state: { items: [] },
+    view: { zoom: 1, pan: { x: 0, y: 0 } },
+    undoStack: { past: [1, 2], future: [] },
+  };
+
+  it('round-trips workspace records', () => {
+    const serialized = serializeWorkspaces([ws], {});
+    const [result] = deserializeWorkspaces(serialized, {});
+    expect(result?.id).toBe('w1');
+    expect(result?.state).toEqual({ items: [] });
+  });
+
+  it('strips undoStack on serialization', () => {
+    const serialized = serializeWorkspaces([ws], {});
+    const parsed = JSON.parse(serialized) as unknown[];
+    expect((parsed[0] as Record<string, unknown>).undoStack).toBeUndefined();
+  });
+
+  it('restores emptyUndoStack after deserialization', () => {
+    const serialized = serializeWorkspaces([ws], {});
+    const [result] = deserializeWorkspaces(serialized, {});
+    expect(result?.undoStack).toEqual({ past: [], future: [] });
+  });
+
+  it('uses instrument.serialize / deserialize when provided', () => {
+    const serializers = {
+      Test: {
+        serialize: (s: unknown) => ({ compressed: true, data: s }),
+        deserialize: (d: unknown) => (d as { data: unknown }).data,
+      },
+    };
+    const serialized = serializeWorkspaces([ws], serializers);
+    const [result] = deserializeWorkspaces(serialized, serializers);
+    expect(result?.state).toEqual({ items: [] });
+  });
+
+  it('falls back to identity when instrumentName not in registry', () => {
+    const serialized = serializeWorkspaces([ws], {});
+    const [result] = deserializeWorkspaces(serialized, {});
+    expect(result?.state).toEqual({ items: [] });
+  });
+
+  it('returns empty array for malformed JSON', () => {
+    const result = deserializeWorkspaces('NOT JSON', {});
+    expect(result).toEqual([]);
+  });
+});

package/src/state/helpers.ts

@@ -0,0 +1,61 @@
+import type { InstrumentSerializers, UndoStack, WorkspaceRecord } from './types';
+
+export function labStorageKey(
+  storageKey: string,
+  bucket: 'workspaces' | 'saves' | 'theme',
+): string {
+  return `lk:${storageKey}:${bucket}`;
+}
+
+export function encodeUrlHash(value: string): string {
+  return btoa(encodeURIComponent(value));
+}
+
+export function decodeUrlHash(hash: string): string | null {
+  if (!hash) return null;
+  try {
+    return decodeURIComponent(atob(hash));
+  } catch {
+    return null;
+  }
+}
+
+export function emptyUndoStack(): UndoStack {
+  return { past: [], future: [] };
+}
+
+type SerializedRecord = Omit<WorkspaceRecord, 'undoStack'>;
+
+export function serializeWorkspaces(
+  workspaces: WorkspaceRecord[],
+  serializers: InstrumentSerializers,
+): string {
+  const records: SerializedRecord[] = workspaces.map(({ undoStack: _undo, ...w }) => {
+    const s = serializers[w.instrumentName];
+    return {
+      ...w,
+      state: s?.serialize ? s.serialize(w.state) : w.state,
+    };
+  });
+  return JSON.stringify(records);
+}
+
+export function deserializeWorkspaces(
+  raw: string,
+  deserializers: InstrumentSerializers,
+): WorkspaceRecord[] {
+  try {
+    const records = JSON.parse(raw) as SerializedRecord[];
+    return records.map((r) => {
+      const d = deserializers[r.instrumentName];
+      return {
+        ...r,
+        state: d?.deserialize ? d.deserialize(r.state) : r.state,
+        undoStack: emptyUndoStack(),
+      };
+    });
+  } catch {
+    console.warn('[labkit] deserializeWorkspaces: failed to parse, returning empty list');
+    return [];
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,40 @@
+export {
+  createMemoryAdapter,
+  localStorageAdapter,
+  noneAdapter,
+  sessionStorageAdapter,
+  urlHashAdapter,
+} from './adapters';
+export {
+  LabStoreContext,
+  LabStoreProvider,
+  useLabStore,
+  useWorkspaceId,
+  WorkspaceIdContext,
+  WorkspaceIdProvider,
+} from './context';
+export {
+  decodeUrlHash,
+  deserializeWorkspaces,
+  emptyUndoStack,
+  encodeUrlHash,
+  labStorageKey,
+  serializeWorkspaces,
+} from './helpers';
+export {
+  SingletonExperimentProvider,
+  type SingletonExperimentProviderProps,
+} from './SingletonExperiment';
+export type { LabStore, LabStoreActions } from './store';
+export { createLabStore } from './store';
+export type {
+  CreateLabStoreOptions,
+  ExperimentStateHandle,
+  InstrumentSerializers,
+  LabStoreState,
+  SavedSnapshot,
+  StorageAdapter,
+  UndoStack,
+  WorkspaceRecord,
+} from './types';
+export { useExperimentState } from './useExperimentState';

package/src/state/store.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMemoryAdapter } from './adapters';
+import { createLabStore } from './store';
+
+function makeStore(overrides?: Partial<Parameters<typeof createLabStore>[0]>) {
+  return createLabStore({
+    storageKey: 'test',
+    storage: createMemoryAdapter(),
+    ...overrides,
+  });
+}
+
+describe('createLabStore — initial state', () => {
+  it('starts with empty workspaces and saves', () => {
+    const s = makeStore();
+    expect(s.getState().workspaces).toEqual([]);
+    expect(s.getState().savedSnapshots).toEqual([]);
+  });
+
+  it('uses initialTheme when provided', () => {
+    const s = makeStore({ initialTheme: 'light' });
+    expect(s.getState().theme).toBe('light');
+  });
+
+  it('defaults theme to auto', () => {
+    const s = makeStore();
+    expect(s.getState().theme).toBe('auto');
+  });
+});
+
+describe('addWorkspace', () => {
+  it('adds a workspace with an empty undoStack', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'Test',
+      config: {},
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    expect(s.getState().workspaces).toHaveLength(1);
+    expect(s.getState().workspaces[0]?.undoStack).toEqual({ past: [], future: [] });
+  });
+});
+
+describe('removeWorkspace', () => {
+  it('removes by id', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().removeWorkspace('w1');
+    expect(s.getState().workspaces).toHaveLength(0);
+  });
+});
+
+describe('updateWorkspaceState', () => {
+  it('updates state with a plain value', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: { n: 0 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().updateWorkspaceState('w1', { n: 42 });
+    expect(s.getState().workspaces[0]?.state).toEqual({ n: 42 });
+  });
+
+  it('updates state with an updater function', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: { n: 1 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().updateWorkspaceState('w1', (prev: unknown) => ({
+      n: (prev as { n: number }).n + 1,
+    }));
+    expect((s.getState().workspaces[0]?.state as { n: number }).n).toBe(2);
+  });
+});
+
+describe('updateWorkspaceConfig', () => {
+  it('updates a single config key', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1, y: 2 },
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().updateWorkspaceConfig('w1', 'x' as never, 99 as never);
+    expect((s.getState().workspaces[0]?.config as { x: number }).x).toBe(99);
+    expect((s.getState().workspaces[0]?.config as { y: number }).y).toBe(2);
+  });
+});
+
+describe('setTheme', () => {
+  it('updates theme', () => {
+    const s = makeStore();
+    s.getState().setTheme('interstellar');
+    expect(s.getState().theme).toBe('interstellar');
+  });
+});
+
+describe('save/load/delete snapshots', () => {
+  it('saveSnapshot creates a snapshot', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1 },
+      state: { n: 5 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().saveSnapshot('w1', 'my save');
+    const snaps = s.getState().savedSnapshots;
+    expect(snaps).toHaveLength(1);
+    expect(snaps[0]?.name).toBe('my save');
+    expect(snaps[0]?.instrumentName).toBe('T');
+  });
+
+  it('loadSnapshot restores state and config', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1 },
+      state: { n: 5 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().saveSnapshot('w1', 'snap1');
+    s.getState().updateWorkspaceState('w1', { n: 99 });
+    const snapId = s.getState().savedSnapshots[0]?.id ?? '';
+    s.getState().loadSnapshot(snapId, 'w1');
+    expect((s.getState().workspaces[0]?.state as { n: number }).n).toBe(5);
+  });
+
+  it('loadSnapshot blocks cross-instrument load', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'A',
+      config: {},
+      state: { n: 1 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().saveSnapshot('w1', 'snap-a');
+    s.getState().setWorkspaceInstrument('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();
+  });
+
+  it('deleteSnapshot removes the snapshot', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      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);
+  });
+
+  it('listSnapshots returns newest first', () => {
+    const s = makeStore();
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    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 workspaces from storage on construction', () => {
+    vi.useFakeTimers();
+    const mem = createMemoryAdapter();
+    const seedStore = createLabStore({ storageKey: 'test', storage: mem });
+    seedStore.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: { n: 7 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    vi.advanceTimersByTime(500);
+    vi.useRealTimers();
+
+    const hydrated = createLabStore({ storageKey: 'test', storage: mem });
+    expect(hydrated.getState().workspaces).toHaveLength(1);
+    expect((hydrated.getState().workspaces[0]?.state as { n: number }).n).toBe(7);
+  });
+});
+
+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 });
+
+    s.getState().addWorkspace({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().updateWorkspaceState('w1', { n: 1 });
+    s.getState().updateWorkspaceState('w1', { n: 2 });
+    s.getState().updateWorkspaceState('w1', { n: 3 });
+
+    const writesBefore = writeSpy.mock.calls.length;
+    vi.advanceTimersByTime(400);
+    const writesAfter = writeSpy.mock.calls.length;
+
+    expect(writesAfter - writesBefore).toBe(3);
+    vi.useRealTimers();
+  });
+});

package/src/state/store.ts

@@ -0,0 +1,225 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import {
+  deserializeWorkspaces,
+  emptyUndoStack,
+  labStorageKey,
+  serializeWorkspaces,
+} from './helpers';
+import type {
+  CreateLabStoreOptions,
+  InstrumentSerializers,
+  LabStoreState,
+  SavedSnapshot,
+  WorkspaceRecord,
+} from './types';
+
+export interface LabStoreActions {
+  addWorkspace: (record: Omit<WorkspaceRecord, 'undoStack'>) => void;
+  removeWorkspace: (id: string) => void;
+  updateWorkspaceState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
+  updateWorkspaceConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
+  updateWorkspaceView: (id: string, view: WorkspaceRecord['view']) => void;
+  updateWorkspaceUndoStack: (
+    id: string,
+    next:
+      | WorkspaceRecord['undoStack']
+      | ((prev: WorkspaceRecord['undoStack']) => WorkspaceRecord['undoStack']),
+  ) => void;
+  setWorkspaceInstrument: (id: string, instrumentName: string) => void;
+  saveSnapshot: (workspaceId: string, name: string) => void;
+  loadSnapshot: (snapshotId: string, workspaceId: string) => void;
+  deleteSnapshot: (snapshotId: string) => void;
+  listSnapshots: (workspaceId?: string) => SavedSnapshot[];
+  setTheme: (theme: 'light' | 'interstellar' | 'auto') => void;
+}
+
+export type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
+  registerSerializers: (s: InstrumentSerializers) => void;
+};
+
+export function createLabStore(options: CreateLabStoreOptions): LabStore {
+  let serializers: InstrumentSerializers = {};
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const workspacesRaw = options.storage.read(labStorageKey(options.storageKey, 'workspaces'));
+  let hydratedWorkspaces: WorkspaceRecord[] = [];
+  if (workspacesRaw) {
+    hydratedWorkspaces = deserializeWorkspaces(workspacesRaw, serializers);
+  }
+
+  const savesRaw = options.storage.read(labStorageKey(options.storageKey, 'saves'));
+  let hydratedSnapshots: SavedSnapshot[] = [];
+  if (savesRaw) {
+    try {
+      hydratedSnapshots = JSON.parse(savesRaw) as SavedSnapshot[];
+    } catch {
+      console.warn('[labkit] failed to parse saved snapshots, starting empty');
+      hydratedSnapshots = [];
+    }
+  }
+
+  const themeRaw = options.storage.read(labStorageKey(options.storageKey, 'theme'));
+  let hydratedTheme: 'light' | 'interstellar' | 'auto';
+  if (themeRaw === 'light' || themeRaw === 'interstellar' || themeRaw === 'auto') {
+    hydratedTheme = themeRaw;
+  } else {
+    hydratedTheme = options.initialTheme ?? 'auto';
+  }
+
+  const store = createStore<LabStoreState & LabStoreActions>()((set, get) => ({
+    workspaces: hydratedWorkspaces,
+    savedSnapshots: hydratedSnapshots,
+    theme: hydratedTheme,
+
+    addWorkspace: (record) => {
+      set((s) => ({
+        workspaces: [...s.workspaces, { ...record, undoStack: emptyUndoStack() }],
+      }));
+      scheduleFlush();
+    },
+
+    removeWorkspace: (id) => {
+      set((s) => ({ workspaces: s.workspaces.filter((w) => w.id !== id) }));
+      scheduleFlush();
+    },
+
+    updateWorkspaceState: (id, next) => {
+      set((s) => ({
+        workspaces: s.workspaces.map((w) => {
+          if (w.id !== id) return w;
+          const nextState =
+            typeof next === 'function' ? (next as (prev: unknown) => unknown)(w.state) : next;
+          return { ...w, state: nextState };
+        }),
+      }));
+      scheduleFlush();
+    },
+
+    updateWorkspaceConfig: (id, key, value) => {
+      set((s) => ({
+        workspaces: s.workspaces.map((w) => {
+          if (w.id !== id) return w;
+          return {
+            ...w,
+            config: { ...(w.config as Record<string, unknown>), [key as string]: value },
+          };
+        }),
+      }));
+      scheduleFlush();
+    },
+
+    updateWorkspaceView: (id, view) => {
+      set((s) => ({
+        workspaces: s.workspaces.map((w) => (w.id === id ? { ...w, view } : w)),
+      }));
+      scheduleFlush();
+    },
+
+    updateWorkspaceUndoStack: (id, next) => {
+      set((s) => ({
+        workspaces: s.workspaces.map((w) => {
+          if (w.id !== id) return w;
+          const undoStack =
+            typeof next === 'function'
+              ? (next as (prev: WorkspaceRecord['undoStack']) => WorkspaceRecord['undoStack'])(
+                  w.undoStack,
+                )
+              : next;
+          return { ...w, undoStack };
+        }),
+      }));
+    },
+
+    setWorkspaceInstrument: (id, instrumentName) => {
+      set((s) => ({
+        workspaces: s.workspaces.map((w) => (w.id === id ? { ...w, instrumentName } : w)),
+      }));
+      scheduleFlush();
+    },
+
+    saveSnapshot: (workspaceId, name) => {
+      const workspace = get().workspaces.find((w) => w.id === workspaceId);
+      if (!workspace) return;
+      const reg = serializers[workspace.instrumentName];
+      const serializedState = reg?.serialize
+        ? reg.serialize(workspace.state)
+        : structuredClone(workspace.state);
+      const clonedConfig = structuredClone(workspace.config);
+      const lastAt = get().savedSnapshots.reduce((m, sn) => (sn.savedAt > m ? sn.savedAt : m), 0);
+      const savedAt = Math.max(Date.now(), lastAt + 1);
+      const snapshot: SavedSnapshot = {
+        id: crypto.randomUUID(),
+        name,
+        workspaceId,
+        instrumentName: workspace.instrumentName,
+        config: clonedConfig,
+        state: serializedState,
+        savedAt,
+      };
+      set((s) => ({ savedSnapshots: [...s.savedSnapshots, snapshot] }));
+      scheduleFlush();
+    },
+
+    loadSnapshot: (snapshotId, workspaceId) => {
+      const snapshot = get().savedSnapshots.find((sn) => sn.id === snapshotId);
+      if (!snapshot) return;
+      const workspace = get().workspaces.find((w) => w.id === workspaceId);
+      if (!workspace) return;
+      if (snapshot.instrumentName !== workspace.instrumentName) {
+        console.warn(
+          `[labkit] loadSnapshot: instrument mismatch (snapshot=${snapshot.instrumentName}, workspace=${workspace.instrumentName}); refusing to load`,
+        );
+        return;
+      }
+      const reg = serializers[snapshot.instrumentName];
+      const restoredState = reg?.deserialize ? reg.deserialize(snapshot.state) : snapshot.state;
+      set((s) => ({
+        workspaces: s.workspaces.map((w) =>
+          w.id === workspaceId ? { ...w, state: restoredState, config: snapshot.config } : w,
+        ),
+      }));
+      scheduleFlush();
+    },
+
+    deleteSnapshot: (snapshotId) => {
+      set((s) => ({
+        savedSnapshots: s.savedSnapshots.filter((sn) => sn.id !== snapshotId),
+      }));
+      scheduleFlush();
+    },
+
+    listSnapshots: (workspaceId) => {
+      const all = get().savedSnapshots;
+      const filtered = workspaceId ? all.filter((sn) => sn.workspaceId === workspaceId) : all;
+      return [...filtered].sort((a, b) => b.savedAt - a.savedAt);
+    },
+
+    setTheme: (theme) => {
+      set({ theme });
+      scheduleFlush();
+    },
+  }));
+
+  function scheduleFlush(): void {
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      const s = store.getState();
+      options.storage.write(
+        labStorageKey(options.storageKey, 'workspaces'),
+        serializeWorkspaces(s.workspaces, serializers),
+      );
+      options.storage.write(
+        labStorageKey(options.storageKey, 'saves'),
+        JSON.stringify(s.savedSnapshots),
+      );
+      options.storage.write(labStorageKey(options.storageKey, 'theme'), s.theme);
+      flushTimer = null;
+    }, 300);
+  }
+
+  return Object.assign(store, {
+    registerSerializers(s: InstrumentSerializers) {
+      serializers = s;
+    },
+  });
+}