@weasel-js/labkit 1.1.0 → 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 { d as LayerDescriptor } from '../_dts/index-iAP6XbH3.js';
-export { L as LayerCapability } from '../_dts/index-iAP6XbH3.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-DJLDIRFN.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';
 
 /**
@@ -1373,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;
@@ -1391,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.
@@ -4708,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, 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-C6GJKPUI.js';
-import '../chunk-DJLDIRFN.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 { S as SerializedTrial, I as InstrumentSerializers, T as TrialRecord, U as UndoStack, a as StorageAdapter } from '../_dts/useTrialState-DYe2vUwN.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-DYe2vUwN.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';

package/dist/state/index.js

@@ -1,5 +1,5 @@
-import { createLabStore, LabStoreProvider, TrialIdProvider } from '../chunk-3TYUJR7Z.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-3TYUJR7Z.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';
 

package/dist/styles.css

@@ -627,6 +627,16 @@ body:has(.lk-lab) > :has(> .lk-lab) {
   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-NRKWVTVT.js';
-import '../../chunk-C6GJKPUI.js';
-import '../../chunk-DJLDIRFN.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-iAP6XbH3.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.1.0",
+  "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 |

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);
+  });
+});

package/src/canvas/useOrbit.ts

@@ -0,0 +1,149 @@
+import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
+
+/** A point in the space the instrument works in. */
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** An orbit camera as a trial view: where it looks from, and what it looks at.
+ *  labkit does not turn this into a matrix — the host's renderer does. */
+export interface OrbitView {
+  yaw: number;
+  pitch: number;
+  distance: number;
+  target: Vec3;
+}
+
+/** Just short of the pole. At exactly ±PI/2 the azimuth is undefined and the
+ *  camera rolls, which reads as the model jumping rather than as a limit. */
+export const PITCH_LIMIT = Math.PI / 2 - 0.01;
+
+const YAW_PER_PX = 0.008;
+const PITCH_PER_PX = 0.008;
+const DISTANCE_PER_NOTCH = 0.0015;
+const DRAG_THRESHOLD = 3;
+
+export function clampPitch(pitch: number): number {
+  return Math.min(PITCH_LIMIT, Math.max(-PITCH_LIMIT, pitch));
+}
+
+export function wrapYaw(yaw: number): number {
+  const wrapped = ((((yaw + Math.PI) % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI)) - Math.PI;
+  return wrapped === -Math.PI ? Math.PI : wrapped;
+}
+
+/** The view a drag of (dx, dy) from `start` produces. Absolute against the drag
+ *  start, so it can be re-applied any number of times without compounding. */
+export function orbitAfterDrag(start: OrbitView, dx: number, dy: number): OrbitView {
+  return {
+    ...start,
+    yaw: wrapYaw(start.yaw + dx * YAW_PER_PX),
+    pitch: clampPitch(start.pitch + dy * PITCH_PER_PX),
+  };
+}
+
+/** Multiplicative, so one notch covers the same proportion of the distance
+ *  whether the camera is near or far. */
+export function orbitAfterWheel(
+  view: OrbitView,
+  deltaY: number,
+  minDistance: number,
+  maxDistance: number,
+): OrbitView {
+  const factor = Math.exp(deltaY * DISTANCE_PER_NOTCH);
+  return {
+    ...view,
+    distance: Math.min(maxDistance, Math.max(minDistance, view.distance * factor)),
+  };
+}
+
+export interface UseOrbitOptions {
+  view: OrbitView;
+  onViewChange: (v: OrbitView) => void;
+  /** Restored on double-click. Defaults to the view the hook first saw. */
+  home?: OrbitView;
+  minDistance?: number;
+  maxDistance?: number;
+}
+
+export interface OrbitHandlers {
+  onWheel: (e: WheelEvent<HTMLElement>) => void;
+  onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+  onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+  onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+  onDoubleClick: () => void;
+  isDragging: () => boolean;
+}
+
+interface DragState {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  startView: OrbitView;
+  moved: boolean;
+}
+
+/** Pointer gestures over an orbit view: drag to turn, wheel or pinch to dolly,
+ *  double-click to go home. The 3D peer of `usePanZoom`. */
+export function useOrbit({
+  view,
+  onViewChange,
+  home,
+  minDistance = 0.1,
+  maxDistance = 1000,
+}: UseOrbitOptions): OrbitHandlers {
+  const dragRef = useRef<DragState | null>(null);
+  const viewRef = useRef(view);
+  viewRef.current = view;
+  const homeRef = useRef(home ?? view);
+  if (home) homeRef.current = home;
+
+  const onWheel = useCallback(
+    (e: WheelEvent<HTMLElement>) => {
+      e.preventDefault();
+      onViewChange(orbitAfterWheel(viewRef.current, e.deltaY, minDistance, maxDistance));
+    },
+    [onViewChange, minDistance, maxDistance],
+  );
+
+  const onPointerDown = useCallback((e: PointerEvent<HTMLElement>) => {
+    if (e.button !== 0) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragRef.current = {
+      pointerId: e.pointerId,
+      startX: e.clientX,
+      startY: e.clientY,
+      startView: viewRef.current,
+      moved: false,
+    };
+  }, []);
+
+  const onPointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => {
+      const drag = dragRef.current;
+      if (!drag || drag.pointerId !== e.pointerId) return;
+      const dx = e.clientX - drag.startX;
+      const dy = e.clientY - drag.startY;
+      if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+      drag.moved = true;
+      onViewChange(orbitAfterDrag(drag.startView, dx, dy));
+    },
+    [onViewChange],
+  );
+
+  const onPointerUp = useCallback((e: PointerEvent<HTMLElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== e.pointerId) return;
+    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+    dragRef.current = null;
+  }, []);
+
+  const onDoubleClick = useCallback(() => onViewChange(homeRef.current), [onViewChange]);
+  const isDragging = useCallback(() => dragRef.current?.moved === true, []);
+
+  return { onWheel, onPointerDown, onPointerMove, onPointerUp, onDoubleClick, isDragging };
+}

