@weasel-js/labkit 1.0.4 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 React widgets for building self-contained interactive **lab** pages — pages with sliders, controls, and canvas-based experimentation.
 
-This is the v0.x of the library. The Lab/Workspace/Instrument runtime arrives in later plans; v0.0.1 ships presentational primitives.
+This is the v0.x of the library. The Lab/Trial/Instrument runtime arrives in later plans; v0.0.1 ships presentational primitives.
 
 ## Installation
 
@@ -28,16 +28,16 @@ Then point your app at the local clone:
 ## Usage
 
 ```tsx
-import { LabShell, Toolbar, WorkspaceGrid, FpsMeter } from '@weasel-js/labkit';
+import { LabShell, Toolbar, Workspace, FpsMeter } from '@weasel-js/labkit';
 import '@weasel-js/labkit/styles.css';
 
 function MyLab() {
   return (
     <LabShell title="My Lab" header={<button>+ Add</button>}>
-      <WorkspaceGrid>
-        <div>Workspace 1</div>
-        <div>Workspace 2</div>
-      </WorkspaceGrid>
+      <Workspace>
+        <div>Trial 1</div>
+        <div>Trial 2</div>
+      </Workspace>
     </LabShell>
   );
 }

package/dist/_dts/{index-CFlDPeZh.d.ts → index-iAP6XbH3.d.ts}

@@ -2,20 +2,24 @@ import { ReactNode } from 'react';
 import { C as ConfigField } from './types-x92Kfeme.js';
 
 /** What an instrument's `render` is handed: its state and config, the setters
- *  for both, the workspace it is mounted in, and a way to emit named events. */
+ *  for both, the trial it is mounted in, and a way to emit named events. */
 interface RenderContext<TS = unknown, TC = unknown> {
     state: TS;
     config: TC;
     setState: (next: TS | ((prev: TS) => TS)) => void;
     setConfig: (key: keyof TC, value: unknown) => void;
-    workspace: {
+    trial: {
         id: string;
         zoom: number;
         setZoom: (z: number) => void;
     };
     emit: (event: string) => void;
 }
-/** One 2D canvas layer of an instrument, drawn in declaration order. */
+/** One 2D canvas layer of an instrument, drawn in declaration order.
+ *
+ *  `draw` is called with the camera already applied, so it works in world
+ *  coordinates. `zoom` is passed for the things that must not scale with it —
+ *  set `ctx.lineWidth = 1 / zoom` to keep a hairline hairline. */
 interface CanvasLayer<TS = unknown, TC = unknown> {
     id: string;
     draw: (ctx: CanvasRenderingContext2D, args: {
@@ -36,7 +40,7 @@ interface CanvasCapability<TS = unknown, TC = unknown> {
         };
     };
 }
-/** Declares which of an instrument's layers the workspace should offer
+/** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
 interface LayerCapability {
     ids: string[];
@@ -72,7 +76,7 @@ type HitResult = {
     layerId?: string;
     pointId?: string;
 };
-/** A workspace's camera. */
+/** A trial's camera. */
 type ViewTransform = {
     zoom: number;
     pan: Point;
@@ -102,13 +106,15 @@ type DragFeedback = {
  * and `state`, what the experiment is currently doing — and renders from both.
  * The optional capability fields declare what else it wants from the runtime:
  * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
- * is what makes the workspace provide the corresponding chrome.
+ * is what makes the trial provide the corresponding chrome.
  */
 interface Instrument<TS = unknown, TC = unknown> {
     name: string;
     defaultConfig: () => TC;
     initialState: (config: TC) => TS;
     configSchema?: () => ConfigField[];
+    /** The instrument's DOM. With `canvas`, this renders as an overlay above the
+     *  layers rather than instead of them; return `null` for canvas only. */
     render: (ctx: RenderContext<TS, TC>) => ReactNode;
     onConfigChange?: (config: TC, prev: TC, state: TS) => TS;
     serialize?: (state: TS) => unknown;
@@ -118,5 +124,9 @@ interface Instrument<TS = unknown, TC = unknown> {
     dragDrop?: DragDropCapability<TS, TC>;
     undo?: UndoCapability;
 }
+/** Instruments as a lab receives them. `any` rather than `unknown` because
+ *  parameter contravariance keeps a `defineInstrument<TS, TC>` result out of
+ *  an `Instrument<unknown, unknown>[]`; it is contained to this alias. */
+type InstrumentList = readonly Instrument<any, any>[];
 
-export type { CanvasCapability as C, DragDropCapability as D, HitResult as H, Instrument as I, LayerCapability as L, PaletteItem as P, RenderContext as R, SystemEvent as S, UndoCapability as U, ViewTransform as V, CanvasLayer as a, DragFeedback as b, LayerDescriptor as c, Point as d };
+export type { CanvasCapability as C, DragDropCapability as D, HitResult as H, Instrument as I, LayerCapability as L, PaletteItem as P, RenderContext as R, SystemEvent as S, UndoCapability as U, ViewTransform as V, InstrumentList as a, CanvasLayer as b, DragFeedback as c, LayerDescriptor as d, Point as e };

package/dist/_dts/{useExperimentState-D7EQnnwJ.d.ts → useTrialState-DYe2vUwN.d.ts}

@@ -2,15 +2,15 @@ import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
 
-/** 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. */
 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. */
-interface WorkspaceRecord<TS = unknown, TC = unknown> {
+interface TrialRecord<TS = unknown, TC = unknown> {
     id: string;
     instrumentName: string;
     config: TC;
@@ -24,12 +24,12 @@ interface WorkspaceRecord<TS = unknown, TC = unknown> {
     };
     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. */
 interface SavedSnapshot {
     id: string;
     name: string;
-    workspaceId: string;
+    trialId: string;
     instrumentName: string;
     config: unknown;
     state: unknown;
@@ -37,14 +37,14 @@ interface SavedSnapshot {
 }
 /** `auto` follows the OS; the other two are an explicit choice. */
 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. */
 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>;
 }
 /** Where a lab persists itself. Implementations are keyed string storage and
@@ -55,9 +55,9 @@ interface StorageAdapter {
     write(key: string, value: string): void;
     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. */
-interface ExperimentStateHandle<TS, TC> {
+interface TrialStateHandle<TS, TC> {
     state: TS;
     setState: (next: TS | ((prev: TS) => TS)) => void;
     config: TC;
@@ -76,6 +76,20 @@ 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. */
+type SerializedTrial = Omit<TrialRecord, 'undoStack'>;
+/** Everything a lab persists, under one key, at a known version. */
+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`. */
+type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;
 
 /** Persist to `localStorage` — state survives a reload and a new tab. Falls
  *  back to no-ops when storage is unavailable. */
