@weasel-js/labkit 1.0.4 → 1.2.0

package/dist/job/index.d.ts

@@ -0,0 +1,13 @@
+import { a as JobCapability, J as JobHandle } from '../_dts/types-DJ79Tg5J.js';
+export { b as JobEvent, c as JobFailure, d as JobStatus } from '../_dts/types-DJ79Tg5J.js';
+
+interface UseJobOptions<TS, TC, TItem> {
+    capability: JobCapability<TS, TC, TItem>;
+    config: TC;
+    state: TS;
+    setState: (next: TS | ((prev: TS) => TS)) => void;
+}
+declare function useJob<TS, TC, TItem>({ capability, config, state, setState, }: UseJobOptions<TS, TC, TItem>): JobHandle;
+
+export { JobCapability, JobHandle, useJob };
+export type { UseJobOptions };

package/dist/job/index.js

@@ -0,0 +1,3 @@
+export { useJob } from '../chunk-LN6JDUGB.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/job/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/layers/index.d.ts

@@ -1,8 +1,9 @@
-import { c as LayerDescriptor } from '../_dts/index-CFlDPeZh.js';
-export { L as LayerCapability } from '../_dts/index-CFlDPeZh.js';
+import { d as LayerDescriptor } from '../_dts/index-JFAYj5Tv.js';
+export { L as LayerCapability } from '../_dts/index-JFAYj5Tv.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'react';
 import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-DJ79Tg5J.js';
 
 /** Props for `<LayerList>`. */
 interface LayerListProps {

package/dist/passthrough/weasel-canvas.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Ref } from 'react';
-import { N as Node, V as View, D as DrawCommand, S as Scene, B as Bounds, a as ViewportDims, P as PathDrawCommand } from '../_dts/DrawCommand-BkZztJsW.js';
+import { N as Node, V as View, D as DrawCommand, S as Scene, B as Bounds, a as ViewportDims, P as PathDrawCommand } from '../_dts/DrawCommand-C_XboUpz.js';
 
 /**
  * `renderSceneToCanvas` — substrate for detached, read-only scene views

package/dist/passthrough/weasel-canvas.js

@@ -1,3 +1,3 @@
-export { FALLBACK_FIT_VIEW, MinimapCanvas, SceneViewCanvas, buildSceneViewCommands, computeFitView2 as computeFitView, computeIndicatorCommand, renderSceneToCanvas } from '../chunk-DWV7SFKR.js';
+export { FALLBACK_FIT_VIEW, MinimapCanvas, SceneViewCanvas, buildSceneViewCommands, computeFitView, computeIndicatorCommand, renderSceneToCanvas } from '../chunk-BOHF3PQO.js';
 //# sourceMappingURL=weasel-canvas.js.map
 //# sourceMappingURL=weasel-canvas.js.map

package/dist/passthrough/weasel-ui.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, MutableRefObject, KeyboardEvent, PointerEvent as PointerEvent$1, RefCallback, RefObject } from 'react';
-import { V as View, D as DrawCommand, O as Op, b as NodeId, c as Path, S as Scene, H as History, B as Bounds } from '../_dts/DrawCommand-BkZztJsW.js';
+import { V as View, D as DrawCommand, O as Op, b as NodeId, c as Path, S as Scene, H as History, B as Bounds } from '../_dts/DrawCommand-C_XboUpz.js';
 import { TextFieldProps, ValidationResult, CheckboxProps as CheckboxProps$1, SwitchProps as SwitchProps$1, TabProps as TabProps$1, TabListProps as TabListProps$1, TabPanelProps as TabPanelProps$1, TabsProps as TabsProps$1, RadioProps as RadioProps$1, RadioGroupProps as RadioGroupProps$1, NumberFieldProps as NumberFieldProps$1, SelectProps as SelectProps$1, ListBoxItemProps, ComboBoxProps as ComboBoxProps$1, SliderProps as SliderProps$1, ModalOverlayProps, DialogProps as DialogProps$1 } from 'react-aria-components';
 
 /**
@@ -1082,6 +1082,10 @@ type TrackCtx = {
  * `onInput` fires continuously through a drag; `onChange` fires once when it
  * ends and is the one to write to history.
  *
+ * `stops` are attractors: a drag that passes within a few pixels of one lands
+ * on it, and the arrow keys move stop to stop. `step` still quantizes the
+ * values between them.
+ *
  * `constraint: 'ordered'` keeps thumbs from crossing each other. Supplying
  * `onAddThumb` makes a click on empty track create a thumb, and supplying
  * `onRemoveThumb` lets a right-click or a drag off the track remove one —
@@ -1095,6 +1099,7 @@ type SliderProps<T extends Thumb = Thumb> = {
     min: number;
     max: number;
     step?: number;
+    stops?: number[];
     constraint?: 'free' | 'ordered';
     onAddThumb?: (atValue: number) => T | null;
     onRemoveThumb?: (index: number) => boolean;
@@ -1368,7 +1373,9 @@ interface Dims {
  * @template TData - The data object passed to each draw call.
  */
 interface RenderLayer<TData> {
-    /** Unique identifier used in visibility maps and ordering arrays. */
+    /** Unique identifier used in visibility maps and ordering arrays. When a
+     *  cache is in use, an id must identify the same logical layer across
+     *  frames — reusing it for a different layer can serve cross-layer commands. */
     id: string;
     /** Human-readable name for UI toggles. */
     label: string;
@@ -1386,6 +1393,21 @@ interface RenderLayer<TData> {
      * subset manually with `viewToMat3(view)`.
      */
     draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
+    /**
+     * Optional cache key. When present and a `LayerCommandCache` is supplied to
+     * `drawLayers`, the layer's previous `DrawCommand[]` is reused as long as
+     * every entry is `Object.is`-equal to the previous call's. A layer with no
+     * `deps` rebuilds on every frame.
+     *
+     * **The returned commands must be treated as immutable.** A cached tree is
+     * handed to the renderer again on later frames, so mutating a tree you
+     * previously returned corrupts the cache silently rather than erroring.
+     *
+     * **Screen-space layers are not protected against a stale `view`/`dims`
+     * the way world-space layers are** (see `space` below) — include them in
+     * `deps` if `draw` reads them.
+     */
+    deps?: (data: TData, view: View, dims: Dims) => readonly unknown[];
     /**
      * Whether the layer is shown when no explicit visibility entry exists.
      * Defaults to `true` when absent.
@@ -1676,8 +1698,10 @@ interface InsertAdapter<TNode extends {
         dx: number;
         dy: number;
     };
-    /** Mutator wired by `insertNode`-using ops (kit-side InsertOp). */
-    insertNode(node: TNode): void;
+    /** Mutator wired by `insertNode`-using ops (kit-side InsertOp). `index`
+     *  carries the z-position a delete captured, so undo restores paint order;
+     *  see `SceneAdapter.insertNode`. */
+    insertNode(node: TNode, index?: number): void;
     /** Mutator wired by `setSelection` ops batched alongside paste. */
     setSelection(ids: string[]): void;
     /** Optional: see SceneAdapter.applyOps. */
@@ -4701,8 +4725,7 @@ interface AnchorRenderProps {
  * Per-instance curve-rendering overrides. Currently empty — passing `{}`
  * means "draw the curve", and `false`/`null` means don't.
  */
-interface CurveSettings {
-}
+type CurveSettings = object;
 /** Shades the region between the curve and one edge of the plot. */
 interface FillSettings {
     side: 'below' | 'above';

package/dist/passthrough/weasel-ui.js

@@ -1,4 +1,4 @@
-export { m as ActionBar, r3 as ActionsBar, Ft as Badge, a as Button, o3 as Checkbox, p4 as ComboBox, m3 as ComboBoxItem, F as CurveEditor, u as DataGrid, c3 as Dialog, qe as EDGE_PROFILES, n as Field, u3 as Input, s as KeyCap, c2 as KeySequence, o2 as MINUS_SIGN, f2 as NumberField, r2 as OptionsBar, _ as Plot2D, n4 as PointPlotter, r4 as Powerline, u4 as Radio, l as RadioGroup, l2 as RangeSlider, p3 as Select, h as SelectItem, n2 as Sidebar, o4 as SidebarPanel, m2 as Slider, a3 as Switch, c4 as Tab, s3 as TabList, l3 as TabPanel, o6 as Tabs, r as ToggleBar, o5 as ToolButton, n3 as ToolGroup, _2 as ToolPalette, He as chromaAt, u2 as detectPlatform, p as dlog, r5 as fieldClasses, s2 as formatNumber, d2 as formatShortcut, u5 as formatShortcutParts, o as inferKeycapKind, f as isDebugEnabled, e as keyGlyph, p2 as keySpecFromKey, d as keySpecsFromMods, Ve as oklchToHex, p5 as paintGradientTrack, c as useReorderDragList, a2 as useRovingTabIndex } from '../chunk-BAPZPDDA.js';
-import '../chunk-DWV7SFKR.js';
+export { m as ActionBar, r3 as ActionsBar, Ft as Badge, a as Button, o3 as Checkbox, p4 as ComboBox, m2 as ComboBoxItem, F as CurveEditor, u as DataGrid, c3 as Dialog, qe as EDGE_PROFILES, n as Field, u3 as Input, s as KeyCap, c2 as KeySequence, o2 as MINUS_SIGN, f2 as NumberField, r2 as OptionsBar, _ as Plot2D, n4 as PointPlotter, r4 as Powerline, u4 as Radio, l as RadioGroup, l2 as RangeSlider, p3 as Select, h as SelectItem, n2 as Sidebar, o4 as SidebarPanel, v as Slider, a3 as Switch, c4 as Tab, s3 as TabList, l3 as TabPanel, o6 as Tabs, r as ToggleBar, o5 as ToolButton, n3 as ToolGroup, _2 as ToolPalette, He as chromaAt, u2 as detectPlatform, p as dlog, r5 as fieldClasses, s2 as formatNumber, d2 as formatShortcut, u5 as formatShortcutParts, o as inferKeycapKind, f as isDebugEnabled, e as keyGlyph, p2 as keySpecFromKey, d as keySpecsFromMods, Ve as oklchToHex, p5 as paintGradientTrack, c as useReorderDragList, a2 as useRovingTabIndex } from '../chunk-73KA7WBO.js';
+import '../chunk-BOHF3PQO.js';
 //# sourceMappingURL=weasel-ui.js.map
 //# sourceMappingURL=weasel-ui.js.map

package/dist/state/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InstrumentSerializers, W as WorkspaceRecord, U as UndoStack, S as StorageAdapter } from '../_dts/useExperimentState-D7EQnnwJ.js';
-export { C as CreateLabStoreOptions, E as ExperimentStateHandle, L as LabStore, a as LabStoreActions, b as LabStoreContext, c as LabStoreProvider, d as LabStoreState, e as SavedSnapshot, f as WorkspaceIdContext, g as WorkspaceIdProvider, h as createLabStore, i as createMemoryAdapter, l as localStorageAdapter, n as noneAdapter, s as sessionStorageAdapter, u as urlHashAdapter, j as useExperimentState, k as useLabStore, m as useWorkspaceId } from '../_dts/useExperimentState-D7EQnnwJ.js';
+import { S as SerializedTrial, I as InstrumentSerializers, T as TrialRecord, U as UndoStack, a as StorageAdapter } from '../_dts/useTrialState-BMNIx3Cy.js';
+export { C as CURRENT_DOCUMENT_VERSION, b as CreateLabStoreOptions, L as LabDocument, c as LabStore, d as LabStoreActions, e as LabStoreContext, f as LabStoreProvider, g as LabStoreState, M as Migration, h as SavedSnapshot, i as TrialIdContext, j as TrialIdProvider, k as TrialStateHandle, l as createLabStore, m as createMemoryAdapter, n as labDocumentKey, o as localStorageAdapter, p as noneAdapter, q as quarantineKey, s as sessionStorageAdapter, u as urlHashAdapter, r as useLabStore, t as useTrialId, v as useTrialState } from '../_dts/useTrialState-BMNIx3Cy.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import 'zustand/vanilla';
@@ -14,19 +14,19 @@ declare function encodeUrlHash(value: string): string;
 declare function decodeUrlHash(hash: string): string | null;
 /** A fresh, empty undo history. */
 declare function emptyUndoStack(): UndoStack;
-/** Serialize workspaces for storage, running each instrument's own serializer
+/** Serialize trials for storage, running each instrument's own serializer
  *  over its state. Undo history is deliberately dropped — it does not survive
  *  a reload. */
-declare function serializeWorkspaces(workspaces: WorkspaceRecord[], serializers: InstrumentSerializers): string;
-/** Rebuild workspaces from storage, running each instrument's deserializer
+declare function serializeTrials(trials: TrialRecord[], serializers: InstrumentSerializers): SerializedTrial[];
+/** Rebuild trials from storage, running each instrument's deserializer
  *  over its state and starting each with an empty undo history. Returns an
  *  empty list rather than throwing on malformed input. */
-declare function deserializeWorkspaces(raw: string, deserializers: InstrumentSerializers): WorkspaceRecord[];
+declare function deserializeTrials(records: SerializedTrial[], deserializers: InstrumentSerializers): TrialRecord[];
 
 /** Props for `<SingletonExperimentProvider>`. */
 interface SingletonExperimentProviderProps<TS, TC> {
-    /** Stable id for the synthetic workspace; also doubles as the
-     *  WorkspaceIdContext value. */
+    /** Stable id for the synthetic trial; also doubles as the
+     *  TrialIdContext value. */
     id: string;
     initialConfig: TC;
     initialState: TS;
@@ -35,12 +35,12 @@ interface SingletonExperimentProviderProps<TS, TC> {
     children: ReactNode;
 }
 /**
- * One-workspace `<Lab>` substitute for single-screen experiments. Mounts
- * a `LabStoreProvider` + `WorkspaceIdProvider` with one synthetic
- * workspace, so `useExperimentState` works without going through the
+ * One-trial `<Lab>` substitute for single-screen experiments. Mounts
+ * a `LabStoreProvider` + `TrialIdProvider` with one synthetic
+ * trial, so `useTrialState` works without going through the
  * full `<Lab instruments={...}>` runtime.
  */
 declare function SingletonExperimentProvider<TS, TC>({ id, initialConfig, initialState, storage, storageKey, children, }: SingletonExperimentProviderProps<TS, TC>): react_jsx_runtime.JSX.Element;
 
-export { InstrumentSerializers, SingletonExperimentProvider, StorageAdapter, UndoStack, WorkspaceRecord, decodeUrlHash, deserializeWorkspaces, emptyUndoStack, encodeUrlHash, labStorageKey, serializeWorkspaces };
+export { InstrumentSerializers, SerializedTrial, SingletonExperimentProvider, StorageAdapter, TrialRecord, UndoStack, decodeUrlHash, deserializeTrials, emptyUndoStack, encodeUrlHash, labStorageKey, serializeTrials };
 export type { SingletonExperimentProviderProps };

package/dist/state/index.js

@@ -1,5 +1,5 @@
-import { createLabStore, LabStoreProvider, WorkspaceIdProvider } from '../chunk-KSTEW2AF.js';
-export { LabStoreContext, LabStoreProvider, WorkspaceIdContext, WorkspaceIdProvider, createLabStore, createMemoryAdapter, decodeUrlHash, deserializeWorkspaces, emptyUndoStack, encodeUrlHash, labStorageKey, localStorageAdapter, noneAdapter, serializeWorkspaces, sessionStorageAdapter, urlHashAdapter, useExperimentState, useLabStore, useWorkspaceId } from '../chunk-KSTEW2AF.js';
+import { createLabStore, LabStoreProvider, TrialIdProvider } from '../chunk-VUU5UXHE.js';
+export { CURRENT_DOCUMENT_VERSION, LabStoreContext, LabStoreProvider, TrialIdContext, TrialIdProvider, createLabStore, createMemoryAdapter, decodeUrlHash, deserializeTrials, emptyUndoStack, encodeUrlHash, labDocumentKey, labStorageKey, localStorageAdapter, noneAdapter, quarantineKey, serializeTrials, sessionStorageAdapter, urlHashAdapter, useLabStore, useTrialId, useTrialState } from '../chunk-VUU5UXHE.js';
 import { useRef } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
@@ -15,8 +15,8 @@ function SingletonExperimentProvider({
   const storeRef = useRef(null);
   if (storeRef.current === null) {
     const store = createLabStore({ storageKey, storage });
-    if (!store.getState().workspaces.some((w) => w.id === id)) {
-      store.getState().addWorkspace({
+    if (!store.getState().trials.some((w) => w.id === id)) {
+      store.getState().addTrial({
         id,
         instrumentName: SINGLETON_INSTRUMENT,
         config: initialConfig,
@@ -26,7 +26,7 @@ function SingletonExperimentProvider({
     }
     storeRef.current = store;
   }
-  return /* @__PURE__ */ jsx(LabStoreProvider, { store: storeRef.current, children: /* @__PURE__ */ jsx(WorkspaceIdProvider, { workspaceId: id, children }) });
+  return /* @__PURE__ */ jsx(LabStoreProvider, { store: storeRef.current, children: /* @__PURE__ */ jsx(TrialIdProvider, { trialId: id, children }) });
 }
 
 export { SingletonExperimentProvider };

package/dist/state/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/state/SingletonExperiment.tsx"],"names":[],"mappings":";;;;;AAKA,IAAM,oBAAA,GAAuB,eAAA;AAoBtB,SAAS,2BAAA,CAAoC;AAAA,EAClD,EAAA;AAAA,EACA,aAAA;AAAA,EACA,YAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF,CAAA,EAA6C;AAC3C,EAAA,MAAM,QAAA,GAAW,OAAwB,IAAI,CAAA;AAC7C,EAAA,IAAI,QAAA,CAAS,YAAY,IAAA,EAAM;AAC7B,IAAA,MAAM,KAAA,GAAQ,cAAA,CAAe,EAAE,UAAA,EAAY,SAAS,CAAA;AACpD,IAAA,IAAI,CAAC,KAAA,CAAM,QAAA,EAAS,CAAE,UAAA,CAAW,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,EAAA,KAAO,EAAE,CAAA,EAAG;AACzD,MAAA,KAAA,CAAM,QAAA,GAAW,YAAA,CAAa;AAAA,QAC5B,EAAA;AAAA,QACA,cAAA,EAAgB,oBAAA;AAAA,QAChB,MAAA,EAAQ,aAAA;AAAA,QACR,KAAA,EAAO,YAAA;AAAA,QACP,IAAA,EAAM,EAAE,IAAA,EAAM,CAAA,EAAG,GAAA,EAAK,EAAE,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,EAAE;AAAE,OACtC,CAAA;AAAA,IACH;AACA,IAAA,QAAA,CAAS,OAAA,GAAU,KAAA;AAAA,EACrB;AACA,EAAA,uBACE,GAAA,CAAC,gBAAA,EAAA,EAAiB,KAAA,EAAO,QAAA,CAAS,OAAA,EAChC,8BAAC,mBAAA,EAAA,EAAoB,WAAA,EAAa,EAAA,EAAK,QAAA,EAAS,CAAA,EAClD,CAAA;AAEJ","file":"index.js","sourcesContent":["import { type ReactNode, useRef } from 'react';\nimport { LabStoreProvider, WorkspaceIdProvider } from './context';\nimport { createLabStore, type LabStore } from './store';\nimport type { StorageAdapter } from './types';\n\nconst SINGLETON_INSTRUMENT = '__singleton__';\n\n/** Props for `<SingletonExperimentProvider>`. */\nexport interface SingletonExperimentProviderProps<TS, TC> {\n  /** Stable id for the synthetic workspace; also doubles as the\n   *  WorkspaceIdContext value. */\n  id: string;\n  initialConfig: TC;\n  initialState: TS;\n  storage: StorageAdapter;\n  storageKey: string;\n  children: ReactNode;\n}\n\n/**\n * One-workspace `<Lab>` substitute for single-screen experiments. Mounts\n * a `LabStoreProvider` + `WorkspaceIdProvider` with one synthetic\n * workspace, so `useExperimentState` works without going through the\n * full `<Lab instruments={...}>` runtime.\n */\nexport function SingletonExperimentProvider<TS, TC>({\n  id,\n  initialConfig,\n  initialState,\n  storage,\n  storageKey,\n  children,\n}: SingletonExperimentProviderProps<TS, TC>) {\n  const storeRef = useRef<LabStore | null>(null);\n  if (storeRef.current === null) {\n    const store = createLabStore({ storageKey, storage });\n    if (!store.getState().workspaces.some((w) => w.id === id)) {\n      store.getState().addWorkspace({\n        id,\n        instrumentName: SINGLETON_INSTRUMENT,\n        config: initialConfig,\n        state: initialState,\n        view: { zoom: 1, pan: { x: 0, y: 0 } },\n      });\n    }\n    storeRef.current = store;\n  }\n  return (\n    <LabStoreProvider store={storeRef.current}>\n      <WorkspaceIdProvider workspaceId={id}>{children}</WorkspaceIdProvider>\n    </LabStoreProvider>\n  );\n}\n"]}
+{"version":3,"sources":["../../src/state/SingletonExperiment.tsx"],"names":[],"mappings":";;;;;AAKA,IAAM,oBAAA,GAAuB,eAAA;AAoBtB,SAAS,2BAAA,CAAoC;AAAA,EAClD,EAAA;AAAA,EACA,aAAA;AAAA,EACA,YAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF,CAAA,EAA6C;AAC3C,EAAA,MAAM,QAAA,GAAW,OAAwB,IAAI,CAAA;AAC7C,EAAA,IAAI,QAAA,CAAS,YAAY,IAAA,EAAM;AAC7B,IAAA,MAAM,KAAA,GAAQ,cAAA,CAAe,EAAE,UAAA,EAAY,SAAS,CAAA;AACpD,IAAA,IAAI,CAAC,KAAA,CAAM,QAAA,EAAS,CAAE,MAAA,CAAO,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,EAAA,KAAO,EAAE,CAAA,EAAG;AACrD,MAAA,KAAA,CAAM,QAAA,GAAW,QAAA,CAAS;AAAA,QACxB,EAAA;AAAA,QACA,cAAA,EAAgB,oBAAA;AAAA,QAChB,MAAA,EAAQ,aAAA;AAAA,QACR,KAAA,EAAO,YAAA;AAAA,QACP,IAAA,EAAM,EAAE,IAAA,EAAM,CAAA,EAAG,GAAA,EAAK,EAAE,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,EAAE;AAAE,OACtC,CAAA;AAAA,IACH;AACA,IAAA,QAAA,CAAS,OAAA,GAAU,KAAA;AAAA,EACrB;AACA,EAAA,uBACE,GAAA,CAAC,gBAAA,EAAA,EAAiB,KAAA,EAAO,QAAA,CAAS,OAAA,EAChC,8BAAC,eAAA,EAAA,EAAgB,OAAA,EAAS,EAAA,EAAK,QAAA,EAAS,CAAA,EAC1C,CAAA;AAEJ","file":"index.js","sourcesContent":["import { type ReactNode, useRef } from 'react';\nimport { LabStoreProvider, TrialIdProvider } from './context';\nimport { createLabStore, type LabStore } from './store';\nimport type { StorageAdapter } from './types';\n\nconst SINGLETON_INSTRUMENT = '__singleton__';\n\n/** Props for `<SingletonExperimentProvider>`. */\nexport interface SingletonExperimentProviderProps<TS, TC> {\n  /** Stable id for the synthetic trial; also doubles as the\n   *  TrialIdContext value. */\n  id: string;\n  initialConfig: TC;\n  initialState: TS;\n  storage: StorageAdapter;\n  storageKey: string;\n  children: ReactNode;\n}\n\n/**\n * One-trial `<Lab>` substitute for single-screen experiments. Mounts\n * a `LabStoreProvider` + `TrialIdProvider` with one synthetic\n * trial, so `useTrialState` works without going through the\n * full `<Lab instruments={...}>` runtime.\n */\nexport function SingletonExperimentProvider<TS, TC>({\n  id,\n  initialConfig,\n  initialState,\n  storage,\n  storageKey,\n  children,\n}: SingletonExperimentProviderProps<TS, TC>) {\n  const storeRef = useRef<LabStore | null>(null);\n  if (storeRef.current === null) {\n    const store = createLabStore({ storageKey, storage });\n    if (!store.getState().trials.some((w) => w.id === id)) {\n      store.getState().addTrial({\n        id,\n        instrumentName: SINGLETON_INSTRUMENT,\n        config: initialConfig,\n        state: initialState,\n        view: { zoom: 1, pan: { x: 0, y: 0 } },\n      });\n    }\n    storeRef.current = store;\n  }\n  return (\n    <LabStoreProvider store={storeRef.current}>\n      <TrialIdProvider trialId={id}>{children}</TrialIdProvider>\n    </LabStoreProvider>\n  );\n}\n"]}

package/dist/styles.css

@@ -356,15 +356,15 @@
   letter-spacing: 0.01em;
   line-height: 1.2;
 }
-.lk-workspace-grid {
+.lk-workspace {
   min-height: 0;
 }
-.lk-workspace-tile {
+.lk-trial-tile {
   display: flex;
   flex-direction: column;
   height: 100%;
 }
-.lk-workspace-tile__grip {
+.lk-trial-tile__grip {
   flex: 0 0 auto;
   display: flex;
   align-items: center;
@@ -374,17 +374,17 @@
   border-radius: var(--wzl-radius-sm) var(--wzl-radius-sm) 0 0;
   background: var(--wzl-surface-sunken);
 }
-.lk-workspace-tile__grip:active {
+.lk-trial-tile__grip:active {
   cursor: grabbing;
 }
-.lk-workspace-tile__grip-dots {
+.lk-trial-tile__grip-dots {
   width: 28px;
   height: 3px;
   border-radius: 999px;
   background: var(--wzl-fg-muted);
   opacity: 0.5;
 }
-.lk-workspace-tile__body {
+.lk-trial-tile__body {
   flex: 1;
   min-height: 0;
 }
@@ -567,10 +567,18 @@
 .lk-scale-indicator-label {
   white-space: nowrap;
 }
+html:has(.lk-lab),
+body:has(.lk-lab) {
+  margin: 0;
+  height: 100%;
+}
+body:has(.lk-lab) > :has(> .lk-lab) {
+  height: 100%;
+}
 .lk-lab {
   height: 100%;
 }
-.lk-workspace {
+.lk-trial {
   display: flex;
   flex-direction: column;
   height: 100%;
@@ -579,27 +587,27 @@
   border-radius: var(--wzl-radius-md);
   overflow: hidden;
 }
-.lk-workspace__body {
+.lk-trial__body {
   display: flex;
   flex: 1;
   overflow: hidden;
 }
-.lk-workspace__sidebar {
+.lk-trial__sidebar {
   flex-shrink: 0;
 }
-.lk-workspace__content {
+.lk-trial__content {
   flex: 1;
   overflow: auto;
 }
-.lk-workspace__toolbar {
+.lk-trial__toolbar {
   flex-shrink: 0;
   border-bottom: 1px solid var(--wzl-line-subtle);
 }
-.lk-workspace__status {
+.lk-trial__status {
   flex-shrink: 0;
   border-top: 1px solid var(--wzl-line-subtle);
 }
-.lk-workspace--unknown {
+.lk-trial--unknown {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -619,6 +627,16 @@
   color: var(--wzl-fg-muted);
   font-size: var(--wzl-font-size-sm);
 }
+.lk-trial__job {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 0.75rem;
+}
+.lk-trial__job-failures,
+.lk-trial__job-error {
+  color: var(--wsl-color-danger, #c0392b);
+}
 .lk-control-panel {
   display: flex;
   flex-direction: column;

package/dist/surface/index.d.ts

@@ -0,0 +1,77 @@
+import * as react from 'react';
+
+/** A box in CSS pixels, measured from the surface's own top-left corner. */
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The subset of `DOMRect` this package reads. Accepting the subset rather than
+ *  `DOMRect` is what lets the pure functions be tested without a DOM. */
+interface Box {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+/** Every tile's box expressed against the container's origin. */
+declare function composeRects(container: Box, tiles: ReadonlyMap<string, Box>): Map<string, Rect>;
+declare function rectsEqual(a: Rect | undefined, b: Rect): boolean;
+
+/**
+ * A DOM rect as a GL viewport rect: origin at the bottom-left, every edge snapped
+ * to the device-pixel grid. Still CSS pixels, because three.js applies its own
+ * pixel ratio — snapping here is what stops a tile and its neighbour rounding
+ * apart and leaving a hairline column between them.
+ */
+declare function toDeviceRect(rect: Rect, surfaceHeight: number, dpr: number): Rect;
+
+/** What a surface owner is handed once per animation frame. `rects` carries every
+ *  tile, not only the dirty ones: a scissored draw has to know where it is drawing
+ *  relative to a surface that may have resized under it. */
+interface SurfaceFrame {
+    dirty: ReadonlySet<string>;
+    rects: ReadonlyMap<string, Rect>;
+    dpr: number;
+    size: {
+        width: number;
+        height: number;
+    };
+}
+/** The invalidators and the two ref callbacks that publish geometry. */
+interface SurfaceHandle {
+    /** Mark one tile for redraw. */
+    invalidate: (id: string) => void;
+    /** Mark every tile — what a resize or a tile-set change means. */
+    invalidateAll: () => void;
+    /** Re-measure before the next frame. The escape hatch for a host that knows it
+     *  moved something a ResizeObserver cannot see. */
+    invalidateRects: () => void;
+    registerTile: (id: string, el: HTMLElement | null) => void;
+    containerRef: (el: HTMLElement | null) => void;
+}
+interface UseTiledSurfaceOptions {
+    onFrame: (frame: SurfaceFrame) => void;
+}
+declare function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHandle;
+
+/** Null when no surface owner is above — a lab with no shared surface at all. */
+declare const SurfaceContext: react.Context<SurfaceHandle | null>;
+
+/** The surface above, or null. Use this where a surface is genuinely optional. */
+declare function useSurfaceOptional(): SurfaceHandle | null;
+/** The surface above. Throws where a caller cannot work without one. */
+declare function useSurface(): SurfaceHandle;
+/**
+ * A ref callback that publishes this element's rect to the surface under `id`.
+ *
+ * Attach it to whichever element the surface should draw into — that is not
+ * necessarily the trial's own element, since a trial may hold a drawn pane beside
+ * an undrawn one, or none at all.
+ */
+declare function useSurfaceTile(id: string): (el: HTMLElement | null) => void;
+
+export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface };
+export type { Box, Rect, SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions };

package/dist/surface/index.js

@@ -0,0 +1,3 @@
+export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-THBG7FQZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/surface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/ui/layers/index.js

@@ -1,5 +1,5 @@
-export { LayerStack } from '../../chunk-DEWXYFEU.js';
-import '../../chunk-BAPZPDDA.js';
-import '../../chunk-DWV7SFKR.js';
+export { LayerStack } from '../../chunk-G5TJVQQT.js';
+import '../../chunk-73KA7WBO.js';
+import '../../chunk-BOHF3PQO.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,6 +1,7 @@
-export { U as UndoCapability } from '../_dts/index-CFlDPeZh.js';
+export { U as UndoCapability } from '../_dts/index-JFAYj5Tv.js';
 import 'react';
 import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-DJ79Tg5J.js';
 
 /** A subscriber to a named event. */
 type EventListener = () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -55,6 +55,14 @@
       "types": "./dist/state/index.d.ts",
       "import": "./dist/state/index.js"
     },
+    "./surface": {
+      "types": "./dist/surface/index.d.ts",
+      "import": "./dist/surface/index.js"
+    },
+    "./job": {
+      "types": "./dist/job/index.d.ts",
+      "import": "./dist/job/index.js"
+    },
     "./weasel-ui": {
       "types": "./dist/passthrough/weasel-ui.d.ts",
       "import": "./dist/passthrough/weasel-ui.js"

package/src/canvas/AGENTS.md

@@ -2,6 +2,14 @@
 
 The `src/canvas/` directory implements the layered canvas primitive used by the `canvas` instrument capability.
 
+For a renderer labkit does not own — three.js, raw WebGL, anything with its own
+render loop — see `src/surface/AGENTS.md` instead. `CanvasStack` is 2D and
+schedules its own layers; a foreign renderer wants rects and dirtiness only.
+
+`useOrbit` also lives here, as the 3D peer of `usePanZoom`. It produces a trial
+view (`{ yaw, pitch, distance, target }`) rather than a matrix — turning that
+into a camera is the host's job.
+
 ## Files
 
 | File | Role |
@@ -32,12 +40,12 @@ interface CanvasStackProps {
 
 1. The container measures itself with `ResizeObserver` and reports `{width, height, dpr}`.
 2. `useLayerScheduler` watches `layers`, `view`, and `size`, and on any change schedules a single `requestAnimationFrame` redraw.
-3. Each layer's `render(ctx, view)` is called with a fresh transform: the canvas is sized to `width * dpr × height * dpr` so coordinates are in CSS pixels.
+3. Each layer's `render(ctx, view)` is called with a fresh transform: the canvas is sized to `width * dpr × height * dpr` so coordinates are in CSS pixels. A `CanvasLayerDescriptor` gets the whole `view` and places its own geometry; an instrument's `CanvasLayer.draw` is called with the camera already applied — see below.
 4. Layers with `visible: false` are skipped and their canvas is `display: none` (DOM is preserved to avoid remounts).
 
 ## Adding a new layer type
 
-A layer is defined by the instrument's `canvas.layers[]` (type `CanvasLayer`), then translated to a `CanvasLayerDescriptor` inside `Workspace.tsx` before being passed to `<CanvasStack>`. To add a layer, push it into `instrument.canvas.layers`:
+A layer is defined by the instrument's `canvas.layers[]` (type `CanvasLayer`), then translated to a `CanvasLayerDescriptor` inside `Trial.tsx` before being passed to `<CanvasStack>`. To add a layer, push it into `instrument.canvas.layers`:
 
 ```ts
 canvas: {
@@ -50,6 +58,10 @@ canvas: {
 }
 ```
 
+`draw` receives the context with the camera already applied, so its coordinates are world coordinates — `Trial.tsx` translates by `view.pan` and scales by `view.zoom` before calling it. `zoom` is still passed so a layer can keep line widths and handle sizes from growing: divide by it (`ctx.lineWidth = 1 / zoom`).
+
+That is the difference between the two layer types. The lower-level `CanvasLayerDescriptor.render(ctx, view)` gets the raw view and an untransformed context, which is what screen-space chrome wants.
+
 Layer order in the array = paint order (first drawn = bottom).
 
 ## Overlay (children)

package/src/canvas/useOrbit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { clampPitch, orbitAfterDrag, orbitAfterWheel, PITCH_LIMIT, wrapYaw } from './useOrbit';
+
+const view = { yaw: 0, pitch: 0, distance: 5, target: { x: 0, y: 0, z: 0 } };
+
+describe('clampPitch', () => {
+  it('stops just short of the poles, where azimuth becomes undefined', () => {
+    expect(clampPitch(Math.PI)).toBeCloseTo(PITCH_LIMIT);
+    expect(clampPitch(-Math.PI)).toBeCloseTo(-PITCH_LIMIT);
+    expect(PITCH_LIMIT).toBeLessThan(Math.PI / 2);
+  });
+
+  it('leaves an in-range pitch alone', () => {
+    expect(clampPitch(0.3)).toBe(0.3);
+  });
+});
+
+describe('wrapYaw', () => {
+  it('wraps into (-PI, PI] so a value cannot drift without bound', () => {
+    expect(wrapYaw(3 * Math.PI)).toBeCloseTo(Math.PI);
+    expect(wrapYaw(-3 * Math.PI)).toBeCloseTo(Math.PI);
+    expect(wrapYaw(0.5)).toBeCloseTo(0.5);
+  });
+
+  it('keeps a full turn equivalent to no turn', () => {
+    expect(wrapYaw(2 * Math.PI)).toBeCloseTo(0);
+  });
+});
+
+describe('orbitAfterDrag', () => {
+  it('turns horizontal movement into yaw and vertical into pitch', () => {
+    const next = orbitAfterDrag(view, 100, 50);
+    expect(next.yaw).not.toBe(view.yaw);
+    expect(next.pitch).not.toBe(view.pitch);
+  });
+
+  it('is absolute against the drag start, so re-applying does not compound', () => {
+    const once = orbitAfterDrag(view, 100, 50);
+    const twice = orbitAfterDrag(view, 100, 50);
+    expect(twice).toEqual(once);
+  });
+
+  it('clamps pitch rather than tumbling past the pole', () => {
+    const next = orbitAfterDrag(view, 0, 100_000);
+    expect(Math.abs(next.pitch)).toBeLessThanOrEqual(PITCH_LIMIT);
+  });
+
+  it('leaves distance and target untouched', () => {
+    const next = orbitAfterDrag(view, 100, 50);
+    expect(next.distance).toBe(view.distance);
+    expect(next.target).toEqual(view.target);
+  });
+});
+
+describe('orbitAfterWheel', () => {
+  it('moves the camera in and out', () => {
+    expect(orbitAfterWheel(view, 100, 0.5, 50).distance).toBeGreaterThan(view.distance);
+    expect(orbitAfterWheel(view, -100, 0.5, 50).distance).toBeLessThan(view.distance);
+  });
+
+  it('is multiplicative, so a step feels the same at every distance', () => {
+    const near = orbitAfterWheel({ ...view, distance: 2 }, 100, 0.5, 50);
+    const far = orbitAfterWheel({ ...view, distance: 20 }, 100, 0.5, 50);
+    expect(far.distance / 20).toBeCloseTo(near.distance / 2);
+  });
+
+  it('honours its bounds', () => {
+    expect(orbitAfterWheel(view, 100_000, 0.5, 50).distance).toBe(50);
+    expect(orbitAfterWheel(view, -100_000, 0.5, 50).distance).toBe(0.5);
+  });
+});