@weasel-js/labkit 1.4.3 → 1.5.0

package/src/state/document.ts

@@ -10,11 +10,10 @@ import type {
 import type { UndockedPanels } from './undock';
 
 /** Bumped whenever the persisted shape changes; every bump needs a migration. */
-export const CURRENT_DOCUMENT_VERSION = 3;
+export const CURRENT_DOCUMENT_VERSION = 4;
 
-/** The one key a lab persists under. The `:doc` suffix keeps it out of the
- *  legacy bucket namespace, where a lab named `a:saves` would otherwise write
- *  its document over lab `a`'s saves bucket. */
+/** Where a version-3 lab kept its one document. Read once, to fold it into
+ *  records, then deleted. */
 export function labDocumentKey(storageKey: string): string {
   return `lk:${storageKey}:doc`;
 }
@@ -69,83 +68,92 @@ export function runMigrations(
 
 const LEGACY_BUCKETS = ['workspaces', 'saves', 'layout', 'theme'] as const;
 
-function parseOr<T>(raw: string | null, fallback: T, bucket: string): T {
-  if (raw === null) return fallback;
+/** The four keys a lab used before it was one document. */
+export function legacyKeys(storageKey: string): string[] {
+  return LEGACY_BUCKETS.map((bucket) => labStorageKey(storageKey, bucket));
+}
+
+/** A value some substrate returned for an old key: already parsed, or a JSON
+ *  string from a store that does not parse. `undefined` when it is neither. */
+export function parseStored(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
   try {
-    return JSON.parse(raw) as T;
+    return JSON.parse(value);
   } catch {
-    console.warn(`[labkit] unparseable legacy bucket "${bucket}", dropping it`);
-    return fallback;
+    return undefined;
   }
 }
 
+function bucketOr<T>(value: unknown, fallback: T, bucket: string, shape: 'array' | 'object'): T {
+  if (value === undefined) return fallback;
+  const parsed = parseStored(value);
+  const fits = shape === 'array' ? Array.isArray(parsed) : !!parsed && typeof parsed === 'object';
+  if (fits) return parsed as T;
+  console.warn(`[labkit] unparseable legacy bucket "${bucket}", dropping it`);
+  return fallback;
+}
+
 /** Assemble a version-0 document out of the four pre-document keys, or null
  *  if none of them is present. `fallbackMode` is used when the theme key is
  *  absent or holds something unrecognized; `interstellar` passes through
  *  untouched for `migrateV0toV1` to coerce. */
-export function readLegacyDocument(
-  storage: StorageAdapter,
+export async function readLegacyDocument(
+  read: (key: string) => Promise<unknown>,
   storageKey: string,
   fallbackMode: LabMode,
-): Record<string, unknown> | null {
-  const present = LEGACY_BUCKETS.some((b) => storage.read(labStorageKey(storageKey, b)) !== null);
-  if (!present) return null;
+): Promise<Record<string, unknown> | null> {
+  const [workspaces, saves, layout, theme] = await Promise.all(
+    LEGACY_BUCKETS.map((bucket) => read(labStorageKey(storageKey, bucket))),
+  );
+  if ([workspaces, saves, layout, theme].every((v) => v === undefined)) return null;
 
-  const rawMode = storage.read(labStorageKey(storageKey, 'theme'));
   const mode =
-    rawMode === 'light' || rawMode === 'dark' || rawMode === 'auto' || rawMode === 'interstellar'
-      ? rawMode
+    theme === 'light' || theme === 'dark' || theme === 'auto' || theme === 'interstellar'
+      ? theme
       : fallbackMode;
 
   return {
     version: 0,
-    workspaces: parseOr(storage.read(labStorageKey(storageKey, 'workspaces')), [], 'workspaces'),
-    saves: parseOr(storage.read(labStorageKey(storageKey, 'saves')), [], 'saves'),
-    layout: parseOr(storage.read(labStorageKey(storageKey, 'layout')), {}, 'layout'),
+    workspaces: bucketOr(workspaces, [], 'workspaces', 'array'),
+    saves: bucketOr(saves, [], 'saves', 'array'),
+    layout: bucketOr(layout, {}, 'layout', 'object'),
     mode,
   };
 }
 
-/** Delete the four pre-document keys, but only once `expectedDocument` is
- *  confirmed to be exactly what is stored under the document key — a
- *  read-back, not a trust of the write that produced it. On any mismatch
- *  (write failed, landed partially, or never happened) it deletes nothing,
- *  warns, and returns `false` so the legacy buckets stay as a recoverable
- *  copy. Deletion itself is read back too — `StorageAdapter.delete` is
- *  optional, so an adapter without it leaves the keys in place — and `true`
- *  is returned only once all four are actually gone. */
-export function deleteLegacyKeys(
-  storage: StorageAdapter,
-  storageKey: string,
-  expectedDocument: string,
-): boolean {
-  const actual = storage.read(labDocumentKey(storageKey));
-  if (actual !== expectedDocument) {
-    console.warn(
-      `[labkit] keeping legacy keys for "${storageKey}": could not confirm the migrated document was written`,
-    );
+/** Whether two stored values hold the same data. Stored values are
+ *  structured-clone copies, so identity says nothing. */
+export function sameStored(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Delete `keys` and read each back, so an adapter whose delete silently did
+ *  nothing is caught. `true` only once all of them are gone. */
+export async function deleteConfirmed(storage: StorageAdapter, keys: string[]): Promise<boolean> {
+  try {
+    await Promise.all(keys.map((key) => storage.delete(key)));
+    const left = await Promise.all(keys.map((key) => storage.get(key)));
+    return left.every((v) => v === undefined);
+  } catch {
     return false;
   }
-  let allGone = true;
-  for (const bucket of LEGACY_BUCKETS) {
-    const key = labStorageKey(storageKey, bucket);
-    storage.delete?.(key);
-    if (storage.read(key) !== null) allGone = false;
-  }
-  return allGone;
 }
 
-/** Set `raw` aside under the quarantine key, reading it back to confirm it
+/** Set `value` aside under the quarantine key, reading it back to confirm it
  *  landed. Returns `false` when it did not — a full disk is exactly when a
  *  document goes unreadable — so the caller can leave the original alone
  *  rather than overwrite the only copy of it. */
-export function quarantineDocument(
+export async function quarantineDocument(
   storage: StorageAdapter,
   storageKey: string,
-  raw: string,
-): boolean {
-  storage.write(quarantineKey(storageKey), raw);
-  return storage.read(quarantineKey(storageKey)) === raw;
+  value: unknown,
+): Promise<boolean> {
+  try {
+    await storage.set(quarantineKey(storageKey), value);
+    return sameStored(await storage.get(quarantineKey(storageKey)), value);
+  } catch {
+    return false;
+  }
 }
 
 /** Fill in whatever a document is missing or holds the wrong shape of, so a
@@ -202,5 +210,11 @@ export function migrateV2toV3(doc: Record<string, unknown>): Record<string, unkn
   return { ...doc, undockedPanels: {}, version: 3 };
 }
 
+/** Version 3 to version 4: a lab is stored as records under one prefix
+ *  instead of one document. The joined shape does not change. */
+export function migrateV3toV4(doc: Record<string, unknown>): Record<string, unknown> {
+  return { ...doc, version: 4 };
+}
+
 /** Index `i` migrates a version-`i` document to version `i + 1`. */
-export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2, migrateV2toV3];
+export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2, migrateV2toV3, migrateV3toV4];

package/src/state/helpers.test.ts

@@ -5,6 +5,7 @@ import {
   emptyUndoStack,
   encodeUrlHash,
   labStorageKey,
+  newId,
   serializeTrials,
 } from './helpers';
 
@@ -114,4 +115,23 @@ describe('deserializeTrials', () => {
   it('returns an empty list when given something that is not an array', () => {
     expect(deserializeTrials(undefined as never, {})).toEqual([]);
   });
+
+  describe('newId', () => {
+    it('mints distinct ids', () => {
+      expect(newId()).not.toBe(newId());
+    });
+
+    it('falls back where crypto.randomUUID is absent', () => {
+      // What a lab reached by LAN IP gets: not a secure context, so the
+      // function is not there. It used to throw on the first render and show a
+      // blank page.
+      const real = globalThis.crypto;
+      Object.defineProperty(globalThis, 'crypto', { value: {}, configurable: true });
+      try {
+        expect(newId()).not.toBe(newId());
+      } finally {
+        Object.defineProperty(globalThis, 'crypto', { value: real, configurable: true });
+      }
+    });
+  });
 });

package/src/state/helpers.ts

@@ -25,6 +25,22 @@ export function decodeUrlHash(hash: string): string | null {
   }
 }
 
+/**
+ * An id for a trial or a snapshot.
+ *
+ * `crypto.randomUUID` exists only in a secure context, and a LAN address is
+ * not one — so a lab opened on a phone or a tablet by IP throws on its first
+ * render and shows a blank page with nothing in reach to say why. The counter
+ * is per page load, which is all these ids have to survive: they name records
+ * inside one session's store, and a saved snapshot carries its own name.
+ */
+let idCounter = 0;
+export function newId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+  return `lk-${Date.now().toString(36)}-${idCounter++}`;
+}
+
 /** A fresh, empty undo history. */
 export function emptyUndoStack(): UndoStack {
   return { past: [], future: [] };

package/src/state/index.ts

@@ -1,5 +1,8 @@
 export {
+  createIndexedDbAdapter,
   createMemoryAdapter,
+  type IndexedDbAdapterOptions,
+  indexedDbAdapter,
   localStorageAdapter,
   noneAdapter,
   sessionStorageAdapter,
@@ -26,6 +29,9 @@ export {
   labStorageKey,
   serializeTrials,
 } from './helpers';
+export { type OpenedLabStore, type OpenLabStoreOptions, openLabStore } from './openLabStore';
+export { Persistence, type PersistenceProps } from './Persistence';
+export type { RecordCache, RecordChange } from './records';
 export {
   SingletonExperimentProvider,
   type SingletonExperimentProviderProps,
@@ -41,10 +47,12 @@ export type {
   SavedSnapshot,
   SerializedTrial,
   StorageAdapter,
+  StorageChange,
   TrialRecord,
   TrialStateHandle,
   UndoStack,
 } from './types';
 export type { UndockedPanel, UndockedPanels } from './undock';
 export { dockPanel, panelKey, undockPanel } from './undock';
+export { type PersistedStateOptions, usePersistedState } from './usePersistedState';
 export { useTrialState } from './useTrialState';

package/src/state/labRecords.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { CURRENT_DOCUMENT_VERSION } from './document';
+import {
+  documentOfRecords,
+  labPrefix,
+  parseRecordName,
+  recordsOfDocument,
+  trialRecord,
+  valueRecord,
+} from './labRecords';
+import type { LabDocument } from './types';
+
+const VIEW = { zoom: 1, pan: { x: 0, y: 0 } };
+
+describe('record names', () => {
+  it('encodes the storage key, so no lab prefix contains another', () => {
+    expect(labPrefix('drag-lab')).toBe('lk:drag-lab:');
+    expect(labPrefix('a:trial:x')).toBe('lk:a%3Atrial%3Ax:');
+    expect(labPrefix('a:trial:x').startsWith(labPrefix('a'))).toBe(false);
+  });
+
+  it('round-trips ids holding the separator', () => {
+    expect(parseRecordName(trialRecord('odd:id'))).toEqual({ kind: 'trial', id: 'odd:id' });
+  });
+
+  it('scopes a value to its trial or to the lab', () => {
+    expect(valueRecord('t:1', 'tab')).toBe('value:trial:t%3A1:tab');
+    expect(valueRecord(null, 'tab')).toBe('value:lab:tab');
+    expect(parseRecordName(valueRecord('t:1', 'a:b'))).toEqual({ kind: 'value' });
+  });
+
+  it('answers null for a name no lab writes', () => {
+    for (const name of [
+      'doc',
+      'meta:x',
+      'trial:',
+      'trial:a:b',
+      'value:lab',
+      'value:x:y',
+      'trial:%E0%A4%A',
+    ]) {
+      expect(parseRecordName(name)).toBeNull();
+    }
+  });
+});
+
+describe('documents and records', () => {
+  const doc: LabDocument = {
+    version: CURRENT_DOCUMENT_VERSION,
+    trials: [
+      { id: 'b', instrumentName: 'T', config: {}, state: { n: 2 }, view: VIEW },
+      { id: 'a', instrumentName: 'T', config: {}, state: { n: 1 }, view: VIEW },
+    ],
+    saves: [
+      {
+        id: 's2',
+        name: 'later',
+        trialId: 'a',
+        instrumentName: 'T',
+        config: {},
+        state: {},
+        savedAt: 2,
+      },
+      {
+        id: 's1',
+        name: 'earlier',
+        trialId: 'a',
+        instrumentName: 'T',
+        config: {},
+        state: {},
+        savedAt: 1,
+      },
+    ],
+    layout: { a: { h: 1 } },
+    undockedPanels: {},
+    mode: 'dark',
+  };
+
+  it('writes meta last', () => {
+    const names = recordsOfDocument(doc).map(([name]) => name);
+    expect(names.at(-1)).toBe('meta');
+  });
+
+  it('joins back into the document it came from, trials in stored order', () => {
+    const joined = documentOfRecords(recordsOfDocument(doc).reverse());
+    expect(joined?.doc).toEqual({ ...doc, saves: [doc.saves[1], doc.saves[0]] });
+    expect([...(joined?.orders ?? [])]).toEqual([
+      ['b', 0],
+      ['a', 1],
+    ]);
+  });
+
+  it('breaks an order tie by id', () => {
+    const joined = documentOfRecords([
+      ['meta', { version: 4, mode: 'auto' }],
+      ['trial:z', { instrumentName: 'T', order: 0 }],
+      ['trial:m', { instrumentName: 'T', order: 0 }],
+    ]);
+    expect((joined?.doc.trials as { id: string }[]).map((t) => t.id)).toEqual(['m', 'z']);
+  });
+
+  it('is null without a meta record', () => {
+    expect(documentOfRecords([['trial:a', { instrumentName: 'T', order: 0 }]])).toBeNull();
+  });
+});

package/src/state/labRecords.ts

@@ -0,0 +1,160 @@
+import type { LabDocument, SavedSnapshot, SerializedTrial } from './types';
+
+/** Every record of the lab stored under `storageKey` starts with this. The key
+ *  is URI-encoded, so it holds no `:` and one lab's prefix can never reach into
+ *  another lab's records. */
+export function labPrefix(storageKey: string): string {
+  return `lk:${encodeURIComponent(storageKey)}:`;
+}
+
+export const META_RECORD = 'meta';
+export const LAYOUT_RECORD = 'layout';
+export const UNDOCK_RECORD = 'undock';
+
+export function trialRecord(id: string): string {
+  return `trial:${encodeURIComponent(id)}`;
+}
+
+export function saveRecord(id: string): string {
+  return `save:${encodeURIComponent(id)}`;
+}
+
+/** The prefix every value scoped to one trial shares. */
+export function trialValuesPrefix(trialId: string): string {
+  return `value:trial:${encodeURIComponent(trialId)}:`;
+}
+
+/** Where a `usePersistedState` value lives: under its trial, or — with a null
+ *  trial — under the lab. */
+export function valueRecord(trialId: string | null, name: string): string {
+  const encoded = encodeURIComponent(name);
+  return trialId === null ? `value:lab:${encoded}` : `${trialValuesPrefix(trialId)}${encoded}`;
+}
+
+/** What a record name addresses, or null for a name no lab writes. */
+export type RecordName =
+  | { kind: 'meta' | 'layout' | 'undock' | 'value' }
+  | { kind: 'trial' | 'save'; id: string };
+
+export function parseRecordName(name: string): RecordName | null {
+  const parts = name.split(':');
+  try {
+    switch (parts[0]) {
+      case 'meta':
+      case 'layout':
+      case 'undock':
+        return parts.length === 1 ? { kind: parts[0] } : null;
+      case 'trial':
+      case 'save':
+        return parts.length === 2 && parts[1]
+          ? { kind: parts[0], id: decodeURIComponent(parts[1]) }
+          : null;
+      case 'value':
+        return (parts[1] === 'lab' && parts.length === 3) ||
+          (parts[1] === 'trial' && parts.length === 4)
+          ? { kind: 'value' }
+          : null;
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/** The fields of the meta record. */
+export interface LabMeta {
+  version: number;
+  mode: unknown;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** A document as the records a lab stores it in, `meta` last — so a write in
+ *  this order that stops partway leaves no `meta`, and the next open folds the
+ *  old storage again rather than trusting a partial set. */
+export function recordsOfDocument(doc: LabDocument): [string, unknown][] {
+  return [
+    ...doc.trials.map((t, order): [string, unknown] => [trialRecord(t.id), { ...t, order }]),
+    ...doc.saves.map((s): [string, unknown] => [saveRecord(s.id), s]),
+    [LAYOUT_RECORD, doc.layout],
+    [UNDOCK_RECORD, doc.undockedPanels],
+    [META_RECORD, { version: doc.version, mode: doc.mode } satisfies LabMeta],
+  ];
+}
+
+/** Records joined back into an unmigrated document, with each trial's stored
+ *  order. Null when there is no `meta` record — no lab has been stored here in
+ *  this form. */
+export function documentOfRecords(
+  entries: Iterable<[string, unknown]>,
+): { doc: Record<string, unknown>; orders: Map<string, number> } | null {
+  let meta: unknown;
+  let layout: unknown;
+  let undock: unknown;
+  const trials: { trial: SerializedTrial; order: number }[] = [];
+  const saves: SavedSnapshot[] = [];
+
+  for (const [name, value] of entries) {
+    const parsed = parseRecordName(name);
+    if (!parsed) continue;
+    switch (parsed.kind) {
+      case 'meta':
+        meta = value;
+        break;
+      case 'layout':
+        layout = value;
+        break;
+      case 'undock':
+        undock = value;
+        break;
+      case 'trial':
+        if (isObject(value)) {
+          const { order, ...rest } = value;
+          trials.push({
+            trial: { ...rest, id: parsed.id } as SerializedTrial,
+            order: typeof order === 'number' && Number.isFinite(order) ? order : Infinity,
+          });
+        }
+        break;
+      case 'save':
+        if (isObject(value)) saves.push({ ...value, id: parsed.id } as SavedSnapshot);
+        break;
+    }
+  }
+  if (!isObject(meta)) return null;
+
+  trials.sort(compareTrialOrder);
+  const orders = new Map<string, number>();
+  let next = 0;
+  for (const { trial, order } of trials) {
+    const at = Number.isFinite(order) ? order : next;
+    orders.set(trial.id, at);
+    next = Math.max(next, at + 1);
+  }
+  saves.sort((a, b) => a.savedAt - b.savedAt);
+
+  return {
+    doc: {
+      version: meta.version,
+      mode: meta.mode,
+      trials: trials.map((t) => t.trial),
+      saves,
+      layout,
+      undockedPanels: undock,
+    },
+    orders,
+  };
+}
+
+/** Stored order first; two trials added at once in two tabs can share an
+ *  order, so the id breaks the tie the same way everywhere. */
+export function compareTrialOrder(
+  a: { trial: { id: string }; order: number },
+  b: { trial: { id: string }; order: number },
+): number {
+  if (a.order !== b.order) return a.order < b.order ? -1 : 1;
+  return a.trial.id < b.trial.id ? -1 : a.trial.id > b.trial.id ? 1 : 0;
+}