@weasel-js/labkit 1.6.1 → 1.7.1

package/README.md

@@ -143,7 +143,6 @@ provide the corresponding chrome; they compose freely.
 | `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 |
@@ -307,14 +306,15 @@ directly. Several expose more than the root does, `/state` most of all.
 
 | Subpath | |
 | --- | --- |
-| `@weasel-js/labkit` | Everything |
+| `@weasel-js/labkit` | Everything but `/loupe` and `/overview` |
 | `/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>` from `@weasel-js/ui`, and the layers capability types |
-| `/loupe` | Magnifier components and `useLoupe` |
+| `/loupe` | `<TrialLoupe>`, the magnifier an instrument mounts in its content; the trial offers a Loupe toggle while one is mounted. Not in the root barrel |
+| `/overview` | `<TrialOverview>`, a floating panel showing a trial's whole content. Not in the root barrel |
 | `/surface` | Tiled surface hooks for your own renderer |
 | `/job` | `useJob` and the job capability types |
 | `/state` | The lab store, storage adapters, `useTrialState`, serialization helpers |

package/dist/_dts/{CanvasStackContext-Wo6OwIVM.d.ts → CanvasStackContext-Cjy6I-Iv.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { b as ViewTransform, W as WorldFrame } from './types-B7yBTTF9.js';
+import { a as ViewTransform, W as WorldFrame, b as WorldSpec } from './index-DCMA4Fy1.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */
@@ -25,6 +25,9 @@ interface CanvasStackSurface {
     canvases: RefObject<Map<string, HTMLCanvasElement>>;
     /** The layers as the stack is drawing them, bottom first. */
     layers: readonly CanvasLayerDescriptor[];
+    /** The coordinate system the stack was given, which `frame` resolves at
+     *  its size — for a re-draw at another size. */
+    worldSpec?: WorldSpec;
 }
 /** What a canvas stack publishes to its children: the view, and the resolved
  *  coordinate system it is read in, so DOM overlays can place themselves in the

package/dist/_dts/{Stage-DWBBi8IU.d.ts → Stage-D6t7o0pF.d.ts}

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { RefObject, ReactNode } from 'react';
-import { ViewApi } from '@weasel-js/core';
-import { W as WorldFrame, P as Point, b as ViewTransform, l as WorldSpec, V as ViewportSize } from './types-B7yBTTF9.js';
-import { C as CanvasLayerDescriptor } from './CanvasStackContext-Wo6OwIVM.js';
+import { ViewApi, Yoke } from '@weasel-js/core';
+import { W as WorldFrame, P as Point, a as ViewTransform, b as WorldSpec, V as ViewportSize } from './index-DCMA4Fy1.js';
+import { C as CanvasLayerDescriptor } from './CanvasStackContext-Cjy6I-Iv.js';
 
 /** The view id the stage publishes its pointer under. */
 declare const STAGE_VIEW_ID = "stage";
@@ -27,17 +27,16 @@ interface CameraContextValue {
 }
 /** The camera around the caller, or `null` outside one. */
 declare const CameraContext: react.Context<CameraContextValue | null>;
-/** Set by a host that already provides one input scope for everything inside
- *  it — a trial — so the camera, the loupe and an overview share it. */
-declare const CameraScopeContext: react.Context<boolean>;
 /**
- * The actions and deps a camera routes through: the ones a trial provides, or
- * an isolated set of its own. Isolated, because an actions registry holds one
- * dispatcher, and a camera must not take input from a canvas beside it. The
- * pointer store is the exception — one already in scope is kept, since sharing
- * it is the point.
+ * The input scope a camera routes through. Inside another camera — a loupe or
+ * an overlay laid over a canvas stack — it joins that camera's scope, so its
+ * actions reach the dispatcher already listening there. Anywhere else it
+ * mounts a scope of its own, which keeps its own tool unless it joins `yoke`:
+ * a camera beside another never takes that one's gestures. The pointer store is the exception — one
+ * already in scope is kept, since sharing it is the point.
  */
-declare function CameraScope({ children }: {
+declare function CameraScope({ yoke, children }: {
+    yoke?: Yoke;
     children: ReactNode;
 }): react.JSX.Element;
 /** Options for {@link useCameraView}. */
@@ -49,16 +48,27 @@ interface CameraViewOptions {
     minZoom?: number;
     maxZoom?: number;
 }
+/** A camera's zoom limits, after widening to admit its opening zoom. */
+interface ZoomRange {
+    min: number;
+    max: number;
+}
+/** A labkit camera: a weasel `ViewApi` that also says how far it zooms. */
+interface CameraView extends ViewApi {
+    zoomRange(): ZoomRange;
+}
 /**
  * A labkit camera as a stable `ViewApi`. Its zoom range is widened to keep the
  * opening zoom reachable — captured once, so a zoom-out cannot shrink the
  * range and strand the opening view behind it.
  */
-declare function useCameraView({ view, onViewChange, frame, hostRef, minZoom, maxZoom, }: CameraViewOptions): ViewApi;
+declare function useCameraView({ view, onViewChange, frame, hostRef, minZoom, maxZoom, }: CameraViewOptions): CameraView;
 /** Props for `<CameraInput>`. */
 interface CameraInputProps {
     hostRef: RefObject<HTMLElement | null>;
-    camera: ViewApi;
+    /** Published to the host's camera registry while its scope is the active
+     *  one, so chrome acting on "the camera" acts on the one last used. */
+    camera: CameraView;
     frame: WorldFrame;
     /** A primary-button press released without crossing the drag threshold, at
      *  the world point it landed on. */
@@ -89,12 +99,15 @@ interface CanvasStackProps {
     onResize?: (size: ViewportSize) => void;
     onHitTest?: (worldPos: Point) => void;
     children?: ReactNode;
+    /** A yoke to join, from `useYoke()`: cameras on one yoke share their tool
+     *  and gesture in flight. Omitted, this one keeps its own. */
+    yoke?: Yoke;
 }
 /** Stacks one `<canvas>` per layer and drives them from a shared view, so a
  *  layer that changes rarely is not redrawn with one that changes every frame.
  *  Handles sizing and device pixel ratio; pan and zoom route through weasel's
  *  gesture dispatcher (`<CameraInput>`). */
-declare function CanvasStack({ layers, view: viewProp, onViewChange, worldSpec, minZoom, maxZoom, width, height, className, onResize, onHitTest, children, }: CanvasStackProps): react.JSX.Element;
+declare function CanvasStack({ layers, view: viewProp, onViewChange, worldSpec, minZoom, maxZoom, width, height, className, onResize, onHitTest, children, yoke, }: CanvasStackProps): react.JSX.Element;
 
 /** Bounds and coordinate system a {@link zoomAt} works in. */
 interface ZoomAtOptions {
@@ -117,6 +130,31 @@ declare function zoomAt(view: ViewTransform, factor: number, at: Point, { frame,
  *  `zoom`. What a lens showing a region around one point renders through. */
 declare function centerOn(world: Point, zoom: number, size: ViewportSize, frame?: WorldFrame): ViewTransform;
 
+/**
+ * Cameras by key, for chrome that acts on a camera it does not contain — the
+ * lab's zoom controls, which drive whichever trial has the focus.
+ */
+interface CameraRegistry {
+    /** Publish `camera` under `key` and return its release. Registrants for one
+     *  key stack, newest live. */
+    register(key: string, camera: CameraView): () => void;
+    get(key: string): CameraView | null;
+    /** Fires after any register or release. Shaped for `useSyncExternalStore`. */
+    subscribe(listener: () => void): () => void;
+}
+/** An empty in-memory `CameraRegistry`. */
+declare function createCameraRegistry(): CameraRegistry;
+/** The registry a lab keeps its trials' cameras in. */
+declare const CameraRegistryContext: react.Context<CameraRegistry | null>;
+/** Where a camera publishes itself. The host binds the key — a trial provides
+ *  one that registers under its own id — so the camera needs no name. */
+declare const CameraPublishContext: react.Context<((camera: CameraView) => () => void) | null>;
+/** Publish `camera` to the host in scope for as long as the caller is mounted,
+ *  and again each time its input scope becomes the active one — a registry
+ *  key stacks newest-live, so the camera last used is the one chrome reaches.
+ *  Call it inside the camera's scope. */
+declare function usePublishCamera(camera: CameraView): void;
+
 /** Project a world point into screen coordinates under a view.
  *
  *  `frame` is the instrument's declared coordinate system, resolved against the
@@ -143,6 +181,9 @@ interface StageProps {
     /** Drawn over the content in viewport pixels, outside the camera. */
     overlay?: ReactNode;
     children?: ReactNode;
+    /** A yoke to join, from `useYoke()`: cameras on one yoke share their tool
+     *  and gesture in flight. Omitted, this one keeps its own. */
+    yoke?: Yoke;
 }
 /**
  * The camera a stage opens at: the content centered in its viewport, shrunk to
@@ -156,7 +197,7 @@ declare function fitStage(size: ViewportSize, viewport: ViewportSize): ViewTrans
  * its own size and transformed, so everything inside keeps its layout and a
  * measurement of any element in it reports where it is actually drawn.
  */
-declare function Stage({ size, view: viewProp, onViewChange, minZoom, maxZoom, onResize, hostRef, overlay, children, }: StageProps): react.JSX.Element;
+declare function Stage({ size, view: viewProp, onViewChange, minZoom, maxZoom, onResize, hostRef, overlay, children, yoke, }: StageProps): react.JSX.Element;
 
-export { CameraContext as C, STAGE_VIEW_ID as S, CameraInput as b, CameraScope as d, CameraScopeContext as e, CanvasStack as g, Stage as i, centerOn as k, fitStage as l, screenToWorld as s, useCameraView as u, worldToScreen as w, zoomAt as z };
-export type { ZoomAtOptions as Z, CameraContextValue as a, CameraInputProps as c, CameraViewOptions as f, CanvasStackProps as h, StageProps as j };
+export { CameraContext as C, STAGE_VIEW_ID as S, CameraInput as b, CameraPublishContext as d, CameraRegistryContext as f, CameraScope as g, CanvasStack as j, Stage as l, centerOn as o, createCameraRegistry as p, fitStage as q, usePublishCamera as r, screenToWorld as s, useCameraView as u, worldToScreen as w, zoomAt as z };
+export type { ZoomAtOptions as Z, CameraContextValue as a, CameraInputProps as c, CameraRegistry as e, CameraView as h, CameraViewOptions as i, CanvasStackProps as k, StageProps as m, ZoomRange as n };

package/dist/_dts/{index-CKyX0ME_.d.ts → index-BTmaRy6a.d.ts}

@@ -1,8 +1,11 @@
-import { d as ControlRenderer, c as ConfigRule } from './types-DTuViBvc.js';
-import { R as Instrument, ax as TrialChromeContext, Y as TrialContribution, T as TrialRecord, t as InstrumentList, f as SavedSnapshot, s as LabMode, av as ToolSlotContext, a9 as ContributionBase, aw as ToolbarItem, au as ToolItem, ao as SidebarSection, ar as StatusReadout, O as TrialTool, ak as RegionContribution, ap as SidebarSlotContext } from './types-B7yBTTF9.js';
+import { c as ControlRenderer, b as ConfigRule } from './types-BUBSIZuV.js';
+import { O as Instrument, ar as TrialChromeContext, R as TrialContribution, T as TrialRecord, q as InstrumentList, e as SavedSnapshot, o as LabMode, ap as ToolSlotContext, a8 as ContributionBase, aq as ToolbarItem, ao as ToolItem, ai as SidebarSection, al as StatusReadout, K as TrialTool, af as RegionContribution, aj as SidebarSlotContext } from './index-DCMA4Fy1.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
+/** Built-in ids contributed only while runtime state says so — the loupe
+ *  toggle appears once a lens mounts, after the trial's first render. */
+declare const TRANSIENT_BUILTINS: ReadonlySet<string>;
 /**
  * The contributions a trial gets from what its instrument declared. This is
  * the whole "declaring a capability provides the chrome" rule — it replaces
@@ -165,11 +168,12 @@ declare function mergeContributions<T extends {
 /**
  * Drop contributions by id. Throws when an id is not present: a typo that
  * silently suppresses nothing is the same class of bug as a duplicate id
- * silently winning.
+ * silently winning. `transient` names ids that are legitimately absent at
+ * times — contributed only while some runtime state holds.
  */
 declare function suppressContributions<T extends {
     id: string;
-}>(bundle: readonly T[], ids: readonly string[]): T[];
+}>(bundle: readonly T[], ids: readonly string[], transient?: ReadonlySet<string>): T[];
 
 /** Props for `<PaletteRegion>`. */
 interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext> {
@@ -244,5 +248,5 @@ interface ViewportRegionProps {
  */
 declare function ViewportRegion({ contributions, ctx }: ViewportRegionProps): react.JSX.Element | null;
 
-export { resetTrial as B, suppressContributions as C, toolContributions as D, useLabChromeContext as E, useLabContext as F, PaletteRegion as P, SidebarRegion as S, ViewportRegion as V, LabAsideRegion as a, LabContext as c, LabFooterRegion as e, LabHeaderRegion as f, LabSidebarRegion as i, StatusRegion as l, TitleBarRegion as n, ToolbarRegion as p, addTrial as s, builtinContributions as t, cloneTrial as u, closeTrial as v, contributionsIn as w, labContributions as x, mergeContributions as y, reorderTrials as z };
-export type { AddTrialOptions as A, LabContribution as L, TitleBarPlacement as T, LabChromeContext as b, LabContextValue as d, LabRegion as g, LabRegionProps as h, PaletteRegionProps as j, SidebarRegionProps as k, StatusRegionProps as m, TitleBarRegionProps as o, ToolbarRegionProps as q, ViewportRegionProps as r };
+export { reorderTrials as B, resetTrial as C, suppressContributions as D, toolContributions as E, useLabChromeContext as F, useLabContext as G, PaletteRegion as P, SidebarRegion as S, TRANSIENT_BUILTINS as T, ViewportRegion as V, LabAsideRegion as a, LabContext as c, LabFooterRegion as e, LabHeaderRegion as f, LabSidebarRegion as i, StatusRegion as l, TitleBarRegion as o, ToolbarRegion as q, addTrial as t, builtinContributions as u, cloneTrial as v, closeTrial as w, contributionsIn as x, labContributions as y, mergeContributions as z };
+export type { AddTrialOptions as A, LabContribution as L, LabChromeContext as b, LabContextValue as d, LabRegion as g, LabRegionProps as h, PaletteRegionProps as j, SidebarRegionProps as k, StatusRegionProps as m, TitleBarPlacement as n, TitleBarRegionProps as p, ToolbarRegionProps as r, ViewportRegionProps as s };

package/dist/_dts/{types-B7yBTTF9.d.ts → index-DCMA4Fy1.d.ts}

@@ -1,8 +1,9 @@
-import { DrawCommand, Scene, PointerContextValue } from '@weasel-js/core';
+import { StanceProps } from '@weasel-js/ui';
+import { View, DrawCommand, Scene, PointerContextValue } from '@weasel-js/core';
 import { RefObject, ComponentType, ReactNode } from 'react';
-import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
-import { R as ResolvedConfig, C as ConfigPath, V as ValueAtPath, a as ConfigField, b as ConfigSchema } from './types-DTuViBvc.js';
 import { ColorModePreference } from '@weasel-js/theme';
+import { R as ResolvedConfig, n as ConfigPath, V as ValueAtPath, a as ConfigField, C as ConfigSchema } from './types-BUBSIZuV.js';
+import { Rect } from '@weasel-js/geom';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
 
 /**
@@ -15,6 +16,7 @@ import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
 declare const auto: unique symbol;
 /** The type of the `auto` sentinel, for widening a value parameter. */
 type Auto = typeof auto;
+/** Whether `value` is the `auto` sentinel. */
 declare function isAuto(value: unknown): value is Auto;
 
 /** A sidebar section torn out of its trial, and where it went. */
@@ -25,7 +27,10 @@ interface UndockedPanel {
 }
 /** Undocked panels, keyed by {@link panelKey}. */
 type UndockedPanels = Record<string, UndockedPanel>;
+/** The `UndockedPanels` key for one trial's section. */
 declare function panelKey(trialId: string, sectionId: string): string;
+/** `panels` with the section marked undocked `as` a tile or a floating panel,
+ *  replacing any earlier entry for it. Returns a new record. */
 declare function undockPanel(panels: UndockedPanels, trialId: string, sectionId: string, as?: UndockedPanel['as']): UndockedPanels;
 /** Dock one section back, or — with no `sectionId` — every panel the trial
  *  owns, which is what closing a trial wants. */
@@ -218,12 +223,7 @@ type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;
 
 /** A mark's box in its target's world: CSS pixels at zoom 1. Matches weasel's
  *  default `RectPose`, which is what the scene stores. */
-interface WorldRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
+type WorldRect = Rect;
 /** Where a fraction lands on a content box of this size. */
 declare function fracToWorld(f: FracRect, content: {
     w: number;
@@ -267,14 +267,15 @@ interface MarkStyle {
 /**
  * What one mark draws, in its target's world.
  *
- * Pure: a node and the target's content box in, draw commands out. Geometry
- * that a bounding box cannot describe — a line's ends, a stroke's path — comes
- * from `data.points`, which is in fractions like the bounds.
+ * Pure: a node in, draw commands out, in its target's world. Geometry that a
+ * bounding box cannot describe — a line's ends, a stroke's path — comes from
+ * `data.shape`, placed in the pose.
+ *
+ * `scale` is the view's, world to screen. Only a point reads it — its ring is
+ * sized in screen pixels — and the default draws that ring as though a world
+ * unit were a pixel.
  */
-declare function markCommands(m: PaintableMark, content: {
-    w: number;
-    h: number;
-}, style?: MarkStyle): DrawCommand[];
+declare function markCommands(m: PaintableMark, style?: MarkStyle, scale?: View['scale']): DrawCommand[];
 
 /** A mark's box in its target's world. Matches weasel's default `RectPose`. */
 type MarkPose = WorldRect;
@@ -282,6 +283,7 @@ type MarkPose = WorldRect;
 type MarkScene = Scene<AnnotationData, 'marks', MarkPose>;
 /** A mark scene: one layer, because marks do not stack in tiers. */
 declare function createAnnotationScene(): MarkScene;
+/** Inputs to `createAnnotationStore`. */
 interface AnnotationStoreOptions {
     /** Re-read on every call, so a target resizing or gaining a dependency takes
      *  effect without rebuilding the store. */
@@ -297,6 +299,10 @@ interface AnnotationStoreOptions {
     config?: () => unknown;
     /** Notified after every finished export. */
     onCapture?: (result: CaptureResult) => void;
+    /** Whether a selection can stand in several targets at once. `'exclusive'`
+     *  (the default) clears every other target when a mark is selected in one.
+     *  A thunk is read at each selection change. */
+    selection?: AnnotationSelectionMode | (() => AnnotationSelectionMode | undefined);
 }
 /** Everything a capture needs that is not the store's own state. Split out so
  *  `capture.ts` takes data rather than reaching back into the store. */
@@ -338,8 +344,8 @@ interface FracRect {
     h: number;
 }
 /** What shape a mark is. The kinds map onto weasel's own tools; an arrow is a
- *  line carrying an end marker, not a separate geometry. A point holds one
- *  entry in `points` and zero-size bounds at that position. */
+ *  line carrying an end marker, not a separate geometry. A point is zero-size
+ *  bounds at its position. */
 type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text' | 'point';
 /** One selectable status in an instrument's meaning tier. */
 interface AnnotationStatus {
@@ -360,8 +366,11 @@ interface AnnotationData {
     target: string;
     kind: AnnotationKind;
     /** Vertices for the kinds a bounding box cannot describe — a line's two
-     *  ends, a stroke's path. In fractions, like the bounds. */
-    points?: readonly FracPoint[];
+     *  ends, a stroke's path — in fractions of the mark's own bounds, so moving
+     *  or resizing the bounds carries them along. A point stores none: it is its
+     *  bounds' origin. `Annotation.points` is this restated in the target's
+     *  content box. */
+    shape?: readonly FracPoint[];
     title?: string;
     status?: string;
     tags?: readonly string[];
@@ -373,16 +382,21 @@ interface AnnotationData {
 }
 /** A mark, as the store reports it. `id` is `<target>/<node>`: one scene per
  *  target means a node id is only unique within one. */
-interface Annotation extends AnnotationData {
+interface Annotation extends Omit<AnnotationData, 'shape'> {
     id: string;
     /** Bounds in fractions of the target's content box. */
     frac: FracRect;
+    /** Vertices in fractions of the target's content box, wherever the bounds
+     *  now are. A point's one entry is its bounds' origin. */
+    points?: readonly FracPoint[];
 }
 /** A new mark, before the store gives it an id and dates it. */
 interface AnnotationInit {
     target: string;
     kind: AnnotationKind;
     frac: FracRect;
+    /** In the target's content box. Stored relative to `frac`, so they should
+     *  lie inside it; a point takes its position from `frac` alone. */
     points?: readonly FracPoint[];
     title?: string;
     status?: string;
@@ -398,7 +412,8 @@ interface AnnotationQuery {
     where?: (a: Annotation) => boolean;
 }
 /** What a mark's meaning can be patched to. Geometry moves through `frac` /
- *  `points`; everything else is the meaning tier. */
+ *  `points`; everything else is the meaning tier. `frac` alone carries the
+ *  vertices with it; `points` alone moves the bounds to enclose them. */
 type AnnotationPatch = Partial<Pick<Annotation, 'frac' | 'points' | 'title' | 'status' | 'tags' | 'meta'>>;
 /** A target's own picture, handed over for an export to draw marks on top of.
  *  labkit cannot rasterize it: it is the consumer's DOM. `svg` is the one that
@@ -468,10 +483,14 @@ interface AnnotationStorage {
     load: () => Promise<SerializedAnnotations | null | undefined>;
     save: (doc: SerializedAnnotations) => void;
 }
-/** Declares that an instrument accepts marks: which regions take them,
- *  optionally what a mark is allowed to mean, and optionally where they live. */
 /** The annotation tools a lab's rail can carry. */
 type AnnotationToolId = 'pointer' | 'select' | 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text';
+/** Whether a selection can stand in several of a trial's targets at once.
+ *  `'exclusive'` clears every other target when a mark is selected in one;
+ *  `'per-target'` lets each target keep its own. */
+type AnnotationSelectionMode = 'exclusive' | 'per-target';
+/** Declares that an instrument accepts marks: which regions take them,
+ *  optionally what a mark is allowed to mean, and optionally where they live. */
 interface AnnotationsCapability<TS = unknown, TC = unknown> {
     /** `trial` is which trial is asking: a declaration made once per instrument
      *  is called once per trial, and its targets are that trial's own. */
@@ -488,6 +507,9 @@ interface AnnotationsCapability<TS = unknown, TC = unknown> {
      *  notification, not an interception: a host wanting its own flow calls
      *  `capture()` from its own UI, which is the surface the chrome uses. */
     onCapture?: (result: CaptureResult) => void;
+    /** Defaults to `'exclusive'`: selecting a mark in one target clears the
+     *  selection in every other. */
+    selection?: AnnotationSelectionMode;
 }
 /** A persisted mark set. Versioned by this arc rather than by labkit's
  *  document migrations, which only ever reach top-level document sections and
@@ -526,11 +548,13 @@ interface AnnotationsApi {
      *  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. */
+     *  there is dropped, the way `update` and `remove` ignore one. Under an
+     *  `'exclusive'` selection, so is every id outside the first id's target. */
     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()`. */
