@weasel-js/labkit 1.0.4 → 1.2.0

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/dragdrop/dragDrop.test.tsx

@@ -34,19 +34,16 @@ const originalGetBoundingClientRect = HTMLElement.prototype.getBoundingClientRec
 function StateProbe({ onState }: { onState: (state: DropState) => void }) {
   const ctx = useContext(LabStoreContext);
   const ws = useStore(
-    ctx?.store ?? ({ getState: () => ({ workspaces: [] }) } as never),
-    (s) => (s as { workspaces: { state: unknown }[] }).workspaces[0],
+    ctx?.store ?? ({ getState: () => ({ trials: [] }) } as never),
+    (s) => (s as { trials: { state: unknown }[] }).trials[0],
   );
   if (ws) onState(ws.state as DropState);
   return null;
 }
 
-// biome-ignore lint/suspicious/noExplicitAny: cross-generic instrument array
-const instruments: any[] = [testInstrument];
-
 function renderLab(probe?: (state: DropState) => void) {
   return render(
-    <Lab instruments={instruments} defaultInstrument="TestDrop">
+    <Lab instruments={[testInstrument]} defaultInstrument="TestDrop">
       {probe ? <StateProbe onState={probe} /> : null}
     </Lab>,
   );
@@ -54,7 +51,7 @@ function renderLab(probe?: (state: DropState) => void) {
 
 beforeEach(() => {
   HTMLElement.prototype.getBoundingClientRect = function () {
-    if (this.classList.contains('lk-workspace__canvas-host')) {
+    if (this.classList.contains('lk-trial__canvas-host')) {
       return {
         x: 100,
         y: 100,

package/src/index.test.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import * as labkit from './index';
+
+/** The barrels the public surface is assembled from. Type-only exports are
+ *  erased at runtime, so the names are read out of the source rather than off
+ *  the module object. */
+const BARRELS = ['./index.ts', './lab/index.ts', './trial/index.ts', './state/index.ts'];
+
+function exportedNames(): string[] {
+  const names: string[] = [];
+  for (const barrel of BARRELS) {
+    const src = readFileSync(fileURLToPath(new URL(barrel, import.meta.url)), 'utf8');
+    for (const [, body] of src.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/g)) {
+      for (const clause of body.split(',')) {
+        const name = clause
+          .trim()
+          .split(/\s+as\s+/)
+          .pop()
+          ?.replace(/^type\s+/, '')
+          .trim();
+        if (name) names.push(name);
+      }
+    }
+  }
+  return names;
+}
+
+describe('public export surface', () => {
+  it('names the grid, not a tile, when it says Workspace', () => {
+    const offenders = exportedNames().filter(
+      (n) => n.startsWith('Workspace') && n !== 'Workspace' && n !== 'WorkspaceProps',
+    );
+    expect(offenders).toEqual([]);
+  });
+
+  it('exports no Experiment symbol that means anything per-tile', () => {
+    const offenders = exportedNames().filter(
+      (n) => n.includes('Experiment') && !n.startsWith('SingletonExperiment'),
+    );
+    expect(offenders).toEqual([]);
+  });
+
+  it('exports the tile as Trial and the area it sits in as Workspace', () => {
+    expect(labkit).toHaveProperty('Trial');
+    expect(labkit).toHaveProperty('TrialChrome');
+    expect(labkit).toHaveProperty('Workspace');
+    expect(labkit).toHaveProperty('useTrialState');
+    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,
@@ -23,6 +32,7 @@ export type {
   DragFeedback,
   HitResult,
   Instrument,
+  InstrumentList,
   LayerCapability,
   LayerDescriptor,
   PaletteItem,
@@ -34,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';
@@ -48,25 +59,31 @@ export {
 export {
   LabStoreContext,
   LabStoreProvider,
+  TrialIdContext,
+  TrialIdProvider,
   useLabStore,
-  useWorkspaceId,
-  WorkspaceIdContext,
-  WorkspaceIdProvider,
+  useTrialId,
 } from './state/context';
+export { CURRENT_DOCUMENT_VERSION, labDocumentKey, quarantineKey } from './state/document';
 export type {
   CreateLabStoreOptions,
-  ExperimentStateHandle,
+  LabDocument,
   LabMode,
   LabStoreState,
   SavedSnapshot,
+  SerializedTrial,
   StorageAdapter,
+  TrialRecord,
+  TrialStateHandle,
   UndoStack,
-  WorkspaceRecord,
 } from './state/types';
-export { useExperimentState } from './state/useExperimentState';
+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';
 export * from './ui/properties';
 export type { EventBus, EventListener } from './undo';
 export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo';
-export * from './workspace';

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(),
-      workspace: { 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/capabilityDetector.ts

@@ -1,6 +1,6 @@
 import type { Instrument } from './types';
 
-/** Which optional capabilities an instrument declared — what the workspace
+/** Which optional capabilities an instrument declared — what the trial
  *  consults to decide which chrome to show. */
 export interface CapabilityFlags {
   hasCanvas: boolean;

package/src/instrument/types.ts

@@ -1,22 +1,35 @@
 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 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. */
 export 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. */
 export interface CanvasLayer<TS = unknown, TC = unknown> {
   id: string;
   draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
@@ -29,7 +42,7 @@ export interface CanvasCapability<TS = unknown, TC = unknown> {
   initialView?: { zoom: number; pan: { x: number; y: number } };
 }
 
-/** 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. */
 export interface LayerCapability {
   ids: string[];
@@ -59,7 +72,7 @@ export type SystemEvent = string;
 export type Point = { x: number; y: number };
 /** What a hit-test found, and where. */
 export type HitResult = { hit: boolean; layerId?: string; pointId?: string };
-/** A workspace's camera. */
+/** A trial's camera. */
 export type ViewTransform = { zoom: number; pan: Point };
 /** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
 export type LayerDescriptor = { id: string; label: string; alwaysOn?: boolean };
@@ -76,13 +89,15 @@ export type DragFeedback = { ok: boolean; reason?: string };
  * 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.
  */
 export 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;
@@ -91,4 +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>[]; // 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';

package/src/job/types.ts

@@ -0,0 +1,47 @@
+/** 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. */
+export 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. */
+export 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. */
+export 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. */
+export interface JobFailure {
+  index: number;
+  error: string;
+}
+
+/** What `RenderContext.job` exposes. Present only when the instrument declares the
+ *  capability; `undefined` otherwise. */
+export 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;
+}