@weasel-js/labkit 1.0.4 → 1.2.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>
   );
 }
@@ -59,6 +59,33 @@ import { ThemeProvider } from '@weasel-js/theme/react';
 `"light"` or `"dark"`. Only `styles.css` needs importing — the token values
 arrive through the provider.
 
+## Driving your own renderer
+
+`CanvasStack` is 2D. For three.js or raw WebGL, take rects and dirtiness from
+labkit and keep the GL yourself:
+
+```tsx
+import { toDeviceRect, useSurfaceTile, useTiledSurface } from '@weasel-js/labkit/surface';
+```
+
+A trial's `view` is opaque to labkit — it is persisted, restored on Reset and
+handed to the instrument without being read into — so a 3D lab stores an orbit
+there and gets all three. `useOrbit` is the 3D peer of `usePanZoom`.
+
+See `src/surface/AGENTS.md` for the contract and the traps.
+
+## Long-running work
+
+An instrument with work too slow for a render declares a `job`. labkit starts it,
+aborts it on unmount and on a key change, discards results from a superseded run,
+and renders progress and a cancel control into the trial chrome. Per-item failure
+is an event rather than a thrown error, so a run with two failed items is a
+partial success.
+
+```tsx
+import type { JobCapability } from '@weasel-js/labkit/job';
+```
+
 ## Development
 
 ```bash

package/dist/_dts/{DrawCommand-BkZztJsW.d.ts → DrawCommand-C_XboUpz.d.ts}

@@ -88,6 +88,8 @@ interface SerializedHistoryEntry {
     label: string;
     forwardOps: SerializedOp[];
     baseOps: SerializedOp[];
+    selectionBefore?: readonly string[];
+    selectionAfter?: readonly string[];
 }
 /** Snapshot of an entire `History` instance. Designed to live alongside the
  *  scene snapshot in IDB so a reload restores the undo / redo stacks to
@@ -119,6 +121,10 @@ interface HistoryEntry {
      *  contribute nothing. May be `undefined` for deserialized entries
      *  restored from an older snapshot that predates this field. */
     touchedIds?: ReadonlySet<string>;
+    /** Selection restored when this entry is undone. */
+    selectionBefore?: readonly string[];
+    /** Selection restored when this entry is redone. */
+    selectionAfter?: readonly string[];
 }
 /** Op-batched undo/redo controller returned by `createHistory`. */
 interface History {
@@ -170,7 +176,7 @@ interface History {
      *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit
      *  to flush a session's net forward ops to the parent as one entry without
      *  re-mutating the scene. */
-    recordEntry(ops: Op[], label: string): void;
+    recordEntry(ops: Op[], label: string, options?: RecordEntryOptions): void;
     /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot
      *  of "what changes are currently applied via this history" — useful for
      *  Journal.commit to flush to a parent, and for any caller that wants to
@@ -193,6 +199,14 @@ interface History {
      *  to resume or discard before calling this. */
     resumeJournal(journal: Journal): void;
 }
+/** Options for `recordEntry`. */
+interface RecordEntryOptions {
+    /** Selection as of before the already-applied ops ran. `recordEntry` is
+     *  called after the fact, so the live selection has moved on by then and
+     *  the engine cannot sample it — a caller that wants undo to restore the
+     *  selection captures it when the batch opens and passes it here. */
+    selectionBefore?: readonly string[];
+}
 
 /** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
 type PathFillRule = 'nonzero' | 'evenodd';
@@ -500,6 +514,14 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
      *  `SceneCanvasAdapter`). Pass `this` from `sceneToAdapter` or a compatible
      *  adapter. */
     applyBatch(ops: Op[], label: string, adapter: unknown): void;
+    /** The transient set of active ids — "operate on these N as a unit".
+     *  Shared by every view over this scene unless a view supplies its own
+     *  (see `CanvasView.selection`). Not document content: it never appears
+     *  in `toJSON`. It does ride on history entries, so undo and redo put
+     *  back the selection an edit was made under; changing it is never an
+     *  undo step of its own. */
+    getSelection(): readonly NodeId[];
+    setSelection(ids: readonly NodeId[]): void;
     undo(): boolean;
     redo(): boolean;
     canUndo(): boolean;
@@ -792,17 +814,22 @@ type StrokeAlign = 'center' | 'inner' | 'outer';
 /** Stroke style: a FillStyle plus structural line parameters. */
 interface Stroke {
     paint: FillStyle;
-    width?: number;
+    /** World units, or `{ px }` for screen pixels — resolved against the
+     *  accumulated transform scale at draw time, so it holds its on-screen
+     *  thickness as the view zooms. */
+    width?: number | {
+        px: number;
+    };
     /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
     dash?: number[];
     cap?: 'butt' | 'round' | 'square';
     join?: 'miter' | 'round' | 'bevel';
     /**
      * Miter join fallback threshold. When the miter length exceeds
-     * `miterLimit * width / 2`, the join falls back to a bevel. Default 10
-     * (matching Canvas2D). SVG's default is 4; consumers that want SVG
-     * fidelity should set this explicitly when constructing strokes from
-     * SVG sources where the attribute was omitted.
+     * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,
+     * matching SVG — which is also what the kit's own serializer implies when
+     * it omits the attribute for an unset field. Canvas2D's 10 lets an acute
+     * corner throw a spike four times the half-width.
      */
     miterLimit?: number;
     /** Where the stroke sits relative to the geometric edge. Default `'center'`. */
@@ -1063,6 +1090,21 @@ interface ImageDrawCommand {
      *  device pixels as hard squares — required by anything magnifying a
      *  framebuffer readback, where blur destroys the point of the readback. */
     sampling?: 'linear' | 'nearest';
+    /** Sub-rectangle of `image` to draw, in bitmap pixels from the top-left.
+     *  Omitted draws the whole bitmap. Not range-checked: a rect past the edge
+     *  samples outside [0..1], which CLAMP_TO_EDGE smears. With
+     *  `sampling: 'linear'` the filter reaches half a texel beyond `source`, so
+     *  atlas frames need a gutter (see `SpriteSheet.spacing`) or `'nearest'`. */
+    source?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Mirror the sampled region within the destination rect. The quad does not
+     *  move — a flipped draw covers exactly the pixels an unflipped one does. */
+    flipX?: boolean;
+    flipY?: boolean;
 }
 /**
  * Custom shader draw command. The renderer generates a quad over `bounds`

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

@@ -1,21 +1,34 @@
 import { ReactNode } from 'react';
 import { C as ConfigField } from './types-x92Kfeme.js';
+import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.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;
+        /** The trial's view, in whatever shape this instrument chose. labkit persists
+         *  it and restores it on Reset without ever reading into it. */
+        view: unknown;
+        setView: (next: unknown) => void;
+        /** 2D convenience over `view`. Reads 1 and writes nothing when the trial holds
+         *  a view that is not the 2D one. */
         zoom: number;
         setZoom: (z: number) => void;
     };
     emit: (event: string) => void;
+    /** Present only when the instrument declares a `job`. */
+    job?: JobHandle;
 }
-/** 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 +49,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 +85,7 @@ type HitResult = {
     layerId?: string;
     pointId?: string;
 };
-/** A workspace's camera. */
+/** A trial's camera. */
 type ViewTransform = {
     zoom: number;
     pan: Point;
@@ -102,13 +115,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;
@@ -117,6 +132,13 @@ interface Instrument<TS = unknown, TC = unknown> {
     layers?: LayerCapability;
     dragDrop?: DragDropCapability<TS, TC>;
     undo?: UndoCapability;
+    /** Work too slow to do during a render. The runtime starts it, aborts it on
+     *  unmount and on a `key` change, and renders progress into the trial. */
+    job?: JobCapability<TS, TC, never>;
 }
+/** 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/types-DJ79Tg5J.d.ts

@@ -0,0 +1,56 @@
+/** What a running job reports as it goes. `total` may arrive at any point and may
+ *  arrive more than once; a job that cannot count up front simply never sends it.
+ *
+ *  `failed` is a first-class event rather than a thrown error because these
+ *  failures are per item: a run with two failed items is a partial success, and
+ *  its other items are worth showing. */
+type JobEvent<T> = {
+    kind: 'total';
+    total: number;
+} | {
+    kind: 'item';
+    item: T;
+} | {
+    kind: 'failed';
+    index: number;
+    error: string;
+};
+/** Where a job is. `idle` before its first run and after a cancel; `done` when the
+ *  iterable finished, whether or not items failed along the way. */
+type JobStatus = 'idle' | 'running' | 'done' | 'error';
+/** Declares that an instrument has work too slow to do during a render: what to
+ *  run, when to re-run it, and how each result folds into state. */
+interface JobCapability<TS = unknown, TC = unknown, TItem = unknown> {
+    /** Re-run whenever this value changes, compared element-wise. A job with no
+     *  `key` runs only when something calls `start()`. */
+    key?: (config: TC, state: TS) => readonly unknown[];
+    /** Start on mount and on every `key` change. Default false. */
+    auto?: boolean;
+    run: (args: {
+        config: TC;
+        state: TS;
+        signal: AbortSignal;
+    }) => AsyncIterable<JobEvent<TItem>>;
+    /** Fold one result into state. Called once per `item` event, in arrival order. */
+    onItem: (item: TItem, state: TS) => TS;
+}
+/** One item that failed, and why. */
+interface JobFailure {
+    index: number;
+    error: string;
+}
+/** What `RenderContext.job` exposes. Present only when the instrument declares the
+ *  capability; `undefined` otherwise. */
+interface JobHandle {
+    status: JobStatus;
+    done: number;
+    /** Null until the job reports a total, and forever if it never does. */
+    total: number | null;
+    failures: readonly JobFailure[];
+    /** The error that ended the run, when `status` is `'error'`. */
+    error: string | null;
+    start: () => void;
+    cancel: () => void;
+}
+
+export type { JobHandle as J, JobCapability as a, JobEvent as b, JobFailure as c, JobStatus as d };

package/dist/_dts/useTrialState-BMNIx3Cy.d.ts

@@ -0,0 +1,171 @@
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { StoreApi } from 'zustand/vanilla';
+
+/** A trial's undo history, as snapshots of its state either side of the
+ *  present. */
+interface UndoStack {
+    past: unknown[];
+    future: unknown[];
+}
+/** One trial as the store holds it: which instrument it runs, that
+ *  instrument's config and state, the camera, and the undo history. */
+interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
+    id: string;
+    instrumentName: string;
+    config: TC;
+    state: TS;
+    /** 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 trial's config and state, restorable into any
+ *  trial running the same instrument. */
+interface SavedSnapshot {
+    id: string;
+    name: string;
+    trialId: string;
+    instrumentName: string;
+    config: unknown;
+    state: unknown;
+    savedAt: number;
+}
+/** `auto` follows the OS; the other two are an explicit choice. */
+type LabMode = 'auto' | 'light' | 'dark';
+/** Everything a lab persists: its trials, its saved snapshots, and the
+ *  chosen color mode. */
+interface LabStoreState {
+    trials: TrialRecord[];
+    savedSnapshots: SavedSnapshot[];
+    mode: LabMode;
+    /** 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
+ *  nothing more, so the same store works against localStorage, the URL hash,
+ *  or memory. */
+interface StorageAdapter {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    delete?(key: string): void;
+}
+/** What `useTrialState` hands an instrument: its state and config, with
+ *  a setter for each. */
+interface TrialStateHandle<TS, TC> {
+    state: TS;
+    setState: (next: TS | ((prev: TS) => TS)) => void;
+    config: TC;
+    setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
+}
+/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
+ *  two labs on one origin do not collide. */
+interface CreateLabStoreOptions {
+    storageKey: string;
+    storage: StorageAdapter;
+    initialMode?: LabMode;
+}
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. */
+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. */
+declare const localStorageAdapter: StorageAdapter;
+/** Persist to `sessionStorage` — state survives a reload but not a new tab. */
+declare const sessionStorageAdapter: StorageAdapter;
+/** Persist into the URL fragment, so the page's link carries its state and
+ *  can be shared or bookmarked. */
+declare const urlHashAdapter: StorageAdapter;
+/** An in-memory store, discarded on reload. For tests, and for labs that
+ *  should start fresh every time. */
+declare function createMemoryAdapter(): StorageAdapter;
+/** Persists nothing and reads back nothing. */
+declare const noneAdapter: StorageAdapter;
+
+/** Every mutation a lab store supports: managing trials, saving and
+ *  restoring snapshots, and setting the color mode. */
+interface LabStoreActions {
+    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: 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: (trialId?: string) => SavedSnapshot[];
+    setMode: (mode: LabMode) => void;
+    setLayout: (layout: Record<string, unknown>) => void;
+}
+/** A lab's store: its state and actions, plus the hook instruments use to
+ *  register how their state is serialized. */
+type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
+    registerSerializers: (s: InstrumentSerializers) => void;
+};
+/** Build a lab store, hydrating from storage if anything was saved under the
+ *  same key. Writes back are debounced. */
+declare function createLabStore(options: CreateLabStoreOptions): LabStore;
+
+type LabStoreCtx = {
+    store: LabStore;
+} | null;
+/** Context carrying the lab store. Prefer `useLabStore`; this is exported for
+ *  code that needs to read the context without subscribing. */
+declare const LabStoreContext: react.Context<LabStoreCtx>;
+/** Provides a lab store to its subtree. */
+declare function LabStoreProvider({ store, children, }: {
+    store: LabStore;
+    children: ReactNode;
+}): ReactElement;
+/** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */
+declare function useLabStore(): LabStoreState & ReturnType<LabStore['getState']>;
+/** 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 TrialIdProvider({ trialId, children, }: {
+    trialId: string;
+    children: ReactNode;
+}): ReactElement;
+/** 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
+ *  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 { 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,8 +1,9 @@
 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-JFAYj5Tv.js';
 import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-DJ79Tg5J.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */