@weasel-js/labkit 1.4.3 → 1.5.0

package/src/state/store.ts

@@ -1,23 +1,17 @@
 import { createStore, type StoreApi } from 'zustand/vanilla';
 import { fillConfigDefaults, withValueAtPath } from '../config/path';
-import {
-  CURRENT_DOCUMENT_VERSION,
-  deleteLegacyKeys,
-  emptyDocument,
-  labDocumentKey,
-  MIGRATIONS,
-  normalizeDocument,
-  quarantineDocument,
-  readLegacyDocument,
-  runMigrations,
-} from './document';
-import { deserializeTrials, emptyUndoStack, serializeTrials } from './helpers';
+import { configDefaultsOf, configMigrationsOf, serializersOf } from '../instrument/serializers';
+import type { InstrumentList } from '../instrument/types';
+import { emptyDocument } from './document';
+import { deserializeTrials, emptyUndoStack, newId } from './helpers';
 import type {
   CreateLabStoreOptions,
-  LabDocument,
+  InstrumentHooks,
+  InstrumentSerializers,
   LabMode,
   LabStoreState,
   SavedSnapshot,
+  SerializedTrial,
   TrialRecord,
 } from './types';
 import {
@@ -59,54 +53,44 @@ export interface LabStoreActions {
   undockPanel: (trialId: string, sectionId: string, as?: UndockedPanel['as']) => void;
   /** Put one section back, or — with no `sectionId` — every panel the trial owns. */
   dockPanel: (trialId: string, sectionId?: string) => void;
+  /** Replace the lab's instruments. Trials and saves of an instrument that is
+   *  new or a different object are brought up to date against it in the same
+   *  write; every other trial keeps its object. */
+  setInstruments: (instruments: InstrumentList) => void;
+  /** The per-instrument hooks in force now. Read them at use; never keep them. */
+  instrumentHooks: () => InstrumentHooks;
 }
 
 /** A lab's store: its state and its actions. How each instrument's state is
- *  serialized comes in through `CreateLabStoreOptions.serializers`. */
+ *  serialized comes in through `CreateLabStoreOptions.instruments`. */
 export type LabStore = StoreApi<LabStoreState & LabStoreActions>;
 
-/** Build a lab store, hydrating from storage if anything was saved under the
- *  same key. Writes back are debounced. */
-export function createLabStore(options: CreateLabStoreOptions): LabStore {
-  const serializers = options.serializers ?? {};
-  let flushTimer: ReturnType<typeof setTimeout> | null = null;
-
-  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 configDefaults = options.configDefaults ?? {};
-  const filled = (instrumentName: string, config: unknown): unknown => {
-    const defaults = configDefaults[instrumentName];
-    return defaults ? fillConfigDefaults(config, defaults()) : config;
-  };
-
-  const hydratedTrials = deserializeTrials(
-    hydrated.trials.map((t) => ({ ...t, config: filled(t.instrumentName, t.config) })),
-    serializers,
-  );
-  const hydratedSnapshots = hydrated.saves.map((sn) => ({
-    ...sn,
-    config: filled(sn.instrumentName, sn.config),
-  }));
-  const hydratedLayout = hydrated.layout;
-  const hydratedMode = hydrated.mode;
+/** Build a lab store holding `initial`, or an empty lab. It knows nothing
+ *  about storage; `openLabStore` reads a stored lab and binds one of these to
+ *  it. */
+export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
+  let hooks: InstrumentHooks = options.instruments
+    ? hooksOf(options.instruments)
+    : {
+        serializers: options.serializers ?? {},
+        configDefaults: options.configDefaults ?? {},
+        configMigrations: options.configMigrations ?? {},
+      };
+  const initial = options.initial ?? emptyDocument(options.initialMode ?? 'auto');
 
   const store = createStore<LabStoreState & LabStoreActions>()((set, get) => ({
-    trials: hydratedTrials,
-    savedSnapshots: hydratedSnapshots,
-    mode: hydratedMode,
-    layout: hydratedLayout,
-    undockedPanels: hydrated.undockedPanels,
+    trials: hydrateTrials(initial.trials, hooks.serializers, hooks),
+    savedSnapshots: hydrateSnapshots(initial.saves, hooks),
+    mode: initial.mode,
+    layout: initial.layout,
+    undockedPanels: initial.undockedPanels,
     activeToolId: null,
+    instruments: options.instruments ?? null,
 
     addTrial: (record) => {
       set((s) => ({
         trials: [...s.trials, { ...record, undoStack: emptyUndoStack() }],
       }));
-      scheduleFlush();
     },
 
     removeTrial: (id) => {
@@ -114,7 +98,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         trials: s.trials.filter((w) => w.id !== id),
         undockedPanels: dockPanelIn(s.undockedPanels, id),
       }));
-      scheduleFlush();
     },
 
     updateTrialState: (id, next) => {
@@ -130,7 +113,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           return { ...w, state: nextState };
         }),
       }));
