@weasel-js/labkit 1.0.4 → 1.2.0

package/src/state/store.ts

@@ -1,38 +1,43 @@
 import { createStore, type StoreApi } from 'zustand/vanilla';
 import {
-  deserializeWorkspaces,
-  emptyUndoStack,
-  labStorageKey,
-  serializeWorkspaces,
-} from './helpers';
+  CURRENT_DOCUMENT_VERSION,
+  deleteLegacyKeys,
+  emptyDocument,
+  labDocumentKey,
+  MIGRATIONS,
+  normalizeDocument,
+  quarantineDocument,
+  readLegacyDocument,
+  runMigrations,
+} from './document';
+import { deserializeTrials, emptyUndoStack, serializeTrials } from './helpers';
 import type {
   CreateLabStoreOptions,
   InstrumentSerializers,
+  LabDocument,
   LabMode,
   LabStoreState,
   SavedSnapshot,
-  WorkspaceRecord,
+  TrialRecord,
 } from './types';
 
-/** Every mutation a lab store supports: managing workspaces, saving and
+/** Every mutation a lab store supports: managing trials, saving and
  *  restoring snapshots, and setting the color mode. */
 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: (
+  addTrial: (record: Omit<TrialRecord, 'undoStack'>) => void;
+  removeTrial: (id: string) => void;
+  updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
+  updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
+  updateTrialView: (id: string, view: unknown) => void;
+  updateTrialUndoStack: (
     id: string,
-    next:
-      | WorkspaceRecord['undoStack']
-      | ((prev: WorkspaceRecord['undoStack']) => WorkspaceRecord['undoStack']),
+    next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack']),
   ) => void;
-  setWorkspaceInstrument: (id: string, instrumentName: string) => void;
-  saveSnapshot: (workspaceId: string, name: string) => void;
-  loadSnapshot: (snapshotId: string, workspaceId: string) => void;
+  setTrialInstrument: (id: string, instrumentName: string) => void;
+  saveSnapshot: (trialId: string, name: string) => void;
+  loadSnapshot: (snapshotId: string, trialId: string) => void;
   deleteSnapshot: (snapshotId: string) => void;
-  listSnapshots: (workspaceId?: string) => SavedSnapshot[];
+  listSnapshots: (trialId?: string) => SavedSnapshot[];
   setMode: (mode: LabMode) => void;
   setLayout: (layout: Record<string, unknown>) => void;
 }
@@ -49,77 +54,54 @@ 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 layoutRaw = options.storage.read(labStorageKey(options.storageKey, 'layout'));
-  let hydratedLayout: Record<string, unknown> = {};
-  if (layoutRaw) {
-    try {
-      hydratedLayout = JSON.parse(layoutRaw) as Record<string, unknown>;
-    } catch {
-      console.warn('[labkit] failed to parse saved layout, starting empty');
-      hydratedLayout = {};
-    }
-  }
+  const hydration = hydrateDocument(options);
+  const hydrated = hydration.document;
+  const persistDisabled = hydration.persistDisabled;
+  // Cleared once the legacy keys are actually gone; see the flush.
+  let foldedFromLegacy = hydration.foldedFromLegacy;
 
