@weasel-js/labkit 1.4.0-pre.0 → 1.4.0

package/README.md

@@ -1,52 +1,185 @@
 # @weasel-js/labkit
 
-React widgets for building self-contained interactive **lab** pages — pages with sliders, controls, and canvas-based experimentation.
+React components for building **labs**: pages where you change parameters and
+watch something redraw. A lab hosts one or more **instruments** — self-contained
+experiments that own their settings and their state and render a picture from
+both. Each open instrument gets a **trial**, one tile of the lab's workspace,
+and the trial supplies the apparatus around it: a control panel, a toolbar, a
+sidebar, undo, snapshots, persistence and drawing tools.
 
-This is the v0.x of the library. The Lab/Trial/Instrument runtime arrives in later plans; v0.0.1 ships presentational primitives.
+Reach for it when you have a visualization, a simulation or a rendering
+algorithm and would rather not build the page around it.
 
-## Installation
-
-Not published to npm — for now the package is intentionally local-install-only.
-It also depends on a sibling clone of [weasel](https://github.com/orochi235/weasel),
-so clone both side by side:
+## Install
 
 ```bash
-git clone https://github.com/orochi235/weasel.git
-git clone https://github.com/orochi235/labkit.git
-cd weasel && npm install && npm run build
-cd ../labkit && npm install && npm run build
+npm i @weasel-js/labkit
 ```
 
-Then point your app at the local clone:
+React 19 is a peer dependency (`react` and `react-dom`, `^19.0.0`). One
+stylesheet import covers everything labkit draws, including the theme tokens and
+the `@weasel-js/ui` components it passes through:
 
-```json
-"dependencies": {
-  "@weasel-js/labkit": "file:../labkit"
-}
+```ts
+import '@weasel-js/labkit/styles.css';
 ```
 
-## Usage
+Annotations are on the `pre` tag until the next stable release:
+`npm i @weasel-js/labkit@pre`.
+
+## A lab
 
 ```tsx
-import { LabShell, Toolbar, Workspace, FpsMeter } from '@weasel-js/labkit';
+import { type ConfigOf, defineInstrument, f, Lab, localStorageAdapter } from '@weasel-js/labkit';
 import '@weasel-js/labkit/styles.css';
 
-function MyLab() {
+const config = f.schema({
+  bins: f.number(20).range(5, 100).step(1).label('Bins'),
+  showAxes: f.boolean(true),
+});
+
+const Histogram = defineInstrument<{ samples: number[] }, ConfigOf<typeof config>>({
+  name: 'Histogram',
+  config,
+  initialState: () => ({ samples: sample(500) }),
+  render: () => null,
+  canvas: {
+    layers: [
+      { id: 'axes', draw: drawAxes },
+      { id: 'bars', draw: drawBars },
+    ],
+  },
+  layers: { ids: ['axes', 'bars'] },
+});
+
+export function App() {
   return (
-    <LabShell title="My Lab" header={<button>+ Add</button>}>
-      <Workspace>
-        <div>Trial 1</div>
-        <div>Trial 2</div>
-      </Workspace>
-    </LabShell>
+    <Lab
+      instruments={[Histogram]}
+      defaultInstrument="Histogram"
+      title="Histogram"
+      storage={localStorageAdapter}
+      storageKey="histogram-lab"
+    />
   );
 }
 ```
 
+`f.schema` states the config once — values, types and controls — and the trial
+renders the settings panel from it. `render` returns the instrument's own DOM;
+returning `null` alongside `canvas` means the canvas layers are the whole
+picture. `storage` keeps open trials and their state across reloads.
+
+## Capabilities
+
+A capability is a field on the instrument. Declaring it is what makes the trial
+provide the corresponding chrome; they compose freely.
+
+| Field | What the trial then provides |
+| --- | --- |
+| `canvas` | A stack of layered `<canvas>` elements with pan and zoom, redrawing only the layers that changed |
+| `layers` | A sidebar list that hides and reorders those layers |
+| `annotations` | Drawing tools, an overlay on each region you name, a Marks panel, undo and export |
+| `loupe` | A magnifier toggle that redraws the canvas through a zoomed camera, or calls your own `render` for DOM content |
+| `dragDrop` | A palette to drag items from, and a drop pipeline that hands you world coordinates |
+| `undo` | Undo and redo buttons, snapshotting state on the events you name |
+| `job` | Starts async work, aborts it on unmount and on a key change, and renders progress and a cancel control |
+| `tools` | A tool palette and a tool slot on the trial |
+| `chrome` | Anything else, as contributions keyed to a region |
+
+## Annotations
+
+An instrument names regions of itself that accept **marks** — freehand strokes,
+lines, arrows, rectangles, ellipses and text drawn over its picture. labkit
+supplies the tool palette, the overlay, the store, undo, persistence and export.
+
+```tsx
+const paneRef = createRef<HTMLDivElement>();
+
+defineInstrument<State, Config>({
+  // …
+  annotations: {
+    targets: () => [
+      { id: 'pane', ref: paneRef, content: { w: 260, h: 180 }, positionDependsOn: ['angle'] },
+    ],
+    meaning: {
+      statuses: [
+        { id: 'open', label: 'Open', color: '#e5484d' },
+        { id: 'fixed', label: 'Fixed', color: '#30a46c' },
+      ],
+    },
+  },
+});
+```
+
+A mark's position is stored as fractions of its target's `content` box, so it
+stays on the same feature when the picture is rendered at a different size.
+`positionDependsOn` names the config keys that move the picture; labkit
+snapshots their values beside each mark, and a mark whose values have since
+changed draws dashed and reports `isStale`. `meaning.statuses` is the optional
+vocabulary a mark can be labelled with — a status carries its own color, which
+the mark on the canvas follows.
+
+Marks live in the trial's record and survive a reload. An instrument that would
+rather keep them in a format it already owns declares `annotations.storage` with
+a `load`/`save` pair, and labkit never writes its own slot.
+
+`useAnnotations()` reaches the store from the instrument's `render` or from a
+chrome contribution, and re-renders its caller as marks change:
+
+```tsx
+const marks = useAnnotations();
+const stale = marks.query({ target: 'pane' }).filter((m) => marks.isStale(m, config));
+```
+
+`selection()` answers which marks the user has picked on the overlay, as
+annotation ids, and `setSelection()` replaces them — the same selection
+weasel's own click, marquee and handles drive, merged across every target.
+A panel that opens a card for the clicked mark subscribes and re-reads it.
+
+It also carries `get`, `hitTest`, `within`, `add`, `update`, `setMeta`,
+`remove`, `undo`/`redo` and `capture`.
+
+**Export.** A target declaring `base()` hands over the picture underneath its
+marks — SVG markup, an image `src` or a canvas — and
+`capture(target, { format, scale })` returns a Blob with the marks drawn on top,
+as PNG or, from an SVG base, as vector SVG. Declaring `annotations` earns an
+Export button in the toolbar; `onCapture` fires after every export, labkit's own
+chrome included.
+
+The pieces are exported for a host that wants to assemble them itself:
+`createAnnotationStore`, `<AnnotationOverlay>`, `<AnnotationTargets>`,
+`<MarkList>`, `<ExportMenu>`, `ANNOTATION_TOOLS` and `capturePlan`.
+
+## Chrome
+
+A trial's chrome has six named regions — `titlebar`, `toolbar`, `palette`,
+`sidebar`, `viewport`, `status`. A `TrialContribution` names one and supplies
+data the region lays out, or a `render` function that opts out of that layout:
+
+```tsx
+<Lab
+  chrome={[{ id: 'seed', region: 'status', item: { text: `seed ${seed}` } }]}
+  suppress={['fps']}
+  // …
+/>
+```
+
+Contributions passed to `<Lab>` apply to every trial; an instrument's own
+`chrome` field applies to its trials only. `suppress` drops a built-in by id and
+throws on an id that is not there.
+
+A sidebar section can be torn out of the trial into the workspace — as a tile
+beside the trials, or as a floating panel — with the trial still rendering into
+it. `SidebarSection.undockable` and `undockAs` control the offer;
+`undockPanel` / `dockPanel` move one.
+
 ## Theming
 
 labkit ships one theme, `interstellar` — a cosmic dark and a warm parchment
-light — as a value, not a stylesheet:
+light — as a value, not a stylesheet. `<Lab>` and `<LabShell>` apply it for you;
+`mode` is `"auto"` (follow the OS), `"light"` or `"dark"`. Only `styles.css`
+needs importing, and the token values arrive through the provider:
 
 ```tsx
 import { interstellarTheme } from '@weasel-js/labkit';
@@ -55,9 +188,31 @@ import { ThemeProvider } from '@weasel-js/theme/react';
 <ThemeProvider theme={interstellarTheme} mode="dark">…</ThemeProvider>
 ```
 
-`<Lab>` and `<LabShell>` do this for you; `mode` is `"auto"` (follow the OS),
-`"light"` or `"dark"`. Only `styles.css` needs importing — the token values
-arrive through the provider.
+Style your own surfaces against the `--wzl-*` tokens so they follow the mode the
+lab is in. Class names are `lk-*` and are not public API — every component takes
+a `className`.
+
+## Without the runtime
+
+The presentational pieces work on their own. `<LabShell>` is a titled page
+frame; `<Workspace>` is a tile grid that can be resized and reordered and takes
+any children:
+
+```tsx
+import { LabShell, Workspace } from '@weasel-js/labkit';
+
+<LabShell title="My Lab" header={<button>+ Add</button>}>
+  <Workspace ids={['a', 'b']} resizable>
+    <MyPane id="a" />
+    <MyPane id="b" />
+  </Workspace>
+</LabShell>;
+```
+
+`<Toolbar>`, `<Sidebar>`, `<StatusBar>`, `<FpsMeter>`, `<ScaleIndicator>`,
+`<Legend>`, `<FloatingPanel>`, `<ZoomControl>` and the `@weasel-js/ui` property
+rows re-exported from the root are all usable this way. `<Trial>` is not: it
+reads the lab store and only mounts inside a `<Lab>`.
 
 ## Driving your own renderer
 
@@ -68,40 +223,56 @@ labkit and keep the GL yourself:
 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`.
+A trial's `view` is opaque to labkit — persisted, restored on Reset and handed
+to the instrument without being read into — so a 3D lab stores an orbit there.
+Both cameras ship independently of `CanvasStack`: `useOrbit` for a 3D view,
+`usePanZoom` for a 2D one over a `ViewTransform`. See `src/surface/AGENTS.md`
+for the contract and the traps.
 
-See `src/surface/AGENTS.md` for the contract and the traps.
+## Subpath exports
 
-## Long-running work
+The root barrel carries the common surface; a subpath reaches one slice
+directly. Several expose more than the root does, `/state` most of all.
 
-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';
-```
+| Subpath | |
+| --- | --- |
+| `@weasel-js/labkit` | Everything |
+| `/styles.css` | The one stylesheet |
+| `/primitives` | Toolbar, Sidebar, StatusBar, Legend, FloatingPanel, meters |
+| `/chrome` | Regions, contribution types, built-in contributions |
+| `/controls` | `<ControlPanel>` and the config field types |
+| `/canvas` | `<CanvasStack>`, coordinate helpers, `usePanZoom`, `useOrbit` |
+| `/layers` | `<LayerList>` |
+| `/loupe` | Magnifier components and `useLoupe` |
+| `/surface` | Tiled surface hooks for your own renderer |
+| `/job` | `useJob` and the job capability types |
+| `/state` | The lab store, storage adapters, `useTrialState`, serialization helpers |
+| `/undo` | Undo stack and event bus |
+| `/dragdrop` | `<Palette>`, `<DragGhost>`, `useDragDrop` |
+| `/ui/layers` | `<LayerStack>`, the expandable layer-card list |
+| `/weasel-ui`, `/weasel-canvas` | Passthroughs to `@weasel-js/ui` and `@weasel-js/core` |
 
 ## Development
 
+labkit is a workspace package in the [weasel](https://github.com/orochi235/weasel)
+monorepo. From the repo root, `npm install` once, then from `packages/labkit`:
+
 ```bash
-npm install
-npm run dev          # Vite dev server (examples/)
-npm run storybook    # Storybook on :6006
-npm test             # Vitest
-npm run lint         # Biome + class-prefix check
-npm run build        # Build dist/ for publish
+npm run dev            # Vite dev server on examples/minimal
+npm run dev:annotate   # …on examples/annotate-lab (and dev:drag, dev:weasel, dev:schema)
+npm test               # Vitest
+npm run lint           # Biome, plus the class-prefix and design-token checks
+npm run build          # dist/ for publish
+npm run docs:dev       # VitePress on docs/ (docs:build to render it)
 ```
 
+Storybook is built at the repo root: `npm run storybook` from there covers every
+package.
+
 ## Documentation
 
-- [Docs site](https://orochi235.github.io/labkit/)
-- [Recipes](https://orochi235.github.io/labkit/RECIPES) — composition patterns
-- [Agent guide](https://orochi235.github.io/labkit/AGENTS) — agent navigation guide
-- [Storybook](https://orochi235.github.io/labkit/storybook/)
-- [Speech balloon experiment](https://orochi235.github.io/labkit/storybook/?path=/story/ui-properties-propertypanel-speechballoonpanels--right-sidebar-tails) — sample implementation built on the property-panel widgets
-- [Design spec](https://github.com/orochi235/labkit/blob/main/docs/superpowers/specs/2026-04-26-labkit-design.md)
+- [Docs site](https://orochi235.github.io/weasel/labkit/)
+- [Recipes](https://orochi235.github.io/weasel/labkit/RECIPES) — composition patterns
+- [Agent guide](https://orochi235.github.io/weasel/labkit/AGENTS) — a map of the source
+- [Storybook](https://orochi235.github.io/weasel/docs/ui/storybook/)
+- [Design spec](https://github.com/orochi235/weasel/blob/main/packages/labkit/docs/superpowers/specs/2026-04-26-labkit-design.md)

package/dist/_dts/{CanvasStackContext-DtAn_3O-.d.ts → CanvasStackContext-D6M0o8cQ.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { V as ViewTransform, W as WorldFrame } from './frac-Cp3NivlC.js';
+import { V as ViewTransform, W as WorldFrame } from './frac-QS7XzvpG.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */

package/dist/_dts/{frac-Cp3NivlC.d.ts → frac-QS7XzvpG.d.ts}

@@ -1,6 +1,6 @@
 import { ComponentType, ReactNode, RefObject } from 'react';
-import { R as ResolvedConfig, C as ConfigField, a as ConfigSchema } from './types-D6s4b7if.js';
-import { c as SavedSnapshot } from './types-DYMaEvM5.js';
+import { R as ResolvedConfig, C as ConfigField, a as ConfigSchema } from './types-C1Zw7s5P.js';
+import { c as SavedSnapshot } from './types-ChVJJHvk.js';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
 import { S as Scene } from './types-C-gh9Ap-.js';
 
@@ -671,8 +671,15 @@ interface AnnotationsApi {
     within(target: string, box: FracRect): Annotation[];
     /** Whether `a`'s position still describes the picture `config` produces. */
     isStale(a: Annotation, config: unknown): boolean;
-    /** Fires after every mutation. No delta: the scene does not diff, so
-     *  re-query rather than expecting a change payload. */
+    /** The marks the user currently has selected, across every target, as
+     *  annotation ids. Every one resolves through `get`. */
+    selection(): readonly string[];
+    /** Replace the selection. An id naming a target or a mark that is not
+     *  there is dropped, the way `update` and `remove` ignore one. */
+    setSelection(ids: readonly string[]): void;
+    /** Fires after every mutation *and* after a selection change — weasel keeps
+     *  a canvas's selection on the scene, so both already arrive on this one
+     *  channel. No delta: re-query, and re-read `selection()`. */
     subscribe(fn: () => void): () => void;
     /** Whether the last mark change on any target can be taken back. Weasel
      *  history is the authority; this only decides *which* target's. */

package/dist/_dts/{index-BDVzvRzQ.d.ts → index-B2X21G1c.d.ts}

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { R as ResolvedConfig, C as ConfigField, c as ControlRenderer } from './types-D6s4b7if.js';
+import { R as ResolvedConfig, C as ConfigField, c as ControlRenderer } from './types-C1Zw7s5P.js';
 
 /** Props for `<PropertyPanel>`. */
 interface PropertyPanelProps {
@@ -155,6 +155,12 @@ interface NumberRowProps {
     max?: number;
     step?: number;
     placeholder?: string;
+    /**
+     * Optional suffix rendered after the field. A string becomes a dim "word"
+     * unit (e.g. "px"); pass JSX like `<sup>°</sup>` for symbol units. Display
+     * only — it never participates in parsing, and the value stays a number.
+     */
+    unit?: ReactNode;
     layout?: PropertyRowLayout;
     description?: string;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
@@ -162,7 +168,7 @@ interface NumberRowProps {
 }
 /** A number typed directly. Reach for `<SliderRow>` when the range matters
  *  more than the exact value. */
-declare function NumberRow({ label, value, onChange, min, max, step, placeholder, layout, description, span, }: NumberRowProps): react_jsx_runtime.JSX.Element;
+declare function NumberRow({ label, value, onChange, min, max, step, placeholder, unit, layout, description, span, }: NumberRowProps): react_jsx_runtime.JSX.Element;
 interface PropertyOption<T extends string> {
     value: T;
     label: ReactNode;

package/dist/_dts/{types-D6s4b7if.d.ts → types-C1Zw7s5P.d.ts}

@@ -22,6 +22,7 @@ interface Annotations {
     min?: number;
     max?: number;
     step?: number;
+    suffix?: string;
     control?: string;
     options?: readonly ConfigOption[];
     placeholder?: string;

package/dist/_dts/{types-DYMaEvM5.d.ts → types-ChVJJHvk.d.ts}

@@ -30,6 +30,9 @@ interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
     view: TV;
     /** This trial's own tool slot. Undefined means it reads the lab's. */
     activeToolId?: string | null;
+    /** The extent the trial's sidebar was last dragged to, in pixels. Undefined
+     *  until someone moves the seam. */
+    sidebarWidth?: number;
     /** The marks on this trial's annotation targets, as `AnnotationsApi.toJSON`
      *  wrote them. Opaque here, and absent for a trial whose instrument declares
      *  no `annotations` — or declares its own `storage`. Not in `state`, which

package/dist/_dts/{useTrialState-gmMvZqPc.d.ts → useTrialState-Cdm13fvl.d.ts}

@@ -1,4 +1,4 @@
-import { a as StorageAdapter, b as LabStoreState, T as TrialRecord, c as SavedSnapshot, h as LabMode, e as UndockedPanel, I as InstrumentSerializers, C as CreateLabStoreOptions, d as TrialStateHandle } from './types-DYMaEvM5.js';
+import { a as StorageAdapter, b as LabStoreState, T as TrialRecord, c as SavedSnapshot, h as LabMode, e as UndockedPanel, I as InstrumentSerializers, C as CreateLabStoreOptions, d as TrialStateHandle } from './types-ChVJJHvk.js';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
@@ -25,6 +25,7 @@ interface LabStoreActions {
     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;
+    updateTrialSidebarWidth: (id: string, width: number) => void;
     updateTrialAnnotations: (id: string, doc: unknown) => void;
     updateTrialUndoStack: (id: string, next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack'])) => void;
     setTrialInstrument: (id: string, instrumentName: string) => void;

package/dist/canvas/index.d.ts

@@ -1,12 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-import { V as ViewTransform, c as WorldSpec, a2 as ViewportSize, a as Point, W as WorldFrame } from '../_dts/frac-Cp3NivlC.js';
-export { x as DEFAULT_FRAME, a4 as applyCamera, aa as resolveFrame } from '../_dts/frac-Cp3NivlC.js';
-import { C as CanvasLayerDescriptor } from '../_dts/CanvasStackContext-DtAn_3O-.js';
-export { a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from '../_dts/CanvasStackContext-DtAn_3O-.js';
-import '../_dts/types-D6s4b7if.js';
+import { ReactNode, WheelEvent, PointerEvent } from 'react';
+import { V as ViewTransform, c as WorldSpec, a2 as ViewportSize, a as Point, W as WorldFrame } from '../_dts/frac-QS7XzvpG.js';
+export { x as DEFAULT_FRAME, a4 as applyCamera, aa as resolveFrame } from '../_dts/frac-QS7XzvpG.js';
+import { C as CanvasLayerDescriptor } from '../_dts/CanvasStackContext-D6M0o8cQ.js';
+export { a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from '../_dts/CanvasStackContext-D6M0o8cQ.js';
+import '../_dts/types-C1Zw7s5P.js';
 import '../_dts/PrefsForm-BkUJZx0A.js';
-import '../_dts/types-DYMaEvM5.js';
+import '../_dts/types-ChVJJHvk.js';
 import '../_dts/types-DJ79Tg5J.js';
 import '../_dts/types-C-gh9Ap-.js';
 
@@ -64,5 +64,71 @@ declare function worldToScreen(world: Point, view: ViewTransform, frame?: WorldF
 /** Unproject a screen point back to world coordinates under a view. */
 declare function screenToWorld(screen: Point, view: ViewTransform, frame?: WorldFrame): Point;
 
-export { CanvasLayerDescriptor, CanvasStack, ViewportSize, WorldFrame, WorldSpec, centerOn, screenToWorld, worldToScreen, zoomAt };
-export type { CanvasStackProps, ZoomAtOptions };
+/** A point in the space the instrument works in. */
+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. */
+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. */
+declare const PITCH_LIMIT: number;
+declare function clampPitch(pitch: number): number;
+declare function wrapYaw(yaw: number): number;
+/** 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. */
+declare function orbitAfterDrag(start: OrbitView, dx: number, dy: number): OrbitView;
+/** Multiplicative, so one notch covers the same proportion of the distance
+ *  whether the camera is near or far. */
+declare function orbitAfterWheel(view: OrbitView, deltaY: number, minDistance: number, maxDistance: number): OrbitView;
+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;
+}
+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;
+}
+/** Pointer gestures over an orbit view: drag to turn, wheel or pinch to dolly,
+ *  double-click to go home. The 3D peer of `usePanZoom`. */
+declare function useOrbit({ view, onViewChange, home, minDistance, maxDistance, }: UseOrbitOptions): OrbitHandlers;
+
+interface UsePanZoomOptions {
+    view: ViewTransform;
+    onViewChange: (v: ViewTransform) => void;
+    /** The opening `view.zoom` always stays reachable, widening these past
+     *  whatever is passed here if it would otherwise exclude it. */
+    minZoom?: number;
+    maxZoom?: number;
+    /** The instrument's coordinate system, resolved against the viewport. The
+     *  wheel anchors in this frame; omitting it anchors at the element's
+     *  top-left, which is what labkit did before a frame could be declared. */
+    frame?: WorldFrame;
+}
+interface PanZoomHandlers {
+    onWheel: (e: WheelEvent<HTMLElement>) => void;
+    onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+    isDragging: () => boolean;
+}
+declare function usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, }: UsePanZoomOptions): PanZoomHandlers;
+
+export { CanvasLayerDescriptor, CanvasStack, PITCH_LIMIT, ViewportSize, WorldFrame, WorldSpec, centerOn, clampPitch, orbitAfterDrag, orbitAfterWheel, screenToWorld, useOrbit, usePanZoom, worldToScreen, wrapYaw, zoomAt };
+export type { CanvasStackProps, OrbitHandlers, OrbitView, PanZoomHandlers, UseOrbitOptions, UsePanZoomOptions, Vec3, ZoomAtOptions };

package/dist/canvas/index.js

@@ -1,7 +1,7 @@
-export { CanvasStack } from '../chunk-3ZELRRBV.js';
+export { CanvasStack, PITCH_LIMIT, clampPitch, orbitAfterDrag, orbitAfterWheel, useOrbit, usePanZoom, wrapYaw } from '../chunk-VHFQKAUL.js';
 export { centerOn, zoomAt } from '../chunk-CTRKTLYZ.js';
 export { DEFAULT_FRAME, applyCamera, resolveFrame, screenToWorld, worldToScreen } from '../chunk-2AYGEN57.js';
 export { CanvasStackContext } from '../chunk-CQLQPQ4P.js';
-import '../chunk-ROQDRXKW.js';
+import '../chunk-7VW3S44V.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/chrome/index.d.ts

@@ -1,10 +1,10 @@
-import { c as ControlRenderer } from '../_dts/types-D6s4b7if.js';
-import { I as Instrument, _ as TrialChromeContext, m as TrialContribution } from '../_dts/frac-Cp3NivlC.js';
-export { z as IconComponent, O as SidebarSection, Q as StatusReadout, Y as ToolItem, Z as ToolbarItem, $ as TrialRegion, a1 as ViewportControl } from '../_dts/frac-Cp3NivlC.js';
+import { c as ControlRenderer } from '../_dts/types-C1Zw7s5P.js';
+import { I as Instrument, _ as TrialChromeContext, m as TrialContribution } from '../_dts/frac-QS7XzvpG.js';
+export { z as IconComponent, O as SidebarSection, Q as StatusReadout, Y as ToolItem, Z as ToolbarItem, $ as TrialRegion, a1 as ViewportControl } from '../_dts/frac-QS7XzvpG.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import '../_dts/PrefsForm-BkUJZx0A.js';
 import 'react';
-import '../_dts/types-DYMaEvM5.js';
+import '../_dts/types-ChVJJHvk.js';
 import '../_dts/types-DJ79Tg5J.js';
 import '../_dts/types-C-gh9Ap-.js';
 

package/dist/chrome/index.js

@@ -1,9 +1,9 @@
-export { PaletteRegion, SidebarRegion, StatusRegion, TitleBarRegion, ToolbarRegion, ViewportRegion, builtinContributions, mergeContributions, suppressContributions } from '../chunk-LITE5YFB.js';
-import '../chunk-6JMU56CU.js';
-import '../chunk-YQJNT4XQ.js';
+export { PaletteRegion, SidebarRegion, StatusRegion, TitleBarRegion, ToolbarRegion, ViewportRegion, builtinContributions, mergeContributions, suppressContributions } from '../chunk-UD7TEHZT.js';
+import '../chunk-QR5V3AFG.js';
+import '../chunk-W3KSUXXR.js';
 import '../chunk-SBXNQW4G.js';
-import '../chunk-HEORBLVT.js';
+import '../chunk-L5WBGUVR.js';
 import '../chunk-CQLQPQ4P.js';
-import '../chunk-ROQDRXKW.js';
+import '../chunk-7VW3S44V.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/chunk-2YILQ7Y5.js

@@ -0,0 +1,33 @@
+import { createContext, useContext } from 'react';
+import { useStore } from 'zustand/react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/state/context.tsx
+var LabStoreContext = createContext(null);
+function LabStoreProvider({
+  store,
+  children
+}) {
+  return /* @__PURE__ */ jsx(LabStoreContext.Provider, { value: { store }, children });
+}
+function useLabStore() {
+  const ctx = useContext(LabStoreContext);
+  if (!ctx) throw new Error("[labkit] useLabStore must be used inside <LabStoreProvider>");
+  return useStore(ctx.store);
+}
+var TrialIdContext = createContext(null);
+function TrialIdProvider({
+  trialId,
+  children
+}) {
+  return /* @__PURE__ */ jsx(TrialIdContext.Provider, { value: trialId, children });
+}
+function useTrialId() {
+  const id = useContext(TrialIdContext);
+  if (!id) throw new Error("[labkit] useTrialId must be used inside <TrialIdProvider>");
+  return id;
+}
+
+export { LabStoreContext, LabStoreProvider, TrialIdContext, TrialIdProvider, useLabStore, useTrialId };
+//# sourceMappingURL=chunk-2YILQ7Y5.js.map
+//# sourceMappingURL=chunk-2YILQ7Y5.js.map

package/dist/chunk-2YILQ7Y5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state/context.tsx"],"names":[],"mappings":";;;;;AASO,IAAM,eAAA,GAAkB,cAA2B,IAAI;AAGvD,SAAS,gBAAA,CAAiB;AAAA,EAC/B,KAAA;AAAA,EACA;AACF,CAAA,EAGiB;AACf,EAAA,uBAAO,GAAA,CAAC,gBAAgB,QAAA,EAAhB,EAAyB,OAAO,EAAE,KAAA,IAAU,QAAA,EAAS,CAAA;AAC/D;AAGO,SAAS,WAAA,GAAgE;AAC9E,EAAA,MAAM,GAAA,GAAM,WAAW,eAAe,CAAA;AACtC,EAAA,IAAI,CAAC,GAAA,EAAK,MAAM,IAAI,MAAM,6DAA6D,CAAA;AACvF,EAAA,OAAO,QAAA,CAAS,IAAI,KAAK,CAAA;AAC3B;AAGO,IAAM,cAAA,GAAiB,cAA6B,IAAI;AAIxD,SAAS,eAAA,CAAgB;AAAA,EAC9B,OAAA;AAAA,EACA;AACF,CAAA,EAGiB;AACf,EAAA,2BAAQ,cAAA,CAAe,QAAA,EAAf,EAAwB,KAAA,EAAO,SAAU,QAAA,EAAS,CAAA;AAC5D;AAIO,SAAS,UAAA,GAAqB;AACnC,EAAA,MAAM,EAAA,GAAK,WAAW,cAAc,CAAA;AACpC,EAAA,IAAI,CAAC,EAAA,EAAI,MAAM,IAAI,MAAM,2DAA2D,CAAA;AACpF,EAAA,OAAO,EAAA;AACT","file":"chunk-2YILQ7Y5.js","sourcesContent":["import { createContext, type ReactElement, type ReactNode, useContext } from 'react';\nimport { useStore } from 'zustand/react';\nimport type { LabStore } from './store';\nimport type { LabStoreState } from './types';\n\ntype LabStoreCtx = { store: LabStore } | null;\n\n/** Context carrying the lab store. Prefer `useLabStore`; this is exported for\n *  code that needs to read the context without subscribing. */\nexport const LabStoreContext = createContext<LabStoreCtx>(null);\n\n/** Provides a lab store to its subtree. */\nexport function LabStoreProvider({\n  store,\n  children,\n}: {\n  store: LabStore;\n  children: ReactNode;\n}): ReactElement {\n  return <LabStoreContext.Provider value={{ store }}>{children}</LabStoreContext.Provider>;\n}\n\n/** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */\nexport function useLabStore(): LabStoreState & ReturnType<LabStore['getState']> {\n  const ctx = useContext(LabStoreContext);\n  if (!ctx) throw new Error('[labkit] useLabStore must be used inside <LabStoreProvider>');\n  return useStore(ctx.store);\n}\n\n/** Context carrying which trial the subtree belongs to. */\nexport const TrialIdContext = createContext<string | null>(null);\n\n/** Names the trial its subtree belongs to, so an instrument's hooks can\n *  find their own record in the store without being passed an id. */\nexport function TrialIdProvider({\n  trialId,\n  children,\n}: {\n  trialId: string;\n  children: ReactNode;\n}): ReactElement {\n  return <TrialIdContext.Provider value={trialId}>{children}</TrialIdContext.Provider>;\n}\n\n/** The id of the trial this component is inside. Throws outside a\n *  `<TrialIdProvider>`. */\nexport function useTrialId(): string {\n  const id = useContext(TrialIdContext);\n  if (!id) throw new Error('[labkit] useTrialId must be used inside <TrialIdProvider>');\n  return id;\n}\n"]}

package/dist/{chunk-3P5TTTA7.js → chunk-4AMN4MMB.js}

@@ -1,4 +1,4 @@
-import { ae, oe } from './chunk-HEORBLVT.js';
+import { ce, le } from './chunk-L5WBGUVR.js';
 import { useRef, useMemo, useState, useEffect } from 'react';
 import { floatingStrategy, DEFAULT_INSET, DEFAULT_ANCHOR, FLOATING_DRAG_PREFIX } from 'windease';
 import { jsx, jsxs } from 'react/jsx-runtime';
@@ -168,12 +168,12 @@ function JobProgress({ job, className }) {
       determinate ? ` / ${total}` : ""
     ] }),
     failures.length > 0 && /* @__PURE__ */ jsxs("span", { className: "lk-job__failures", title: failures.map((f) => f.error).join("\n"), children: [
-      /* @__PURE__ */ jsx(ae, { size: 14 }),
+      /* @__PURE__ */ jsx(ce, { size: 14 }),
       failures.length,
       " failed"
     ] }),
     error && /* @__PURE__ */ jsxs("span", { className: "lk-job__error", title: error, children: [
-      /* @__PURE__ */ jsx(oe, { size: 14 }),
+      /* @__PURE__ */ jsx(le, { size: 14 }),
       error
     ] }),
     status === "running" && /* @__PURE__ */ jsx("button", { type: "button", className: "lk-job__cancel", onClick: job.cancel, children: "Cancel" })
@@ -216,5 +216,5 @@ function Sidebar({ children, title, collapsed = false, onToggle }) {
 }
 
 export { FloatingPanel, JobProgress, Legend, Sidebar };
-//# sourceMappingURL=chunk-3P5TTTA7.js.map
-//# sourceMappingURL=chunk-3P5TTTA7.js.map
+//# sourceMappingURL=chunk-4AMN4MMB.js.map
+//# sourceMappingURL=chunk-4AMN4MMB.js.map