-      scheduleFlush();
     },
 
     updateTrialConfig: (id, path, value) => {
@@ -139,14 +121,12 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           w.id === id ? { ...w, config: withValueAtPath(w.config, path, value) } : w,
         ),
       }));
-      scheduleFlush();
     },
 
     updateTrialView: (id, view) => {
       set((s) => ({
         trials: s.trials.map((w) => (w.id === id && !Object.is(view, w.view) ? { ...w, view } : w)),
       }));
-      scheduleFlush();
     },
 
     updateTrialSidebarWidth: (id, width) => {
@@ -155,7 +135,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           w.id === id && w.sidebarWidth !== width ? { ...w, sidebarWidth: width } : w,
         ),
       }));
-      scheduleFlush();
     },
 
     setTrialTitle: (id, title) => {
@@ -167,7 +146,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           return { ...w, title: next };
         }),
       }));
-      scheduleFlush();
     },
 
     setTrialSectionCollapsed: (id, key, collapsed) => {
@@ -178,7 +156,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           return { ...w, collapsedSections: { ...w.collapsedSections, [key]: collapsed } };
         }),
       }));
-      scheduleFlush();
     },
 
     updateTrialAnnotations: (id, doc) => {
@@ -187,7 +164,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           w.id === id && !Object.is(doc, w.annotations) ? { ...w, annotations: doc } : w,
         ),
       }));
-      scheduleFlush();
     },
 
     updateTrialUndoStack: (id, next) => {
@@ -207,13 +183,12 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       set((s) => ({
         trials: s.trials.map((w) => (w.id === id ? { ...w, instrumentName } : w)),
       }));
-      scheduleFlush();
     },
 
     saveSnapshot: (trialId, name) => {
       const trial = get().trials.find((w) => w.id === trialId);
       if (!trial) return;
-      const reg = serializers[trial.instrumentName];
+      const reg = hooks.serializers[trial.instrumentName];
       const serializedState = reg?.serialize
         ? reg.serialize(trial.state)
         : structuredClone(trial.state);
@@ -221,7 +196,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       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(),
+        id: newId(),
         name,
         trialId,
         instrumentName: trial.instrumentName,
@@ -230,7 +205,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         savedAt,
       };
       set((s) => ({ savedSnapshots: [...s.savedSnapshots, snapshot] }));
-      scheduleFlush();
     },
 
     loadSnapshot: (snapshotId, trialId) => {
@@ -244,7 +218,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         );
         return;
       }
-      const reg = serializers[snapshot.instrumentName];
+      const reg = hooks.serializers[snapshot.instrumentName];
       const restoredState = reg?.deserialize
         ? reg.deserialize(snapshot.state, snapshot.config)
         : snapshot.state;
@@ -253,14 +227,12 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
           w.id === trialId ? { ...w, state: restoredState, config: snapshot.config } : w,
         ),
       }));