-  const modeRaw = options.storage.read(labStorageKey(options.storageKey, 'theme'));
-  // `interstellar` was the dark mode's name back when it was a theme.
-  const stored = modeRaw === 'interstellar' ? 'dark' : modeRaw;
-  let hydratedMode: LabMode;
-  if (stored === 'light' || stored === 'dark' || stored === 'auto') {
-    hydratedMode = stored;
-  } else {
-    hydratedMode = options.initialMode ?? 'auto';
-  }
+  const hydratedTrials = deserializeTrials(hydrated.trials, serializers);
+  const hydratedSnapshots = hydrated.saves;
+  const hydratedLayout = hydrated.layout;
+  const hydratedMode = hydrated.mode;
 
   const store = createStore<LabStoreState & LabStoreActions>()((set, get) => ({
-    workspaces: hydratedWorkspaces,
+    trials: hydratedTrials,
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
     layout: hydratedLayout,
 
-    addWorkspace: (record) => {
+    addTrial: (record) => {
       set((s) => ({
-        workspaces: [...s.workspaces, { ...record, undoStack: emptyUndoStack() }],
+        trials: [...s.trials, { ...record, undoStack: emptyUndoStack() }],
       }));
       scheduleFlush();
     },
 
-    removeWorkspace: (id) => {
-      set((s) => ({ workspaces: s.workspaces.filter((w) => w.id !== id) }));
+    removeTrial: (id) => {
+      set((s) => ({ trials: s.trials.filter((w) => w.id !== id) }));
       scheduleFlush();
     },
 
-    updateWorkspaceState: (id, next) => {
+    updateTrialState: (id, next) => {
       set((s) => ({
-        workspaces: s.workspaces.map((w) => {
+        trials: s.trials.map((w) => {
           if (w.id !== id) return w;
           const nextState =
             typeof next === 'function' ? (next as (prev: unknown) => unknown)(w.state) : next;
+          // An updater that returns its input means "nothing changed", and must not
+          // cost a new record: the trial re-renders on record identity, so
+          // allocating here turns the standard React bail-out into a render loop.
+          if (Object.is(nextState, w.state)) return w;
           return { ...w, state: nextState };
         }),
       }));
       scheduleFlush();
     },
 
-    updateWorkspaceConfig: (id, key, value) => {
+    updateTrialConfig: (id, key, value) => {
       set((s) => ({
-        workspaces: s.workspaces.map((w) => {
+        trials: s.trials.map((w) => {
           if (w.id !== id) return w;
           return {
             ...w,
@@ -130,50 +112,50 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
-    updateWorkspaceView: (id, view) => {
+    updateTrialView: (id, view) => {
       set((s) => ({
-        workspaces: s.workspaces.map((w) => (w.id === id ? { ...w, view } : w)),
+        trials: s.trials.map((w) =>
+          w.id === id && !Object.is(view, w.view) ? { ...w, view } : w,
+        ),
       }));
       scheduleFlush();
     },
 
-    updateWorkspaceUndoStack: (id, next) => {
+    updateTrialUndoStack: (id, next) => {
       set((s) => ({
-        workspaces: s.workspaces.map((w) => {
+        trials: s.trials.map((w) => {
           if (w.id !== id) return w;
           const undoStack =
             typeof next === 'function'
-              ? (next as (prev: WorkspaceRecord['undoStack']) => WorkspaceRecord['undoStack'])(
-                  w.undoStack,
-                )
+              ? (next as (prev: TrialRecord['undoStack']) => TrialRecord['undoStack'])(w.undoStack)
               : next;
           return { ...w, undoStack };
         }),
       }));
     },
 
-    setWorkspaceInstrument: (id, instrumentName) => {
+    setTrialInstrument: (id, instrumentName) => {
       set((s) => ({
-        workspaces: s.workspaces.map((w) => (w.id === id ? { ...w, instrumentName } : w)),
+        trials: s.trials.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];
+    saveSnapshot: (trialId, name) => {
+      const trial = get().trials.find((w) => w.id === trialId);
+      if (!trial) return;
+      const reg = serializers[trial.instrumentName];
       const serializedState = reg?.serialize
-        ? reg.serialize(workspace.state)
-        : structuredClone(workspace.state);
-      const clonedConfig = structuredClone(workspace.config);
+        ? reg.serialize(trial.state)
+        : structuredClone(trial.state);
+      const clonedConfig = structuredClone(trial.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,
+        trialId,
+        instrumentName: trial.instrumentName,
         config: clonedConfig,
         state: serializedState,
         savedAt,
@@ -182,22 +164,22 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
-    loadSnapshot: (snapshotId, workspaceId) => {
+    loadSnapshot: (snapshotId, trialId) => {
       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) {
+      const trial = get().trials.find((w) => w.id === trialId);
+      if (!trial) return;
+      if (snapshot.instrumentName !== trial.instrumentName) {
         console.warn(
-          `[labkit] loadSnapshot: instrument mismatch (snapshot=${snapshot.instrumentName}, workspace=${workspace.instrumentName}); refusing to load`,
+          `[labkit] loadSnapshot: instrument mismatch (snapshot=${snapshot.instrumentName}, trial=${trial.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,
+        trials: s.trials.map((w) =>
+          w.id === trialId ? { ...w, state: restoredState, config: snapshot.config } : w,
         ),
       }));
       scheduleFlush();
@@ -210,9 +192,9 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
-    listSnapshots: (workspaceId) => {
+    listSnapshots: (trialId) => {
       const all = get().savedSnapshots;
-      const filtered = workspaceId ? all.filter((sn) => sn.workspaceId === workspaceId) : all;
+      const filtered = trialId ? all.filter((sn) => sn.trialId === trialId) : all;
       return [...filtered].sort((a, b) => b.savedAt - a.savedAt);
     },
 
@@ -228,26 +210,107 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
   }));
 
   function scheduleFlush(): void {
+    if (persistDisabled) return;
     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.mode);
-      options.storage.write(labStorageKey(options.storageKey, 'layout'), JSON.stringify(s.layout));
+      const document: LabDocument = {
+        version: CURRENT_DOCUMENT_VERSION,
+        trials: serializeTrials(s.trials, serializers),
+        saves: s.savedSnapshots,
+        layout: s.layout,
+        mode: s.mode,
+      };
+      const serialized = JSON.stringify(document);
+      options.storage.write(labDocumentKey(options.storageKey), serialized);
+      if (foldedFromLegacy && deleteLegacyKeys(options.storage, options.storageKey, serialized)) {
+        foldedFromLegacy = false;
+      }
       flushTimer = null;
     }, 300);
   }
 
+  // A lab opened and closed without a single mutation still completes its
+  // fold; the flush is what removes the legacy keys.
+  if (foldedFromLegacy) scheduleFlush();
+
   return Object.assign(store, {
     registerSerializers(s: InstrumentSerializers) {
       serializers = s;
     },
   });
 }
+
+interface HydrateResult {
+  document: LabDocument;
+  /** True when flushing would destroy the only copy of something: a document
+   *  newer than this code understands, or an unusable one whose quarantine
+   *  copy did not land. */
+  persistDisabled: boolean;
+  foldedFromLegacy: boolean;
+}
+
+/** Copy an unusable document aside, and report whether the store may go on
+ *  persisting. A failed quarantine write means the copy in storage is the only
+ *  one there is, so the store must not overwrite it. */
+function setAside(
+  options: CreateLabStoreOptions,
+  raw: string,
+  why: string,
+  error?: unknown,
+): boolean {
+  const quarantined = quarantineDocument(options.storage, options.storageKey, raw);
+  const message = quarantined
+    ? `[labkit] ${why}; quarantined it and starting empty`
+    : `[labkit] ${why} and could not be quarantined; leaving it in place and not persisting`;
+  if (error === undefined) console.warn(message);
+  else console.warn(message, error);
+  return quarantined;
+}
+
+function hydrateDocument(options: CreateLabStoreOptions): HydrateResult {
+  const fallback = emptyDocument(options.initialMode ?? 'auto');
+  const raw = options.storage.read(labDocumentKey(options.storageKey));
+
+  let parsed: Record<string, unknown> | null = null;
+  if (raw !== null) {
+    try {
+      parsed = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      const persistDisabled = !setAside(options, raw, 'lab document is unparseable');
+      return { document: fallback, persistDisabled, foldedFromLegacy: false };
+    }
+  } else {
+    parsed = readLegacyDocument(options.storage, options.storageKey, options.initialMode ?? 'auto');
+  }
+
+  if (parsed === null) {
+    return { document: fallback, persistDisabled: false, foldedFromLegacy: false };
+  }
+
+  const foldedFromLegacy = raw === null;
+  const outcome = runMigrations(parsed, MIGRATIONS, CURRENT_DOCUMENT_VERSION);
+
+  if (!outcome.ok) {
+    if (outcome.reason === 'future') {
+      console.warn(
+        '[labkit] lab document is from a newer version of labkit; starting empty and leaving it alone',
+      );
+      return { document: fallback, persistDisabled: true, foldedFromLegacy: false };
+    }
+    const stored = JSON.stringify(parsed);
+    const persistDisabled = !setAside(
+      options,
+      stored,
+      'lab document failed to migrate',
+      outcome.error,
+    );
+    return { document: fallback, persistDisabled, foldedFromLegacy: false };
+  }
+
+  return {
+    document: normalizeDocument(outcome.doc, options.initialMode ?? 'auto'),
+    persistDisabled: false,
+    foldedFromLegacy,
+  };
+}

package/src/state/types.ts

@@ -1,27 +1,29 @@
-/** A workspace's undo history, as snapshots of its state either side of the
+/** A trial's undo history, as snapshots of its state either side of the
  *  present. */
 export interface UndoStack {
   past: unknown[];
   future: unknown[];
 }
 
-/** One workspace as the store holds it: which instrument it runs, that
+/** One trial as the store holds it: which instrument it runs, that
  *  instrument's config and state, the camera, and the undo history. */
-export interface WorkspaceRecord<TS = unknown, TC = unknown> {
+export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
   id: string;
   instrumentName: string;
   config: TC;
   state: TS;
-  view: { zoom: number; pan: { x: number; y: number } };
+  /** Opaque to labkit: persisted, restored on Reset and handed to the instrument,
+   *  but never read into. A 3D lab puts an orbit here and keeps all three. */
+  view: TV;
   undoStack: UndoStack;
 }
 
-/** A named, saved copy of a workspace's config and state, restorable into any
- *  workspace running the same instrument. */
+/** A named, saved copy of a trial's config and state, restorable into any
+ *  trial running the same instrument. */
 export interface SavedSnapshot {
   id: string;
   name: string;
-  workspaceId: string;
+  trialId: string;
   instrumentName: string;
   config: unknown;
   state: unknown;
@@ -31,14 +33,14 @@ export interface SavedSnapshot {
 /** `auto` follows the OS; the other two are an explicit choice. */
 export type LabMode = 'auto' | 'light' | 'dark';
 
-/** Everything a lab persists: its workspaces, its saved snapshots, and the
+/** Everything a lab persists: its trials, its saved snapshots, and the
  *  chosen color mode. */
 export interface LabStoreState {
-  workspaces: WorkspaceRecord[];
+  trials: TrialRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
-  /** Per-workspace tile extents, keyed by workspace id. Opaque here — the
-   *  shape belongs to whatever lays the workspaces out. */
+  /** Per-trial tile extents, keyed by trial id. Opaque here — the
+   *  shape belongs to whatever lays the trials out. */
   layout: Record<string, unknown>;
 }
 
@@ -51,9 +53,9 @@ export interface StorageAdapter {
   delete?(key: string): void;
 }
 
-/** What `useExperimentState` hands an instrument: its state and config, with
+/** What `useTrialState` hands an instrument: its state and config, with
  *  a setter for each. */
-export interface ExperimentStateHandle<TS, TC> {
+export interface TrialStateHandle<TS, TC> {
   state: TS;
   setState: (next: TS | ((prev: TS) => TS)) => void;
   config: TC;
@@ -74,3 +76,20 @@ export type InstrumentSerializers = Record<
   string,
   { serialize?: (state: unknown) => unknown; deserialize?: (data: unknown) => unknown } | undefined
 >;
+
+/** A trial as it is persisted: everything but the undo history, which is
+ *  session-only. */
+export type SerializedTrial = Omit<TrialRecord, 'undoStack'>;
+
+/** Everything a lab persists, under one key, at a known version. */
+export interface LabDocument {
+  version: number;
+  trials: SerializedTrial[];
+  saves: SavedSnapshot[];
+  layout: Record<string, unknown>;
+  mode: LabMode;
+}
+
+/** Migrates a document one version forward. Index `i` in the chain takes a
+ *  version-`i` document to version `i + 1`. */
+export type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;

package/src/state/{useExperimentState.test.tsx → useTrialState.test.tsx}

@@ -2,17 +2,17 @@ import { act, renderHook } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { describe, expect, it } from 'vitest';
 import { createMemoryAdapter } from './adapters';
-import { LabStoreProvider, WorkspaceIdProvider } from './context';
+import { LabStoreProvider, TrialIdProvider } from './context';
 import { createLabStore } from './store';
-import { useExperimentState } from './useExperimentState';
+import { useTrialState } from './useTrialState';
 
 type TestState = { count: number };
 type TestConfig = { step: number };
 
-function makeWrapper(workspaceId: string) {
+function makeWrapper(trialId: string) {
   const store = createLabStore({ storageKey: 'test', storage: createMemoryAdapter() });
-  store.getState().addWorkspace({
-    id: workspaceId,
+  store.getState().addTrial({
+    id: trialId,
     instrumentName: 'Counter',
     config: { step: 1 } satisfies TestConfig,
     state: { count: 0 } satisfies TestState,
@@ -23,51 +23,51 @@ function makeWrapper(workspaceId: string) {
     store,
     wrapper: ({ children }: { children: ReactNode }) => (
       <LabStoreProvider store={store}>
-        <WorkspaceIdProvider workspaceId={workspaceId}>{children}</WorkspaceIdProvider>
+        <TrialIdProvider trialId={trialId}>{children}</TrialIdProvider>
       </LabStoreProvider>
     ),
   };
 }
 
-describe('useExperimentState', () => {
+describe('useTrialState', () => {
   it('returns the initial state and config', () => {
     const { wrapper } = makeWrapper('w1');
-    const { result } = renderHook(() => useExperimentState<TestState, TestConfig>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<TestState, TestConfig>(), { wrapper });
     expect(result.current.state.count).toBe(0);
     expect(result.current.config.step).toBe(1);
   });
 
   it('setState (plain value) updates the store', () => {
     const { wrapper } = makeWrapper('w1');
-    const { result } = renderHook(() => useExperimentState<TestState, TestConfig>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<TestState, TestConfig>(), { wrapper });
     act(() => result.current.setState({ count: 42 }));
     expect(result.current.state.count).toBe(42);
   });
 
   it('setState (updater) updates the store', () => {
     const { wrapper } = makeWrapper('w1');
-    const { result } = renderHook(() => useExperimentState<TestState, TestConfig>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<TestState, TestConfig>(), { wrapper });
     act(() => result.current.setState((prev) => ({ count: prev.count + 10 })));
     expect(result.current.state.count).toBe(10);
   });
 
   it('setConfig updates a config key', () => {
     const { wrapper } = makeWrapper('w1');
-    const { result } = renderHook(() => useExperimentState<TestState, TestConfig>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<TestState, TestConfig>(), { wrapper });
     act(() => result.current.setConfig('step', 5));
     expect(result.current.config.step).toBe(5);
   });
 
-  it('sibling workspace does not re-render on unrelated workspace changes', () => {
+  it('sibling trial does not re-render on unrelated trial changes', () => {
     const store = createLabStore({ storageKey: 'test', storage: createMemoryAdapter() });
-    store.getState().addWorkspace({
+    store.getState().addTrial({
       id: 'w1',
       instrumentName: 'T',
       config: {},
       state: { n: 0 },
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    store.getState().addWorkspace({
+    store.getState().addTrial({
       id: 'w2',
       instrumentName: 'T',
       config: {},
@@ -79,24 +79,24 @@ describe('useExperimentState', () => {
 
     const wrapper = ({ children }: { children: ReactNode }) => (
       <LabStoreProvider store={store}>
-        <WorkspaceIdProvider workspaceId="w2">{children}</WorkspaceIdProvider>
+        <TrialIdProvider trialId="w2">{children}</TrialIdProvider>
       </LabStoreProvider>
     );
 
     renderHook(
       () => {
         w2RenderCount++;
-        return useExperimentState();
+        return useTrialState();
       },
       { wrapper },
     );
 
     const countBefore = w2RenderCount;
-    act(() => store.getState().updateWorkspaceState('w1', { n: 99 }));
+    act(() => store.getState().updateTrialState('w1', { n: 99 }));
     expect(w2RenderCount).toBe(countBefore);
   });
 
   it('throws when used outside LabStoreProvider', () => {
-    expect(() => renderHook(() => useExperimentState())).toThrow('[labkit]');
+    expect(() => renderHook(() => useTrialState())).toThrow('[labkit]');
   });
 });

package/src/state/useTrialState.ts

@@ -0,0 +1,29 @@
+import { useContext } from 'react';
+import { useStore } from 'zustand/react';
+import { LabStoreContext, TrialIdContext } from './context';
+import type { TrialStateHandle } from './types';
+
+/** An instrument's own state and config, plus setters. Reads the surrounding
+ *  trial id, so an instrument never has to know which trial it is
+ *  running in. Throws outside a lab store and trial. */
+export function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS, TC> {
+  const ctx = useContext(LabStoreContext);
+  if (!ctx) throw new Error('[labkit] useTrialState must be used inside <LabStoreProvider>');
+
+  const trialId = useContext(TrialIdContext);
+  if (!trialId) throw new Error('[labkit] useTrialState must be used inside <TrialIdProvider>');
+
+  const record = useStore(ctx.store, (s) => s.trials.find((w) => w.id === trialId));
+
+  if (!record) throw new Error(`[labkit] No trial found with id "${trialId}"`);
+
+  const updateTrialState = useStore(ctx.store, (s) => s.updateTrialState);
+  const updateTrialConfig = useStore(ctx.store, (s) => s.updateTrialConfig);
+
+  return {
+    state: record.state as TS,
+    config: record.config as TC,
+    setState: (next) => updateTrialState(trialId, next as Parameters<typeof updateTrialState>[1]),
+    setConfig: (key, value) => updateTrialConfig(trialId, key as never, value as never),
+  };
+}