@weasel-js/labkit 1.6.0 → 1.6.1

package/src/canvas/cameraView.ts

@@ -0,0 +1,61 @@
+/**
+ * labkit's camera as a weasel `View`, so core's viewport actions drive it.
+ *
+ * labkit places a world point on screen at
+ * `originPx + pan + zoom * (x, yDir * y)`. A weasel `View` places one at
+ * `(p - (x, y)) * scale`. Over *frame-local* coordinates — the world with `y`
+ * multiplied by `yDir` — the two are the same affine map, which is all a pan
+ * or a zoom about a screen point needs.
+ */
+import type { View } from '@weasel-js/core';
+import type { Point, ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
+import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
+
+/** The weasel `View` equal to `view` under `frame`. */
+export function toCameraView(view: ViewTransform, frame: WorldFrame = DEFAULT_FRAME): View {
+  const v = normalize2DView(view);
+  return {
+    x: -(frame.originPx.x + v.pan.x) / v.zoom,
+    y: -(frame.originPx.y + v.pan.y) / v.zoom,
+    scale: { x: v.zoom, y: v.zoom },
+  };
+}
+
+/** The labkit camera equal to weasel `view` under `frame`. */
+export function fromCameraView(view: View, frame: WorldFrame = DEFAULT_FRAME): ViewTransform {
+  const zoom = view.scale.x;
+  return {
+    zoom,
+    pan: { x: -view.x * zoom - frame.originPx.x, y: -view.y * zoom - frame.originPx.y },
+  };
+}
+
+/** A frame-local point in the instrument's world, and back — the map is its
+ *  own inverse. */
+export function frameLocalToWorld(p: Point, frame: WorldFrame = DEFAULT_FRAME): Point {
+  return { x: p.x, y: p.y * frame.yDir };
+}
+
+/**
+ * `next` with its zoom held to [`min`, `max`], about the screen point the step
+ * from `prev` was anchored on, so a zoom that hits a bound stays anchored where
+ * the pointer is. A pan (equal scales) passes through.
+ */
+export function clampZoomAbout(prev: View, next: View, min: number, max: number): View {
+  const s0 = prev.scale.x;
+  const s1 = next.scale.x;
+  const clamped = Math.min(max, Math.max(min, s1));
+  if (clamped === s1) return next;
+  if (s0 === s1) return { ...next, scale: { x: clamped, y: clamped } };
+  // The screen point both views agree on: p / s0 + x0 = p / s1 + x1.
+  const inv = 1 / s0 - 1 / s1;
+  const px = (next.x - prev.x) / inv;
+  const py = (next.y - prev.y) / inv;
+  // The same point under the clamped scale.
+  return {
+    x: prev.x + px / s0 - px / clamped,
+    y: prev.y + py / s0 - py / clamped,
+    scale: { x: clamped, y: clamped },
+  };
+}

package/src/canvas/index.ts

@@ -1,3 +1,12 @@
+export type { CameraContextValue, CameraInputProps, CameraViewOptions } from './CameraInput';
+export {
+  CameraContext,
+  CameraInput,
+  CameraScope,
+  CameraScopeContext,
+  STAGE_VIEW_ID,
+  useCameraView,
+} from './CameraInput';
 export type { CameraWheelSlot } from './CameraWheelContext';
 export { CameraWheelContext } from './CameraWheelContext';
 export type { CanvasStackProps } from './CanvasStack';
@@ -6,11 +15,11 @@ export type { CanvasStackContextValue, CanvasStackSurface } from './CanvasStackC
 export { CanvasStackContext } from './CanvasStackContext';
 export type { ZoomAtOptions } from './camera';
 export { centerOn, zoomAt } from './camera';
+export { clampZoomAbout, frameLocalToWorld, fromCameraView, toCameraView } from './cameraView';
 export { screenToWorld, worldToScreen } from './canvasCoords';
+export { LinkedCursor } from './LinkedCursor';
 export type { StageProps } from './Stage';
 export { fitStage, Stage } from './Stage';
 export type { CanvasLayerDescriptor } from './useLayerScheduler';
-export type { PanZoomHandlers, UsePanZoomOptions } from './usePanZoom';
-export { usePanZoom } from './usePanZoom';
 export type { ViewportSize, WorldFrame, WorldSpec } from './worldSpec';
 export { applyCamera, DEFAULT_FRAME, resolveFrame } from './worldSpec';

package/src/chrome/regions/SidebarRegion.test.tsx

@@ -3,13 +3,20 @@ import { describe, expect, it } from 'vitest';
 import type { RegionContribution, TrialChromeContext } from '../types';
 import { SidebarRegion } from './SidebarRegion';
 
-const ctx = { collapsedSections: {}, setSectionCollapsed: () => {} } as unknown as TrialChromeContext;
+const ctx = {
+  collapsedSections: {},
+  setSectionCollapsed: () => {},
+} as unknown as TrialChromeContext;
 
 describe('<SidebarRegion> stance and tone', () => {
   it('puts a section’s stance and tone on the section', () => {
     const contributions: RegionContribution<TrialChromeContext>[] = [
       { id: 'a', region: 'sidebar', item: { title: 'Plain', body: 'x' } },
-      { id: 'b', region: 'sidebar', item: { title: 'Debug', body: 'y', stance: 'debug', tone: '#224a63' } },
+      {
+        id: 'b',
+        region: 'sidebar',
+        item: { title: 'Debug', body: 'y', stance: 'debug', tone: '#224a63' },
+      },
     ];
     const { container } = render(<SidebarRegion contributions={contributions} ctx={ctx} />);
     const [plain, debug] = [...container.querySelectorAll<HTMLElement>('.lk-sidebar-section')];

package/src/config/builder.ts

@@ -1,5 +1,4 @@
 import type { PrefLeaf, PrefNumberFormat, PrefNumberUnit } from '@weasel-js/ui';
-import { type InDialogOptions, inDialog } from '../controls/inDialog';
 import { type Auto, isAuto } from './auto';
 import type {
   Annotations,
@@ -12,6 +11,7 @@ import type {
   ConfigSchema,
   ConfigShape,
   ControlRenderer,
+  InDialogOptions,
   InferConfig,
   NodeOptions,
   SectionOption,
@@ -89,13 +89,13 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
 
   /** Draw this one row yourself, keeping the kind, default and validation. */
   render(renderer: ControlRenderer): this {
-    return this.opt({ render: renderer });
+    return this.opt({ render: renderer, dialog: undefined });
   }
 
   /** Draw this row as a button that opens a dialog, with `body` as the
    *  dialog's content — for an editor too big for the row. */
   dialog(body: ControlRenderer, opts?: InDialogOptions): this {
-    return this.render(inDialog(body, opts));
+    return this.opt({ dialog: { ...opts, body }, render: undefined });
   }
 
   /**

package/src/config/entry.test.ts

@@ -39,7 +39,9 @@ describe('@weasel-js/labkit/config', () => {
   // A forge frame loads this entry for every story, and ui's barrel is 167 modules on the dev server.
   it('loads nothing from @weasel-js/ui at runtime', () => {
     const importers = [...walk(resolve(__dirname, 'index.ts'))].filter((file) =>
-      [...readFileSync(file, 'utf8').matchAll(IMPORT)].some((m) => (m[1] ?? m[2] ?? m[3])?.startsWith('@weasel-js/ui')),
+      [...readFileSync(file, 'utf8').matchAll(IMPORT)].some((m) =>
+        (m[1] ?? m[2] ?? m[3])?.startsWith('@weasel-js/ui'),
+      ),
     );
     expect(importers).toEqual([]);
   });

package/src/config/fromConfigField.ts

@@ -70,5 +70,6 @@ export function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig
     sections: [],
     showIf: new Map(),
     renderers: {},
+    dialogs: {},
   };
 }

package/src/config/index.ts

@@ -23,8 +23,8 @@ export {
   withValueAtPath,
 } from './path';
 export { resolveConfigSchema } from './resolve';
-export { type SectionTree, sectionTree } from './sectionTree';
 export { applyRules, builtinRules, titleCase } from './rules';
+export { type SectionTree, sectionTree } from './sectionTree';
 export type {
   Annotations,
   BranchAnnotations,
@@ -40,12 +40,15 @@ export type {
   ConfigSchema,
   ConfigShape,
   ControlRenderer,
+  DialogSpec,
   EntryValue,
+  InDialogOptions,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
+  SectionOption,
   SectionSpec,
   ValueAtPath,
 } from './types';

package/src/config/resolve.ts

@@ -7,6 +7,7 @@ import type {
   ConfigSchema,
   ConfigShape,
   ControlRenderer,
+  DialogSpec,
   LeafPatch,
   ResolvedConfig,
   SectionSpec,
@@ -25,6 +26,7 @@ interface Sink {
   sections: SectionSpec[];
   showIf: Map<string, (config: Record<string, unknown>) => boolean>;
   renderers: Record<string, ControlRenderer>;
+  dialogs: Record<string, DialogSpec>;
   chain: readonly ConfigRule[];
 }
 
@@ -45,10 +47,17 @@ export function resolveConfigSchema<TC>(
     sections: [],
     showIf: new Map(),
     renderers: {},
+    dialogs: {},
     chain: [...rules, ...builtinRules],
   };
   const group = resolveShape(schema.nodes, '', '', sink);
-  return { group, sections: sink.sections, showIf: sink.showIf, renderers: sink.renderers };
+  return {
+    group,
+    sections: sink.sections,
+    showIf: sink.showIf,
+    renderers: sink.renderers,
+    dialogs: sink.dialogs,
+  };
 }
 
 /** A section while it is still being filled. */
@@ -81,6 +90,7 @@ function resolveShape(shape: ConfigShape, at: string, name: string, sink: Sink):
     }
     if (predicate) sink.showIf.set(path, predicate);
     if (!isConfigBranch(entry) && entry.options.render) sink.renderers[path] = entry.options.render;
+    if (!isConfigBranch(entry) && entry.options.dialog) sink.dialogs[path] = entry.options.dialog;
   }
 
   return { name, children };

package/src/config/sectionTree.test.ts

@@ -70,14 +70,19 @@ describe('sectionTree', () => {
       'weight',
     ]);
     const off = sectionTree(resolved, { lineNumbers: false, listing: { dim: 1, weight: 0 } });
-    expect(Object.keys(groupAt(groupAt(off.group, 'view'), 'listing').children)).toEqual(['weight']);
+    expect(Object.keys(groupAt(groupAt(off.group, 'view'), 'listing').children)).toEqual([
+      'weight',
+    ]);
   });
 
   it('drops a section nothing in it is showing, rather than opening it onto nothing', () => {
     const resolved = resolveConfigSchema(
       f.schema({
         mode: f.enum<string>('a', ['a', 'b']).section('View'),
-        glow: f.number(1).section('Diff').showIf((c) => c.mode === 'b'),
+        glow: f
+          .number(1)
+          .section('Diff')
+          .showIf((c) => c.mode === 'b'),
       }),
     );
     expect(Object.keys(sectionTree(resolved, { mode: 'b', glow: 1 }).group.children)).toEqual([
@@ -91,7 +96,10 @@ describe('sectionTree', () => {
 
   it('keeps a hidden leaf out unless asked for it', () => {
     const resolved = resolveConfigSchema(
-      f.schema({ seed: f.number(1).hidden().section('Debug'), route: f.boolean(true).section('Debug') }),
+      f.schema({
+        seed: f.number(1).hidden().section('Debug'),
+        route: f.boolean(true).section('Debug'),
+      }),
     );
     expect(Object.keys(groupAt(sectionTree(resolved, {}).group, 'debug').children)).toEqual([
       'route',
@@ -134,9 +142,7 @@ describe('sectionTree', () => {
   it('ignores a section nested under a group, which buckets rows in a pane', () => {
     const resolved = resolveConfigSchema(
       f.schema({
-        cards: f
-          .group({ floor: f.number(1).section('Size') })
-          .section('View'),
+        cards: f.group({ floor: f.number(1).section('Size') }).section('View'),
       }),
     );
     const { group } = sectionTree(resolved, { cards: { floor: 1 } });

package/src/config/sectionTree.ts

@@ -1,4 +1,4 @@
-import { isPrefLeaf, type PrefGroup } from '@weasel-js/ui';
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
 import { valueAtPath } from './path';
 import type { ResolvedConfig } from './types';
 import { isLeafVisible } from './visible';
@@ -22,10 +22,20 @@ export interface SectionTree {
   pathAt: (railPath: string) => string;
 }
 
+/** Structural rather than `isPrefLeaf`, so the config entry stays free of a
+ *  runtime import from ui. */
+function isLeaf(node: PrefLeaf | PrefGroup): node is PrefLeaf {
+  return 'kind' in node;
+}
+
 /** A section label as an object key: no dots, since a dotted path is how every
  *  caller addresses a node, and a label is free to hold one. */
 function slugOf(label: string, taken: ReadonlySet<string>): string {
-  const base = label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'section';
+  const base =
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'section';
   if (!taken.has(base)) return base;
   for (let n = 2; ; n += 1) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`;
 }
@@ -44,7 +54,7 @@ function prune(
   for (const [key, child] of Object.entries(group.children)) {
     const path = at === '' ? key : `${at}.${key}`;
     if (!isLeafVisible(resolved, path, config, showHidden)) continue;
-    if (isPrefLeaf(child)) {
+    if (isLeaf(child)) {
       children[key] = child;
       continue;
     }
@@ -81,7 +91,7 @@ export function sectionTree(
       claimed.add(path);
       const child = resolved.group.children[path];
       if (!child || !isLeafVisible(resolved, path, config, showHidden)) continue;
-      if (isPrefLeaf(child)) {
+      if (isLeaf(child)) {
         kept[path] = child;
       } else {
         const subtree = prune(resolved, child, path, config, showHidden);
@@ -101,7 +111,7 @@ export function sectionTree(
   // gathers loose leaves into one item named for the root.
   for (const [key, child] of Object.entries(resolved.group.children)) {
     if (claimed.has(key) || !isLeafVisible(resolved, key, config, showHidden)) continue;
-    if (isPrefLeaf(child)) {
+    if (isLeaf(child)) {
       children[key] = child;
     } else {
       const subtree = prune(resolved, child, key, config, showHidden);

package/src/config/types.ts

@@ -5,6 +5,7 @@ import type {
   PrefNumberUnit,
   PrefRenderer,
 } from '@weasel-js/ui';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -104,6 +105,23 @@ export interface ResolvedConfig {
   showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
   /** Node-level `.render` overrides, keyed by path. */
   renderers: Readonly<Record<string, ControlRenderer>>;
+  /** Node-level `.dialog` rows, keyed by path. */
+  dialogs: Readonly<Record<string, DialogSpec>>;
+}
+
+/** Options for a row drawn as a button that opens a dialog. */
+export interface InDialogOptions {
+  /** What the row's button shows of the value. Defaults to a list joined with
+   *  commas, or the value itself. */
+  summary?: (value: unknown) => ReactNode;
+  /** The dialog's heading. Defaults to the row's label. */
+  title?: ReactNode;
+}
+
+/** A `.dialog` row: `body` is the dialog's content, handed the context a row
+ *  renderer gets. */
+export interface DialogSpec extends InDialogOptions {
+  body: ControlRenderer;
 }
 
 /** How a node names the section it belongs to: the heading, and how that
@@ -121,6 +139,9 @@ export interface SectionOption {
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
+  /** Draw the row as a button that opens a dialog. Set by `.dialog`; the
+   *  config entry records it, and `ControlPanel` draws it. */
+  dialog?: DialogSpec;
   /** Errors for this leaf under `config`, the instrument's whole config. */
   validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[];
   /** Computes this leaf's value while it is auto. Attaching one is what gives

package/src/controls/ControlPanel.test.tsx

@@ -372,6 +372,7 @@ describe('<ControlPanel> built-in kind coverage', () => {
     sections: [],
     showIf: new Map(),
     renderers: {},
+    dialogs: {},
   });
 
   it('declines paint and object with a named row rather than a blank one', () => {
@@ -1075,14 +1076,23 @@ describe('<ControlPanel> title, stance and tone', () => {
   const fields: ConfigField[] = [{ key: 'on', label: 'On', type: 'checkbox', default: true }];
 
   it('renders the bare list when given none of them', () => {
-    const { container } = render(<ControlPanel fields={fields} config={{ on: true }} setConfig={vi.fn()} />);
+    const { container } = render(
+      <ControlPanel fields={fields} config={{ on: true }} setConfig={vi.fn()} />,
+    );
     expect(container.firstElementChild?.classList.contains('lk-control-panel')).toBe(true);
     expect(container.querySelector('[data-stance], h2')).toBeNull();
   });
 
   it('wraps its rows in a panel carrying them when asked', () => {
     const { container } = render(
-      <ControlPanel title="View" stance="scope" tone={1} fields={fields} config={{ on: true }} setConfig={vi.fn()} />,
+      <ControlPanel
+        title="View"
+        stance="scope"
+        tone={1}
+        fields={fields}
+        config={{ on: true }}
+        setConfig={vi.fn()}
+      />,
     );
     const panel = container.firstElementChild as HTMLElement;
     expect(panel.dataset.stance).toBe('scope');

package/src/controls/ControlPanel.tsx

@@ -6,8 +6,8 @@ import {
   type PrefGroup,
   type PrefLeaf,
   type PropertyAlign,
-  type PropertyControlProps,
   PropertyControl,
+  type PropertyControlProps,
   type PropertyDensity,
   PropertyField,
   PropertyGroup,
@@ -26,7 +26,7 @@ import { fromConfigFields } from '../config/fromConfigField';
 import { schemaNodeAtPath, valueAtPath } from '../config/path';
 import type { ControlRenderer, ResolvedConfig, SectionSpec } from '../config/types';
 import { isLeafVisible } from '../config/visible';
-import { summarizeValue } from './inDialog';
+import { inDialog, summarizeValue } from './inDialog';
 import type { ConfigField } from './types';
 
 /** How a panel packs its rows into the two-column property grid.
@@ -243,7 +243,13 @@ export function ControlPanel<TC extends Record<string, unknown>>({
     if (pair === undefined) return undefined;
     if (!isLeafVisible(resolved, path, config as Record<string, unknown>, showHidden))
       return undefined;
-    if (renderers?.[path] ?? resolved.renderers[path] ?? renderers?.[found.kind]) return undefined;
+    if (
+      renderers?.[path] ??
+      resolved.renderers[path] ??
+      resolved.dialogs[path] ??
+      renderers?.[found.kind]
+    )
+      return undefined;
     if (!isBuiltinToolPref(found)) return undefined;
     if (found.kind === 'paint' || found.kind === 'object' || isSliderLeaf(found)) return undefined;
     return { leaf: found, pair };
@@ -405,8 +411,13 @@ function ControlRow<TC extends Record<string, unknown>>({
   const autoProps = { auto: isAutoRow, onAutoChange };
 
   // Most specific wins, and within a tier the lab's entry beats the
-  // instrument's: controls[path] -> node .render -> controls[kind] -> built-in.
-  const custom = renderers?.[path] ?? resolved.renderers[path] ?? renderers?.[leaf.kind];
+  // instrument's: controls[path] -> node .render/.dialog -> controls[kind] -> built-in.
+  const dialog = resolved.dialogs[path];
+  const custom =
+    renderers?.[path] ??
+    resolved.renderers[path] ??
+    (dialog ? inDialog(dialog.body, dialog) : undefined) ??
+    renderers?.[leaf.kind];
   // A custom row places itself like any other; one that needs the full width
   // says so with `<PropertyRow span>`, which is the same opt-out a built-in has.
   if (custom) return custom({ path, pref: leaf, value, setValue: write, auto: isAutoRow, setAuto });
@@ -442,7 +453,8 @@ function ControlRow<TC extends Record<string, unknown>>({
   }
 
   const field = labField(leaf, value, write);
-  if (field === null) return <UnwiredRow label={label} kind={leaf.kind} description={description} />;
+  if (field === null)
+    return <UnwiredRow label={label} kind={leaf.kind} description={description} />;
   switch (field.kind) {
     case 'string':
       return <DebouncedTextRow leaf={leaf} field={field} span={wide} {...row} />;
@@ -479,7 +491,10 @@ function labField(
         unit: extra<string>(leaf, 'suffix') ?? field.unit,
       };
     case 'boolean':
-      return { ...field, control: extra<string>(leaf, 'control') === 'switch' ? 'switch' : 'checkbox' };
+      return {
+        ...field,
+        control: extra<string>(leaf, 'control') === 'switch' ? 'switch' : 'checkbox',
+      };
     case 'enum':
       return { ...field, control: extra<string>(leaf, 'control') === 'radio' ? 'radio' : 'select' };
     case 'string':
@@ -605,7 +620,9 @@ function PairCell({
   if (field === null) return null;
   switch (field.kind) {
     case 'string':
-      return <PropertyControl {...field} name={leaf.name} value={text.local} onChange={text.type} />;
+      return (
+        <PropertyControl {...field} name={leaf.name} value={text.local} onChange={text.type} />
+      );
     case 'number':
       // The pair names the row, so a cell has no room for a unit.
       return <PropertyControl {...field} name={leaf.name} control="input" unit={undefined} />;
@@ -618,7 +635,9 @@ function PairCell({
           {...field}
           name={leaf.name}
           alpha={undefined}
-          onChange={(rgb: string) => write(field.alpha ? withAlpha01(rgb, getAlpha01(stored)) : rgb)}
+          onChange={(rgb: string) =>
+            write(field.alpha ? withAlpha01(rgb, getAlpha01(stored)) : rgb)
+          }
         />
       );
     }

package/src/controls/inDialog.test.tsx

@@ -69,6 +69,24 @@ describe('.dialog', () => {
     render(<Panel schema={schema} />);
     expect(screen.getByRole('button', { name: 'Edit Pts' }).textContent).toContain('3 points');
   });
+
+  it('gives way to a later .render, and takes over from an earlier one', () => {
+    const schema = f.schema({
+      a: f
+        .string('x')
+        .dialog(() => null)
+        .render(() => <span>row a</span>),
+      b: f
+        .string('y')
+        .render(() => <span>row b</span>)
+        .dialog(() => null),
+    });
+    render(<Panel schema={schema} />);
+    expect(screen.getByText('row a')).toBeTruthy();
+    expect(screen.queryByRole('button', { name: 'Edit A' })).toBeNull();
+    expect(screen.queryByText('row b')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Edit B' })).toBeTruthy();
+  });
 });
 
 describe('summarizeValue', () => {

package/src/controls/inDialog.tsx

@@ -1,15 +1,7 @@
 import { DialogRow } from '@weasel-js/ui';
-import type { ReactNode } from 'react';
-import type { ControlRenderer } from '../config/types';
+import type { ControlRenderer, InDialogOptions } from '../config/types';
 
-/** Options for {@link inDialog}. */
-export interface InDialogOptions {
-  /** What the row's button shows of the value. Defaults to a list joined with
-   *  commas, or the value itself. */
-  summary?: (value: unknown) => ReactNode;
-  /** The dialog's heading. Defaults to the row's label. */
-  title?: ReactNode;
-}
+export type { InDialogOptions };
 
 /** The one-line summary a dialog row shows when it is given none. */
 export function summarizeValue(value: unknown): string {

package/src/index.test.ts

@@ -72,7 +72,7 @@ describe('surface, job and orbit entry points', () => {
     expect(typeof kit.annotationsFromJSON).toBe('function');
     expect(typeof kit.seenFrom).toBe('function');
     expect(typeof kit.fracToWorld).toBe('function');
-    expect(typeof kit.usePanZoom).toBe('function');
+    expect(typeof kit.CameraInput).toBe('function');
     expect(typeof kit.useJob).toBe('function');
     expect(typeof kit.as2DView).toBe('function');
     expect(kit.SurfaceContext).toBeDefined();

package/src/index.ts

@@ -79,6 +79,7 @@ export type {
   AnnotationsCapability,
   AnnotationTarget,
   AnnotationTargetInfo,
+  AnnotationToolId,
   CaptureDeps,
   CaptureOptions,
   CaptureResult,
@@ -129,13 +130,12 @@ export {
 export type { ContentSize, PaneSize } from './annotations/view';
 export { fitView, fromWeaselView, toWeaselView } from './annotations/view';
 export type {
+  CameraContextValue,
   CanvasLayerDescriptor,
   CanvasStackContextValue,
   CanvasStackProps,
   CanvasStackSurface,
-  PanZoomHandlers,
   StageProps,
-  UsePanZoomOptions,
   ViewportSize,
   WorldFrame,
   WorldSpec,
@@ -143,6 +143,9 @@ export type {
 } from './canvas';
 export {
   applyCamera,
+  CameraContext,
+  CameraInput,
+  CameraScope,
   CanvasStack,
   CanvasStackContext,
   centerOn,
@@ -151,7 +154,6 @@ export {
   resolveFrame,
   Stage,
   screenToWorld,
-  usePanZoom,
   worldToScreen,
   zoomAt,
 } from './canvas';
@@ -173,7 +175,6 @@ export {
   ValueNode,
 } from './config/builder';
 export { fromConfigFields } from './config/fromConfigField';
-export { type SectionTree, sectionTree } from './config/sectionTree';
 export {
   fillConfigDefaults,
   hasConfigPath,
@@ -183,6 +184,7 @@ export {
 } from './config/path';
 export { resolveConfigSchema } from './config/resolve';
 export { applyRules, builtinRules, titleCase } from './config/rules';
+export { type SectionTree, sectionTree } from './config/sectionTree';
 export type {
   Annotations,
   BranchAnnotations,
@@ -198,12 +200,14 @@ export type {
   ConfigSchema,
   ConfigShape,
   ControlRenderer,
+  DialogSpec,
   EntryValue,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
+  SectionOption,
   SectionSpec,
   ValueAtPath,
 } from './config/types';

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

@@ -1,4 +1,5 @@
 import { render } from '@testing-library/react';
+import { createPointerStore } from '@weasel-js/core';
 import type { ReactElement } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import { DEFAULT_VIEW } from '../state/view';
@@ -94,6 +95,7 @@ describe('SineWave instrument smoke test', () => {
         setZoom: vi.fn(),
         activeToolId: null,
         visibleLayers: [],
+        pointer: createPointerStore(),
       },
       emit: vi.fn(),
     };

package/src/instrument/types.ts

@@ -1,3 +1,4 @@
+import type { PointerContextValue } from '@weasel-js/core';
 import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
@@ -33,6 +34,14 @@ export interface RenderContext<TS = unknown, TC = unknown> {
      *  hidden layer's `draw`, so this is the only way to know what was
      *  painted — a legend listing rows the view did not draw needs it. */
     visibleLayers: readonly string[];
+    /**
+     * Where the pointer is over this trial, in the instrument's world:
+     * `get()` answers `{ worldX, worldY, viewId }`, where `viewId` is
+     * `'stage'` over the trial's own camera and `'overview'` over its
+     * `<TrialOverview>`, or `null` when it is over neither. A key handler
+     * reading it works over either view.
+     */
+    pointer: PointerContextValue;
   };
   emit: (event: string) => void;
   /** Present only when the instrument declares a `job`. */
@@ -61,7 +70,7 @@ export interface CanvasCapability<TS = unknown, TC = unknown> {
    *  size, so an instrument can frame content it can only place in terms of
    *  the viewport; until then the trial's view is `null`. */
   initialView?: ViewTransform | ((size: ViewportSize) => ViewTransform);
-  /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
+  /** Widens the camera's default zoom clamp; the opening zoom stays reachable
    *  regardless of these. */
   minZoom?: number;
   maxZoom?: number;