-      scheduleFlush();
     },
 
     deleteSnapshot: (snapshotId) => {
       set((s) => ({
         savedSnapshots: s.savedSnapshots.filter((sn) => sn.id !== snapshotId),
       }));
-      scheduleFlush();
     },
 
     listSnapshots: (trialId) => {
@@ -271,7 +243,6 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
 
     setMode: (mode) => {
       set({ mode });
-      scheduleFlush();
     },
 
     setLabTool: (id) => set({ activeToolId: id }),
@@ -283,119 +254,107 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
 
     undockPanel: (trialId, sectionId, as) => {
       set((s) => ({ undockedPanels: undockPanelIn(s.undockedPanels, trialId, sectionId, as) }));
-      scheduleFlush();
     },
 
     dockPanel: (trialId, sectionId) => {
       set((s) => ({ undockedPanels: dockPanelIn(s.undockedPanels, trialId, sectionId) }));
-      scheduleFlush();
     },
 
     setLayout: (layout) => {
       set({ layout });
-      scheduleFlush();
     },
-  }));
 
-  function scheduleFlush(): void {
-    if (persistDisabled) return;
-    if (flushTimer) clearTimeout(flushTimer);
-    flushTimer = setTimeout(() => {
-      const s = store.getState();
-      const document: LabDocument = {
-        version: CURRENT_DOCUMENT_VERSION,
-        trials: serializeTrials(s.trials, serializers),
-        saves: s.savedSnapshots,
-        layout: s.layout,
-        undockedPanels: s.undockedPanels,
-        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;
+    setInstruments: (instruments) => {
+      const before = get().instruments;
+      if (before === instruments) return;
+      const next = mergedHooks(hooks, instruments);
+      const previous = new Map((before ?? []).map((i) => [i.name, i]));
+      const changed = new Set(
+        instruments.filter((i) => previous.get(i.name) !== i).map((i) => i.name),
+      );
+      if (changed.size === 0) {
+        hooks = next;
+        set({ instruments });
+        return;
       }
-      flushTimer = null;
-    }, 300);
-  }
+      const s = get();
+      const trials = s.trials.map((w) =>
+        changed.has(w.instrumentName)
+          ? { ...w, config: hydratedConfig(next, w.instrumentName, w.config) }
+          : w,
+      );
+      const savedSnapshots = s.savedSnapshots.map((sn) =>
+        changed.has(sn.instrumentName)
+          ? { ...sn, config: hydratedConfig(next, sn.instrumentName, sn.config) }
+          : sn,
+      );
+      hooks = next;
+      set({ instruments, trials, savedSnapshots });
+    },
 
-  // A lab opened and closed without a single mutation still completes its
-  // fold; the flush is what removes the legacy keys.
-  if (foldedFromLegacy) scheduleFlush();
+    instrumentHooks: () => hooks,
+  }));
 
   return store;
 }
 
-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;
+function hooksOf(instruments: InstrumentList): InstrumentHooks {
+  return {
+    serializers: serializersOf(instruments),
+    configDefaults: configDefaultsOf(instruments),
+    configMigrations: configMigrationsOf(instruments),
+  };
 }
 
-/** 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;
+/** Hooks for `instruments`, keeping those of any instrument no longer listed:
+ *  its trials stay open, and their state still has to round-trip. A listed
+ *  name takes its hooks wholly from the new list. */
+function mergedHooks(old: InstrumentHooks, instruments: InstrumentList): InstrumentHooks {
+  const listed = new Set(instruments.map((i) => i.name));
+  const fresh = hooksOf(instruments);
+  const unlisted = <T>(entries: Record<string, T>): Record<string, T> =>
+    Object.fromEntries(Object.entries(entries).filter(([name]) => !listed.has(name)));
+  return {
+    serializers: { ...unlisted(old.serializers), ...fresh.serializers },
+    configDefaults: { ...unlisted(old.configDefaults), ...fresh.configDefaults },
+    configMigrations: { ...unlisted(old.configMigrations), ...fresh.configMigrations },
+  };
 }
 