+     *  channel. A selection change touching several targets is one event. 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. */
@@ -559,7 +583,7 @@ interface AnnotationsApi {
  *  world (0,0) at the element's top-left, y growing downward. */
 interface WorldSpec {
     /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.
-     *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */
+     *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` center. */
     origin?: Point;
     /** Which way the world y axis runs on screen. Default `'down'`. */
     yAxis?: 'down' | 'up';
@@ -576,7 +600,9 @@ interface WorldFrame {
     originPx: Point;
     yDir: 1 | -1;
 }
+/** The frame an absent `WorldSpec` resolves to: origin top-left, y down. */
 declare const DEFAULT_FRAME: WorldFrame;
+/** Resolve `spec` against a viewport of `size`; `undefined` gives `DEFAULT_FRAME`. */
 declare function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame;
 /** Put a 2D context into the instrument's world coordinates, so a layer's
  *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */
@@ -744,8 +770,10 @@ interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext {
     canRedo: boolean;
     undo: () => void;
     redo: () => void;
-    /** Whether the trial's loupe is turned on. False for an instrument that
-     *  declares none, whose chrome offers no way to turn one on. */
+    /** Whether a `<TrialLoupe>` following the trial's toggle is mounted in it.
+     *  The loupe toggle is offered only while one is. */
+    hasLoupe: boolean;
+    /** Whether the trial's loupe is turned on. */
     loupeOn: boolean;
     toggleLoupe: () => void;
     /** The instrument's controls, resolved against the lab's rules. Always
@@ -780,83 +808,6 @@ interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext {
     close: () => void;
 }
 
-/** A point on the magnified surface, in its own CSS pixels. */
-interface LoupePoint {
-    x: number;
-    y: number;
-}
-
-/** How a loupe magnifies. `'vector'` re-renders the source through a zoomed-in
- *  view, so content stays sharp at any factor; `'pixel'` blows up the actual
- *  pixels the surface presented. */
-type LoupeMode = 'vector' | 'pixel';
-
-/** What a DOM instrument's loupe `render` is handed: the same data its own
- *  `render` gets, and the camera to draw it through. */
-interface LoupeRenderArgs<TS = unknown, TC = unknown> {
-    state: TS;
-    config: TC;
-    /** The trial's own camera composed with the magnification, about the aimed
-     *  point — so drawing the same content through it magnifies in place. */
-    view: ViewTransform;
-    /** The magnification on its own, for whatever must not scale with the
-     *  camera. */
-    factor: number;
-    mode: LoupeMode;
-    /** The size of the viewport `view` is written for: the trial's content well,
-     *  not the lens. The lens shows a circle cut out of it. */
-    size: ViewportSize;
-}
-/**
- * Declares that an instrument can be magnified.
- *
- * With no `render`, the loupe re-draws the instrument's canvas layers through a
- * zoomed camera, so it stays sharp at any factor. An instrument whose content is
- * DOM supplies `render` instead: given a camera, draw me again.
- */
-interface LoupeCapability<TS = unknown, TC = unknown> {
-    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
-    /** Opening magnification, clamped to the bounds below. Default 6. */
-    factor?: number;
-    /** What the wheel clamps to. Defaults 2 and 32. */
-    minFactor?: number;
-    maxFactor?: number;
-    /** `'vector'` (default) re-renders the content magnified; `'pixel'` blows up
-     *  the pixels the instrument presented. A `render` loupe is always vector —
-     *  DOM has no framebuffer to enlarge. */
-    mode?: LoupeMode;
-    /** Lens diameter in CSS px. Default 200. */
-    diameter?: number;
-    /** Held for a momentary peek while the loupe is off. Default `'Alt'`; `null`
-     *  turns hold-to-peek off. Matched against `KeyboardEvent.key`. */
-    peekKey?: string | null;
-    /** Called with the color under the aim, wherever the surface can say. The
-     *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
-    onColorChange?: (hex: string) => void;
-}
-/** An instrument's loupe declaration. `true` takes every default. */
-type LoupeDeclaration<TS = unknown, TC = unknown> = true | LoupeCapability<TS, TC>;
-/** A {@link LoupeCapability} with every default filled in. */
-interface ResolvedLoupe<TS = unknown, TC = unknown> {
-    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
-    onColorChange?: (hex: string) => void;
-    factor: number;
-    minFactor: number;
-    maxFactor: number;
-    mode: LoupeMode;
-    diameter: number;
-    peekKey: string | null;
-}
-declare const LOUPE_DEFAULTS: {
-    readonly factor: 6;
-    readonly minFactor: 2;
-    readonly maxFactor: 32;
-    readonly mode: "vector";
-    readonly diameter: 200;
-    readonly peekKey: "Alt";
-};
-declare function resolveLoupe<TS, TC>(declared: LoupeDeclaration<TS, TC>): ResolvedLoupe<TS, TC>;
-
 /**
  * A tool a trial can be in. labkit's own — core's `ToolsApi` carries hotkey
  * slots, ambient tools, eligibility tiers and canvas overlay layers, all bound
@@ -1070,11 +1021,6 @@ interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
      *  is allowed to mean. Declaring it is what makes the trial provide the
      *  annotation overlay and its chrome. */
     annotations?: AnnotationsCapability<TS, TC>;
-    /** Magnification. `true` takes every default and re-draws the instrument's
-     *  canvas layers through a zoomed camera; an instrument whose content is DOM
-     *  gives a `render` that draws it again at a camera it is handed. A function
-     *  is re-read as the config changes, so a setting can drive the lens. */
-    loupe?: LoupeDeclaration<TS, TC> | ((config: TC) => LoupeDeclaration<TS, TC>);
     /** Chrome this instrument contributes beyond what its capabilities imply. */
     chrome?: TrialContribution[];
     /** Work too slow to do during a render. The runtime starts it, aborts it on
@@ -1086,5 +1032,5 @@ interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
  *  an `Instrument<unknown, unknown>[]`; it is contained to this alias. */
 type InstrumentList = readonly Instrument<any, any, any>[];
 
-export { DEFAULT_FRAME as D, annotationsFromJSON as aB, auto as aC, createAnnotationScene as aD, createAnnotationStore as aE, fracContains as aF, fracEncloses as aG, fracToWorld as aH, isAuto as aI, markCommands as aJ, resolveLoupe as aK, roundFrac as aL, worldToFrac as aM, LOUPE_DEFAULTS as ae, dockPanel as k, applyCamera as m, panelKey as p, resolveFrame as r, undockPanel as u };
-export type { AnnotationPatch as $, AnnotationMeaning as A, CaptureSource as B, CreateLabStoreOptions as C, CaptureOptions as E, CaptureResult as F, PaintableMark as G, AnnotationTarget as H, InstrumentSerializers as I, AnnotationsApi as J, AnnotationsCapability as K, LayerCapability as L, Migration as M, TrialInfo as N, TrialTool as O, Point as P, AnnotationKind as Q, Instrument as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, LabDensity as X, TrialContribution as Y, Annotation as Z, AnnotationInit as _, LayerDescriptor as a, AnnotationQuery as a0, AnnotationStatus as a1, AnnotationStoreOptions as a2, AnnotationTargetInfo as a3, AnnotationToolId as a4, Auto as a5, CanvasCapability as a6, CanvasLayer as a7, CaptureDeps as a8, ContributionBase as a9, ViewportControl as aA, FracPoint as aa, FracRect as ab, HitResult as ac, IconComponent as ad, LoupeCapability as af, LoupeDeclaration as ag, LoupeMode as ah, LoupePoint as ai, LoupeRenderArgs as aj, RegionContribution as ak, RenderContext as al, ResolvedLoupe as am, SerializedAnnotations as an, SidebarSection as ao, SidebarSlotContext as ap, StageCapability as aq, StatusReadout as ar, SystemEvent as as, ToolCapability as at, ToolItem as au, ToolSlotContext as av, ToolbarItem as aw, TrialChromeContext as ax, TrialRegion as ay, UndoCapability as az, ViewTransform as b, StorageAdapter as c, LabDocument as d, LabStoreState as e, SavedSnapshot as f, StorageChange as g, TrialStateHandle as h, UndockedPanel as i, UndockedPanels as j, WorldSpec as l, PaletteItem as n, DragFeedback as o, DragDropCapability as q, LabMode as s, InstrumentList as t, InstrumentHooks as v, AnnotationData as w, WorldRect as x, MarkStyle as y, MarkScene as z };
+export { DEFAULT_FRAME as D, fracEncloses as aA, fracToWorld as aB, isAuto as aC, markCommands as aD, roundFrac as aE, worldToFrac as aF, annotationsFromJSON as av, auto as aw, createAnnotationScene as ax, createAnnotationStore as ay, fracContains as az, dockPanel as j, applyCamera as k, panelKey as p, resolveFrame as r, undockPanel as u };
+export type { AnnotationSelectionMode as $, AnnotationMeaning as A, CaptureResult as B, CreateLabStoreOptions as C, PaintableMark as E, AnnotationTarget as F, AnnotationsApi as G, AnnotationsCapability as H, InstrumentSerializers as I, TrialInfo as J, TrialTool as K, LabDocument as L, Migration as M, AnnotationKind as N, Instrument as O, Point as P, LabDensity as Q, TrialContribution as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, Annotation as X, AnnotationInit as Y, AnnotationPatch as Z, AnnotationQuery as _, ViewTransform as a, AnnotationStatus as a0, AnnotationStoreOptions as a1, AnnotationTargetInfo as a2, AnnotationToolId as a3, Auto as a4, CanvasCapability as a5, CanvasLayer as a6, CaptureDeps as a7, ContributionBase as a8, FracPoint as a9, FracRect as aa, HitResult as ab, IconComponent as ac, LayerCapability as ad, LayerDescriptor as ae, RegionContribution as af, RenderContext as ag, SerializedAnnotations as ah, SidebarSection as ai, SidebarSlotContext as aj, StageCapability as ak, StatusReadout as al, SystemEvent as am, ToolCapability as an, ToolItem as ao, ToolSlotContext as ap, ToolbarItem as aq, TrialChromeContext as ar, TrialRegion as as, UndoCapability as at, ViewportControl as au, WorldSpec as b, StorageAdapter as c, LabStoreState as d, SavedSnapshot as e, StorageChange as f, TrialStateHandle as g, UndockedPanel as h, UndockedPanels as i, PaletteItem as l, DragFeedback as m, DragDropCapability as n, LabMode as o, InstrumentList as q, InstrumentHooks as s, AnnotationData as t, WorldRect as v, MarkStyle as w, MarkScene as x, CaptureSource as y, CaptureOptions as z };

package/dist/_dts/{types-DTuViBvc.d.ts → types-BUBSIZuV.d.ts}

@@ -1,6 +1,6 @@
+import { Display } from '@weasel-js/quantity';
+import { PrefNumberUnit, PrefRenderer, PrefLeaf, PrefGroup } from '@weasel-js/ui';
 import { ReactNode } from 'react';
-import { ToolPrefNumberFormat, ToolPrefNumberUnit, ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
-import { P as PrefRenderer } from './PrefsRow.d-DFpPIeIC.js';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -12,6 +12,10 @@ type ControlRenderer = PrefRenderer;
 interface ConfigOption {
     value: string;
     label: string;
+    /** A glyph in weasel-ui's icon set (`IconName`). A segmented row draws it in
+     *  place of `label`, which stays the accessible name and becomes the tooltip;
+     *  a select draws it beside `label`. */
+    icon?: string;
 }
 /** Everything a leaf can carry beyond its kind and default. A flat union of
  *  every `Pref*` leaf's extras, plus labkit's own `debounceMs`. */
@@ -25,11 +29,11 @@ interface Annotations {
     max?: number;
     step?: number;
     suffix?: string;
-    /** How a number's value is shown. `compact` abbreviates from a thousand up. */
-    format?: ToolPrefNumberFormat;
+    /** How a number's value shows, speaks and reads back — `compact()` reads `2.00M`. */
+    display?: Display;
     /** Display-unit conversion for a number stored in a canonical unit — the
      *  value, its bounds and its step all convert at the control's edge. */
-    unit?: ToolPrefNumberUnit;
+    unit?: PrefNumberUnit;
     /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
     alpha?: boolean;
     control?: string;
@@ -90,13 +94,16 @@ interface SectionSpec {
 interface ResolvedConfig {
     /** The schema as a `PrefGroup` tree: an `f.group` is a nested group, so a
      *  leaf's dotted path within it is the path its value is written at. */
-    group: ToolPrefGroup;
+    group: PrefGroup;
     sections: readonly SectionSpec[];
     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>>;
+    /** Paths of the groups marked `.resettable()`, whose heading carries a
+     *  button that puts every value beneath it back to its default. */
+    resettable?: ReadonlySet<string>;
 }
 /** Options for a row drawn as a button that opens a dialog. */
 interface InDialogOptions {
@@ -129,7 +136,7 @@ interface NodeOptions extends BranchOptions {
      *  config entry records it, and `ControlPanel` draws it. */
     dialog?: DialogSpec;
     /** Errors for this leaf under `config`, the instrument's whole config. */
-    validate?: (leaf: ToolPrefLeaf, config: Record<string, unknown>) => string[];
+    validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[];
     /** Computes this leaf's value while it is auto. Attaching one is what gives
      *  the row a real value to pin back to and keeps the instrument off
      *  `?? compute()`. */
@@ -147,6 +154,9 @@ interface BranchOptions {
     /** Show this node only while the predicate holds. On a group it hides the
      *  whole subtree; the values stay in config either way. */
     showIf?: (config: Record<string, unknown>) => boolean;
+    /** Put a button on this group's heading that returns every value beneath it
+     *  to its default. Groups only. */
+    resettable?: boolean;
 }
 /** A group's own annotations: what it is called and, optionally, why. */
 interface BranchAnnotations {
@@ -269,4 +279,4 @@ interface ColorField extends ConfigFieldBase {
  *  panel renders, and what `validateConfigSchema` checks. */
 type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
 
-export type { Annotations as A, BranchAnnotations as B, ConfigPath as C, DialogSpec as D, EntryValue as E, InDialogOptions as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionOption as S, TextField as T, ValueAtPath as V, ConfigField as a, ConfigSchema as b, ConfigRule as c, ControlRenderer as d, BranchOptions as e, CheckboxField as f, ColorField as g, ConfigBranch as h, ConfigEntry as i, ConfigFieldBase as j, ConfigFieldType as k, ConfigNode as l, ConfigOf as m, ConfigOption as n, ConfigRuleContext as o, ConfigShape as p, InferConfig as q, NodeValue as r, NumberField as s, SectionSpec as t, SelectField as u, SelectOption as v, SliderField as w };
+export type { Annotations as A, BranchAnnotations as B, ConfigSchema as C, DialogSpec as D, EntryValue as E, InDialogOptions as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionOption as S, TextField as T, ValueAtPath as V, ConfigField as a, ConfigRule as b, ControlRenderer as c, BranchOptions as d, CheckboxField as e, ColorField as f, ConfigBranch as g, ConfigEntry as h, ConfigFieldBase as i, ConfigFieldType as j, ConfigNode as k, ConfigOf as l, ConfigOption as m, ConfigPath as n, ConfigRuleContext as o, ConfigShape as p, InferConfig as q, NodeValue as r, NumberField as s, SectionSpec as t, SelectField as u, SelectOption as v, SliderField as w };

package/dist/_dts/{useTrialState-CMaV6UD4.d.ts → useTrialState-Bh8bzFgE.d.ts}

@@ -1,4 +1,4 @@
-import { c as StorageAdapter, e as LabStoreState, T as TrialRecord, f as SavedSnapshot, s as LabMode, i as UndockedPanel, t as InstrumentList, v as InstrumentHooks, C as CreateLabStoreOptions, h as TrialStateHandle } from './types-B7yBTTF9.js';
+import { c as StorageAdapter, d as LabStoreState, T as TrialRecord, e as SavedSnapshot, o as LabMode, h as UndockedPanel, q as InstrumentList, s as InstrumentHooks, C as CreateLabStoreOptions, g as TrialStateHandle } from './index-DCMA4Fy1.js';
 import * as react from 'react';
 import { ReactNode, ReactElement, Dispatch, SetStateAction } from 'react';
 import { StoreApi } from 'zustand/vanilla';