package/src/index.test.ts

@@ -50,3 +50,21 @@ describe('public export surface', () => {
     expect(labkit).toHaveProperty('useTrialId');
   });
 });
+
+describe('surface, job and orbit entry points', () => {
+  it('are reachable from the package root', async () => {
+    const kit = await import('./index');
+    expect(typeof kit.useTiledSurface).toBe('function');
+    expect(typeof kit.useSurfaceTile).toBe('function');
+    expect(typeof kit.useSurface).toBe('function');
+    expect(typeof kit.useSurfaceOptional).toBe('function');
+    expect(typeof kit.toDeviceRect).toBe('function');
+    expect(typeof kit.composeRects).toBe('function');
+    expect(typeof kit.useOrbit).toBe('function');
+    expect(typeof kit.orbitAfterDrag).toBe('function');
+    expect(typeof kit.useJob).toBe('function');
+    expect(typeof kit.as2DView).toBe('function');
+    expect(kit.SurfaceContext).toBeDefined();
+    expect(kit.DEFAULT_VIEW).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });
+  });
+});

package/src/index.ts

@@ -1,5 +1,14 @@
 export type { CanvasLayerDescriptor, CanvasStackContextValue, CanvasStackProps } from './canvas';
 export { CanvasStack, CanvasStackContext, screenToWorld, worldToScreen } from './canvas';
+export type { OrbitHandlers, OrbitView, UseOrbitOptions, Vec3 } from './canvas/useOrbit';
+export {
+  clampPitch,
+  orbitAfterDrag,
+  orbitAfterWheel,
+  PITCH_LIMIT,
+  useOrbit,
+  wrapYaw,
+} from './canvas/useOrbit';
 export { ControlPanel } from './controls/ControlPanel';
 export type {
   CheckboxField,
@@ -35,6 +44,7 @@ export type {
 } from './instrument/types';
 export type { ValidationResult } from './instrument/validateConfigSchema';
 export { validateConfigSchema } from './instrument/validateConfigSchema';
+export * from './job';
 export * from './lab';
 export type { LayerListProps } from './layers';
 export { LayerList } from './layers';
@@ -68,6 +78,9 @@ export type {
   UndoStack,
 } from './state/types';
 export { useTrialState } from './state/useTrialState';
+export type { ViewTransform2D } from './state/view';
+export { as2DView, DEFAULT_VIEW } from './state/view';
+export * from './surface';
 export { interstellarTheme } from './theme/interstellar';
 export * from './trial';
 export * from './ui/layers';

package/src/instrument/SineWave.smoke.test.tsx

@@ -1,6 +1,7 @@
 import { render } from '@testing-library/react';
 import type { ReactElement } from 'react';
 import { describe, expect, it, vi } from 'vitest';
+import { DEFAULT_VIEW } from '../state/view';
 import { defineInstrument } from './defineInstrument';
 import type { RenderContext } from './types';
 import { validateConfigSchema } from './validateConfigSchema';
@@ -85,7 +86,7 @@ describe('SineWave instrument smoke test', () => {
       config: SineWaveInstrument.defaultConfig(),
       setState: vi.fn(),
       setConfig: vi.fn(),
-      trial: { id: 'w', zoom: 1, setZoom: vi.fn() },
+      trial: { id: 'w', view: DEFAULT_VIEW, setView: vi.fn(), zoom: 1, setZoom: vi.fn() },
       emit: vi.fn(),
     };
     const { container } = render(SineWaveInstrument.render(ctx) as ReactElement);

package/src/instrument/types.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { ConfigField } from '../controls/types';
+import type { JobCapability, JobHandle } from '../job/types';
 
 /** What an instrument's `render` is handed: its state and config, the setters
  *  for both, the trial it is mounted in, and a way to emit named events. */
@@ -10,10 +11,18 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   setConfig: (key: keyof TC, value: unknown) => void;
   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.
@@ -97,10 +106,13 @@ export 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. */
 // biome-ignore lint/suspicious/noExplicitAny: see above
-export type InstrumentList = readonly Instrument<any, any>[];
+export type InstrumentList = readonly Instrument<any, any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any -- contravariant TC; see above

package/src/job/index.ts

@@ -0,0 +1,3 @@
+export type { JobCapability, JobEvent, JobFailure, JobHandle, JobStatus } from './types';
+export type { UseJobOptions } from './useJob';
+export { useJob } from './useJob';