-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 };
-  }
+/** How a stored config is brought up to date on the way in. */
+export type ConfigHydration = Pick<CreateLabStoreOptions, 'configDefaults' | 'configMigrations'>;
+
+function hydratedConfig(
+  hydration: ConfigHydration,
+  instrumentName: string,
+  config: unknown,
+): unknown {
+  const migrate = hydration.configMigrations?.[instrumentName];
+  const moved = migrate ? migrate(config) : config;
+  const defaults = hydration.configDefaults?.[instrumentName];
+  return defaults ? fillConfigDefaults(moved, defaults()) : moved;
+}
 
-  return {
-    document: normalizeDocument(outcome.doc, options.initialMode ?? 'auto'),
-    persistDisabled: false,
-    foldedFromLegacy,
-  };
+/** Rebuild stored trials: migrate each config, fill its gaps from its
+ *  instrument's defaults, then run the deserializer against the result. */
+export function hydrateTrials(
+  trials: SerializedTrial[],
+  serializers: InstrumentSerializers,
+  hydration: ConfigHydration = {},
+): TrialRecord[] {
+  return deserializeTrials(
+    trials.map((t) => ({ ...t, config: hydratedConfig(hydration, t.instrumentName, t.config) })),
+    serializers,
+  );
+}
+
+/** Bring each stored snapshot's config up to date the way `hydrateTrials` does a trial's. */
+export function hydrateSnapshots(
+  saves: SavedSnapshot[],
+  hydration: ConfigHydration = {},
+): SavedSnapshot[] {
+  return saves.map((sn) => ({
+    ...sn,
+    config: hydratedConfig(hydration, sn.instrumentName, sn.config),
+  }));
 }

package/src/state/toolSlot.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { createLabStore } from './store';
 
 function store() {
-  return createLabStore({ storageKey: 'test', storage: { read: () => null, write: () => {} } });
+  return createLabStore();
 }
 
 const record = { id: 't1', instrumentName: 'X', config: {}, state: {}, view: {} };

package/src/state/types.ts

@@ -1,4 +1,5 @@
 import type { ConfigPath, ValueAtPath } from '../config/types';
+import type { InstrumentList } from '../instrument/types';
 import type { UndockedPanels } from './undock';
 /** A trial's undo history, as snapshots of its state either side of the
  *  present. */
@@ -79,15 +80,29 @@ export interface LabStoreState {
   /** Sidebar sections torn out of their trial. A panel here is not rendered in
    *  its trial's sidebar; the workspace renders it instead. */
   undockedPanels: UndockedPanels;
+  /** The instruments this store serializes, migrates and fills configs for.
+   *  Null for a store built without them, whose trials look their instrument
+   *  up on the lab instead. Not persisted. */
+  instruments: InstrumentList | null;
 }
 