@@ -91,20 +105,20 @@ declare function createMemoryAdapter(): StorageAdapter;
 /** Persists nothing and reads back nothing. */
 declare const noneAdapter: StorageAdapter;
 
-/** 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. */
 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;
+    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: TrialRecord['view']) => void;
+    updateTrialUndoStack: (id: string, next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack'])) => 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;
 }
@@ -130,22 +144,32 @@ declare function LabStoreProvider({ store, children, }: {
 }): ReactElement;
 /** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */
 declare function useLabStore(): LabStoreState & ReturnType<LabStore['getState']>;
-/** Context carrying which workspace the subtree belongs to. */
-declare const WorkspaceIdContext: react.Context<string | null>;
-/** Names the workspace its subtree belongs to, so an instrument's hooks can
+/** Context carrying which trial the subtree belongs to. */
+declare const TrialIdContext: react.Context<string | null>;
+/** Names the trial its subtree belongs to, so an instrument's hooks can
  *  find their own record in the store without being passed an id. */
-declare function WorkspaceIdProvider({ workspaceId, children, }: {
-    workspaceId: string;
+declare function TrialIdProvider({ trialId, children, }: {
+    trialId: string;
     children: ReactNode;
 }): ReactElement;
-/** The id of the workspace this component is inside. Throws outside a
- *  `<WorkspaceIdProvider>`. */
-declare function useWorkspaceId(): string;
+/** The id of the trial this component is inside. Throws outside a
+ *  `<TrialIdProvider>`. */
+declare function useTrialId(): string;
+
+/** Bumped whenever the persisted shape changes; every bump needs a migration. */
+declare const CURRENT_DOCUMENT_VERSION = 2;
+/** 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. */
+declare function labDocumentKey(storageKey: string): string;
+/** Where a document that failed to migrate is set aside, so a bad migration
+ *  loses state loudly rather than silently. */
+declare function quarantineKey(storageKey: string): string;
 
 /** An instrument's own state and config, plus setters. Reads the surrounding
- *  workspace id, so an instrument never has to know which workspace it is
- *  running in. Throws outside a lab store and workspace. */
-declare function useExperimentState<TS = unknown, TC = unknown>(): ExperimentStateHandle<TS, TC>;
+ *  trial id, so an instrument never has to know which trial it is
+ *  running in. Throws outside a lab store and trial. */
+declare function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS, TC>;
 
-export { LabStoreContext as b, LabStoreProvider as c, WorkspaceIdContext as f, WorkspaceIdProvider as g, createLabStore as h, createMemoryAdapter as i, useExperimentState as j, useLabStore as k, localStorageAdapter as l, useWorkspaceId as m, noneAdapter as n, sessionStorageAdapter as s, urlHashAdapter as u };
-export type { CreateLabStoreOptions as C, ExperimentStateHandle as E, InstrumentSerializers as I, LabStore as L, StorageAdapter as S, UndoStack as U, WorkspaceRecord as W, LabStoreActions as a, LabStoreState as d, SavedSnapshot as e, LabMode as o };
+export { CURRENT_DOCUMENT_VERSION as C, LabStoreContext as e, LabStoreProvider as f, TrialIdContext as i, TrialIdProvider as j, createLabStore as l, createMemoryAdapter as m, labDocumentKey as n, localStorageAdapter as o, noneAdapter as p, quarantineKey as q, useLabStore as r, sessionStorageAdapter as s, useTrialId as t, urlHashAdapter as u, useTrialState as v };
+export type { InstrumentSerializers as I, LabDocument as L, Migration as M, SerializedTrial as S, TrialRecord as T, UndoStack as U, StorageAdapter as a, CreateLabStoreOptions as b, LabStore as c, LabStoreActions as d, LabStoreState as g, SavedSnapshot as h, TrialStateHandle as k, LabMode as w };

package/dist/canvas/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { V as ViewTransform, d as Point } from '../_dts/index-CFlDPeZh.js';
+import { V as ViewTransform, e as Point } from '../_dts/index-iAP6XbH3.js';
 import '../_dts/types-x92Kfeme.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how