@weasel-js/labkit 1.0.3 → 1.1.0

package/src/state/helpers.test.ts

@@ -1,13 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import {
   decodeUrlHash,
-  deserializeWorkspaces,
+  deserializeTrials,
   emptyUndoStack,
   encodeUrlHash,
   labStorageKey,
-  serializeWorkspaces,
+  serializeTrials,
 } from './helpers';
-import type { WorkspaceRecord } from './types';
 
 describe('labStorageKey', () => {
   it('produces namespaced keys', () => {
@@ -19,7 +18,7 @@ describe('labStorageKey', () => {
 
 describe('encodeUrlHash / decodeUrlHash', () => {
   it('round-trips a string', () => {
-    const original = JSON.stringify({ workspaces: '[]', saves: '[]' });
+    const original = JSON.stringify({ trials: '[]', saves: '[]' });
     expect(decodeUrlHash(encodeUrlHash(original))).toBe(original);
   });
 
@@ -35,55 +34,84 @@ describe('emptyUndoStack', () => {
   });
 });
 
-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();
+describe('serializeTrials', () => {
+  it('returns records with the undo stack dropped', () => {
+    const records = serializeTrials(
+      [
+        {
+          id: 'w1',
+          instrumentName: 'Test',
+          config: { a: 1 },
+          state: { b: 2 },
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+          undoStack: { past: [{ b: 1 }], future: [] },
+        },
+      ],
+      {},
+    );
+    expect(records).toEqual([
+      {
+        id: 'w1',
+        instrumentName: 'Test',
+        config: { a: 1 },
+        state: { b: 2 },
+        view: { zoom: 1, pan: { x: 0, y: 0 } },
+      },
+    ]);
   });
 
-  it('restores emptyUndoStack after deserialization', () => {
-    const serialized = serializeWorkspaces([ws], {});
-    const [result] = deserializeWorkspaces(serialized, {});
-    expect(result?.undoStack).toEqual({ past: [], future: [] });
+  it('runs the instrument serializer over the state', () => {
+    const records = serializeTrials(
+      [
+        {
+          id: 'w1',
+          instrumentName: 'Test',
+          config: {},
+          state: { n: 2 },
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+          undoStack: { past: [], future: [] },
+        },
+      ],
+      { Test: { serialize: (s) => ({ doubled: (s as { n: number }).n * 2 }) } },
+    );
+    expect(records[0].state).toEqual({ doubled: 4 });
   });
+});
 
-  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: [] });
+describe('deserializeTrials', () => {
+  it('rebuilds records with an empty undo stack', () => {
+    const out = deserializeTrials(
+      [
+        {
+          id: 'w1',
+          instrumentName: 'Test',
+          config: {},
+          state: { n: 1 },
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+        },
+      ],
+      {},
+    );
+    expect(out[0].undoStack).toEqual({ past: [], future: [] });
   });
 
-  it('falls back to identity when instrumentName not in registry', () => {
-    const serialized = serializeWorkspaces([ws], {});
-    const [result] = deserializeWorkspaces(serialized, {});
-    expect(result?.state).toEqual({ items: [] });
+  it('runs the instrument deserializer over the state', () => {
+    const out = deserializeTrials(
+      [
+        {
+          id: 'w1',
+          instrumentName: 'Test',
+          config: {},
+          state: { doubled: 4 },
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+        },
+      ],
+      { Test: { deserialize: (d) => ({ n: (d as { doubled: number }).doubled / 2 }) } },
+    );
+    expect(out[0].state).toEqual({ n: 2 });
   });
 
-  it('returns empty array for malformed JSON', () => {
-    const result = deserializeWorkspaces('NOT JSON', {});
-    expect(result).toEqual([]);
+  it('returns an empty list when given something that is not an array', () => {
+    expect(deserializeTrials(undefined as never, {})).toEqual([]);
   });
 });

package/src/state/helpers.ts

@@ -1,10 +1,10 @@
-import type { InstrumentSerializers, UndoStack, WorkspaceRecord } from './types';
+import type { InstrumentSerializers, SerializedTrial, TrialRecord, UndoStack } from './types';
 
-/** The storage key a lab writes one of its three buckets under. Namespaced by
+/** The storage key a lab writes one of its buckets under. Namespaced by
  *  `storageKey` so two labs sharing an origin do not collide. */
 export function labStorageKey(
   storageKey: string,
-  bucket: 'workspaces' | 'saves' | 'theme',
+  bucket: 'workspaces' | 'saves' | 'theme' | 'layout',
 ): string {
   return `lk:${storageKey}:${bucket}`;
 }
@@ -30,44 +30,36 @@ export function emptyUndoStack(): UndoStack {
   return { past: [], future: [] };
 }
 
-type SerializedRecord = Omit<WorkspaceRecord, 'undoStack'>;
-
-/** Serialize workspaces for storage, running each instrument's own serializer
+/** Serialize trials for storage, running each instrument's own serializer
  *  over its state. Undo history is deliberately dropped — it does not survive
  *  a reload. */
-export function serializeWorkspaces(
-  workspaces: WorkspaceRecord[],
+export function serializeTrials(
+  trials: TrialRecord[],
   serializers: InstrumentSerializers,
-): string {
-  const records: SerializedRecord[] = workspaces.map(({ undoStack: _undo, ...w }) => {
+): SerializedTrial[] {
+  return trials.map(({ undoStack: _undo, ...w }) => {
     const s = serializers[w.instrumentName];
-    return {
-      ...w,
-      state: s?.serialize ? s.serialize(w.state) : w.state,
-    };
+    return { ...w, state: s?.serialize ? s.serialize(w.state) : w.state };
   });
-  return JSON.stringify(records);
 }
 
-/** Rebuild workspaces from storage, running each instrument's deserializer
+/** Rebuild trials from storage, running each instrument's deserializer
  *  over its state and starting each with an empty undo history. Returns an
  *  empty list rather than throwing on malformed input. */
-export function deserializeWorkspaces(
-  raw: string,
+export function deserializeTrials(
+  records: SerializedTrial[],
   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');
+): TrialRecord[] {
+  if (!Array.isArray(records)) {
+    console.warn('[labkit] deserializeTrials: not an array, returning empty list');
     return [];
   }
+  return records.map((r) => {
+    const d = deserializers[r.instrumentName];
+    return {
+      ...r,
+      state: d?.deserialize ? d.deserialize(r.state) : r.state,
+      undoStack: emptyUndoStack(),
+    };
+  });
 }

package/src/state/index.ts

@@ -8,18 +8,23 @@ export {
 export {
   LabStoreContext,
   LabStoreProvider,
+  TrialIdContext,
+  TrialIdProvider,
   useLabStore,
-  useWorkspaceId,
-  WorkspaceIdContext,
-  WorkspaceIdProvider,
+  useTrialId,
 } from './context';
+export {
+  CURRENT_DOCUMENT_VERSION,
+  labDocumentKey,
+  quarantineKey,
+} from './document';
 export {
   decodeUrlHash,
-  deserializeWorkspaces,
+  deserializeTrials,
   emptyUndoStack,
   encodeUrlHash,
   labStorageKey,
-  serializeWorkspaces,
+  serializeTrials,
 } from './helpers';
 export {
   SingletonExperimentProvider,
@@ -29,12 +34,15 @@ export type { LabStore, LabStoreActions } from './store';
 export { createLabStore } from './store';
 export type {
   CreateLabStoreOptions,
-  ExperimentStateHandle,
   InstrumentSerializers,
+  LabDocument,
   LabStoreState,
+  Migration,
   SavedSnapshot,
+  SerializedTrial,
   StorageAdapter,
+  TrialRecord,
+  TrialStateHandle,
   UndoStack,
-  WorkspaceRecord,
 } from './types';
-export { useExperimentState } from './useExperimentState';
+export { useTrialState } from './useTrialState';