-/** Where a lab persists itself. Implementations are keyed string storage and
- *  nothing more, so the same store works against localStorage, the URL hash,
- *  or memory. */
+/** A change someone else made to one record: its new value, or `undefined`
+ *  when it was deleted. */
+export type StorageChange = [key: string, value: unknown];
+
+/** Where a lab persists itself: asynchronous keyed storage of
+ *  structured-clone values, so IndexedDB, the URL, memory or a server can all
+ *  back one. */
 export interface StorageAdapter {
-  read(key: string): string | null;
-  write(key: string, value: string): void;
-  delete?(key: string): void;
+  /** `undefined` when the key is absent. */
+  get(key: string): Promise<unknown>;
+  list(prefix: string): Promise<[string, unknown][]>;
+  /** Rejects when the value did not land. */
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Reports writes under `prefix` made by anyone but this adapter — another
+   *  tab, another instance, a server. Omit when the substrate cannot tell. */
+  subscribe?(prefix: string, on: (changes: StorageChange[]) => void): () => void;
 }
 
 /** What `useTrialState` hands an instrument: its state and config, with
@@ -101,23 +116,32 @@ export interface TrialStateHandle<TS, TC> {
   setConfig: <P extends ConfigPath<TC> & string>(path: P, value: ValueAtPath<TC, P>) => void;
 }
 
-/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
- *  two labs on one origin do not collide. */
+/** Options for `createLabStore`, which knows nothing about storage. */
 export interface CreateLabStoreOptions {
-  storageKey: string;
-  storage: StorageAdapter;
+  /** A document already read and migrated — what `openLabStore` hands over. */
+  initial?: LabDocument;
   initialMode?: LabMode;
   /** Each instrument's default config, keyed by instrument name, used to fill
    *  the gaps in a stored one. A config saved before its schema grew a branch
    *  arrives holding that branch's defaults rather than `undefined`, and keeps
-   *  whatever keys the schema has since stopped naming. `<Lab>` collects these
-   *  off its `instruments`. */
+   *  whatever keys the schema has since stopped naming. */
   configDefaults?: Record<string, () => unknown>;
+  /** Each instrument's `migrateConfig`, keyed by instrument name, run on a
+   *  stored config before its defaults fill it. */
+  configMigrations?: Record<string, (stored: unknown) => unknown>;
   /** How each instrument's state survives a reload. Hydration is the first
-   *  thing `createLabStore` does, so these have to arrive with the store —
-   *  anything registered afterwards is already too late to read the document
-   *  it was built from. `<Lab>` collects them off its `instruments`. */
+   *  thing `createLabStore` does, so these have to arrive with the store. */
   serializers?: InstrumentSerializers;
+  /** The instruments to serialize, migrate and fill configs for. Given, it
+   *  supplies all three and the three fields above are ignored. */
+  instruments?: InstrumentList;
+}
+
+/** What a store does per instrument on the way in and out. */
+export interface InstrumentHooks {
+  serializers: InstrumentSerializers;
+  configDefaults: Record<string, () => unknown>;
+  configMigrations: Record<string, (stored: unknown) => unknown>;
 }
 
 /** Per-instrument serialize/deserialize hooks, keyed by instrument name. An

package/src/state/useOpenOnce.ts

@@ -0,0 +1,68 @@
+import { useEffect, useRef, useState } from 'react';
+
+interface Closable {
+  close(): Promise<void> | void;
+}
+
+interface Entry<T> {
+  value: T | null;
+  pending: Promise<T> | null;
+  mounts: number;
+}
+
+/**
+ * Open something once for a component's lifetime: at once when `open` returns
+ * a value, after it settles when it returns a promise. Closed on unmount — but
+ * the close waits a microtask, and the remount React StrictMode performs right
+ * after its rehearsal unmount cancels it, so StrictMode opens it once.
+ */
+export function useOpenOnce<T extends Closable>(open: () => T | Promise<T>): T | null {
+  const entry = useRef<Entry<T> | null>(null);
+  if (entry.current === null) {
+    const result = open();
+    entry.current =
+      result instanceof Promise
+        ? { value: null, pending: result, mounts: 0 }
+        : { value: result, pending: null, mounts: 0 };
+  }
+  const [value, setValue] = useState<T | null>(entry.current.value);
+
+  useEffect(() => {
+    const e = entry.current as Entry<T>;
+    e.mounts += 1;
+    let live = true;
+    void e.pending?.then((opened) => {
+      e.value = opened;
+      if (live) setValue(opened);
+    });
+    return () => {
+      live = false;
+      e.mounts -= 1;
+      queueMicrotask(() => {
+        if (e.mounts > 0) return;
+        if (e.value) void e.value.close();
+        else
+          void e.pending?.then((opened) => {
+            if (e.mounts === 0) void opened.close();
+          });
+      });
+    };
+  }, []);
+
+  return value;
+}
+
+/** Warn once, in development, when a prop read only at mount changes after it. */
+export function useWarnIgnoredChange(component: string, props: Record<string, unknown>): void {
+  const first = useRef(props);
+  const warned = useRef(false);
+  if (process.env.NODE_ENV === 'production' || warned.current) return;
+  for (const key of Object.keys(props)) {
+    if (Object.is(first.current[key], props[key])) continue;
+    warned.current = true;
+    console.warn(
+      `[labkit] ${component} reads \`${key}\` once, at mount; a later change is ignored`,
+    );
+    return;
+  }
+}