@weasel-js/labkit 1.7.0 → 1.7.1

package/src/canvas/cameraRegistry.ts

@@ -15,6 +15,7 @@ export interface CameraRegistry {
   subscribe(listener: () => void): () => void;
 }
 
+/** An empty in-memory `CameraRegistry`. */
 export function createCameraRegistry(): CameraRegistry {
   const stacks = new Map<string, CameraView[]>();
   const listeners = new Set<() => void>();

package/src/canvas/worldSpec.ts

@@ -5,7 +5,7 @@ import type { Point, ViewTransform } from '../instrument/types';
  *  world (0,0) at the element's top-left, y growing downward. */
 export 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';
@@ -25,8 +25,10 @@ export interface WorldFrame {
   yDir: 1 | -1;
 }
 
+/** The frame an absent `WorldSpec` resolves to: origin top-left, y down. */
 export const DEFAULT_FRAME: WorldFrame = { originPx: { x: 0, y: 0 }, yDir: 1 };
 
+/** Resolve `spec` against a viewport of `size`; `undefined` gives `DEFAULT_FRAME`. */
 export function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame {
   if (!spec) return DEFAULT_FRAME;
   const origin = spec.origin ?? { x: 0, y: 0 };

package/src/chrome/builtins.test.ts

@@ -23,6 +23,7 @@ const ctx: TrialChromeContext = {
   canRedo: false,
   undo: () => {},
   redo: () => {},
+  hasLoupe: false,
   loupeOn: false,
   toggleLoupe: () => {},
   configFields: [],
@@ -72,21 +73,21 @@ describe('builtinContributions', () => {
     expect(ids({ ...bare, undo: {} })).toContain('redo');
   });
 
-  it('contributes the loupe toggle only when the instrument declares one', () => {
+  it('contributes the loupe toggle only while a lens is mounted', () => {
     expect(ids(bare)).not.toContain('loupe');
-    expect(ids({ ...bare, loupe: true })).toContain('loupe');
-    expect(ids({ ...bare, loupe: { render: () => null } })).toContain('loupe');
+    const mounted = builtinContributions(bare, { ...ctx, hasLoupe: true });
+    expect(mounted.map((c) => c.id)).toContain('loupe');
   });
 
   it('offers the loupe to a DOM instrument, which declares no canvas', () => {
-    const contributions = builtinContributions({ ...bare, loupe: true }, ctx);
+    const contributions = builtinContributions(bare, { ...ctx, hasLoupe: true });
     const loupe = contributions.find((c) => c.id === 'loupe');
     expect(loupe?.region).toBe('toolbar');
   });
 
   it('reports the loupe switch position, so the button reads as held', () => {
-    const off = builtinContributions({ ...bare, loupe: true }, ctx);
-    const on = builtinContributions({ ...bare, loupe: true }, { ...ctx, loupeOn: true });
+    const off = builtinContributions(bare, { ...ctx, hasLoupe: true });
+    const on = builtinContributions(bare, { ...ctx, hasLoupe: true, loupeOn: true });
     expect(off.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: false });
     expect(on.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: true });
   });

package/src/chrome/builtins.tsx

@@ -39,6 +39,10 @@ function groupFolds(
   return out;
 }
 
+/** Built-in ids contributed only while runtime state says so — the loupe
+ *  toggle appears once a lens mounts, after the trial's first render. */
+export const TRANSIENT_BUILTINS: ReadonlySet<string> = new Set(['loupe']);
+
 /**
  * The contributions a trial gets from what its instrument declared. This is
  * the whole "declaring a capability provides the chrome" rule — it replaces
@@ -93,7 +97,7 @@ export function builtinContributions(
     });
   }
 
-  if (instrument.loupe != null) {
+  if (ctx.hasLoupe) {
     out.push({
       id: 'loupe',
       region: 'toolbar',

package/src/chrome/index.ts

@@ -1,4 +1,4 @@
-export { builtinContributions } from './builtins';
+export { builtinContributions, TRANSIENT_BUILTINS } from './builtins';
 export type { LabRegionProps } from './LabChrome';
 export {
   contributionsIn,

package/src/chrome/merge.test.ts

@@ -44,6 +44,11 @@ describe('suppressContributions', () => {
     );
   });
 
+  it('passes over an absent id it was told may come and go', () => {
+    const out = suppressContributions([toolbarItem('a')], ['late'], new Set(['late']));
+    expect(out.map((c) => c.id)).toEqual(['a']);
+  });
+
   it('is a no-op for an empty suppress list', () => {
     const bundle = [toolbarItem('a')];
     expect(suppressContributions(bundle, [])).toEqual(bundle);

package/src/chrome/merge.ts

@@ -30,15 +30,17 @@ export function mergeContributions<T extends { id: string }>(
 /**
  * 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.
  */
 export function suppressContributions<T extends { id: string }>(
   bundle: readonly T[],
   ids: readonly string[],
+  transient: ReadonlySet<string> = new Set(),
 ): T[] {
   const present = new Set(bundle.map((c) => c.id));
   for (const id of ids) {
-    if (!present.has(id)) {
+    if (!present.has(id) && !transient.has(id)) {
       throw new Error(
         `[labkit] cannot suppress "${id}": no contribution with that id. ` +
           `Present ids: ${[...present].join(', ')}`,

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

@@ -62,16 +62,15 @@ describe('PaletteRegion', () => {
 
   it('walks the vertical strip with ArrowDown, and leaves ArrowRight to the page', () => {
     render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
-    const strip = screen.getByRole('toolbar', { name: 'Tools' });
     const brush = screen.getByRole('button', { name: 'brush' });
     const eraser = screen.getByRole('button', { name: 'eraser' });
 
     brush.focus();
-    fireEvent.keyDown(strip, { key: 'ArrowDown' });
+    fireEvent.keyDown(brush, { key: 'ArrowDown' });
     expect(document.activeElement).toBe(eraser);
     expect(eraser).toHaveAttribute('tabindex', '0');
 
-    fireEvent.keyDown(strip, { key: 'ArrowRight' });
+    fireEvent.keyDown(eraser, { key: 'ArrowRight' });
     expect(document.activeElement).toBe(eraser);
   });
 });

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,5 +1,4 @@
-import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
-import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
+import { ToolButton, ToolGroup, useRovingTabIndex } from '../../passthrough/weasel-ui';
 import type { RegionContribution, ToolItem, ToolSlotContext, TrialChromeContext } from '../types';
 
 /** Props for `<PaletteRegion>`. */
@@ -19,11 +18,11 @@ export function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>
   ctx,
   region = 'palette',
 }: PaletteRegionProps<TCtx>) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>('vertical');
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'vertical' });
   if (contributions.length === 0) return null;
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-palette-region"
       role="toolbar"
       aria-label="Tools"

package/src/chrome/regions/ViewportRegion.browser.test.less

@@ -0,0 +1,6 @@
+// Narrower than the zoom control's 160px natural width, wider than its floor.
+.lk-viewport-test-well {
+  position: relative;
+  width: 160px;
+  height: 120px;
+}

package/src/chrome/regions/ViewportRegion.browser.test.tsx

@@ -0,0 +1,38 @@
+import '@weasel-js/theme/tokens.css';
+import '../../styles.less';
+import './ViewportRegion.browser.test.less';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import { ZoomControl } from '../../primitives/ZoomControl';
+import type { TrialChromeContext, TrialContribution } from '../types';
+import { ViewportRegion } from './ViewportRegion';
+
+// Whether a rendered control shrinks to the cluster or runs out past it is
+// layout, which only a real browser has.
+
+afterEach(cleanup);
+
+const ctx = { zoom: 1, setZoom: () => {} } as unknown as TrialChromeContext;
+
+const contributions: TrialContribution[] = [
+  {
+    id: 'zoom-control',
+    region: 'viewport',
+    render: (c) => <ZoomControl zoom={c.zoom ?? 1} onZoomChange={c.setZoom} />,
+  },
+];
+
+test('a zoom control on its own row shrinks its slider to fit a narrow well', () => {
+  const { container } = render(
+    <div className="lk-root">
+      <div className="lk-viewport-test-well">
+        <ViewportRegion contributions={contributions} ctx={ctx} />
+      </div>
+    </div>,
+  );
+  const cluster = container.querySelector('.lk-viewport-controls')?.getBoundingClientRect();
+  const zoom = container.querySelector('.lk-zoom')?.getBoundingClientRect();
+  if (!cluster || !zoom) throw new Error('nothing rendered');
+  expect(zoom.left).toBeGreaterThanOrEqual(cluster.left);
+  expect(zoom.right).toBeLessThanOrEqual(cluster.right);
+});

package/src/chrome/regions/ViewportRegion.less

@@ -17,6 +17,12 @@
   backdrop-filter: blur(var(--wzl-glass-blur));
 }
 
+// Without this a rendered control's floor is its content's min-content, and the
+// zoom slider's fixed width then runs it out past the cluster on a narrow well.
+.lk-viewport-controls__item {
+  min-width: 0;
+}
+
 .lk-viewport-controls__button {
   display: inline-flex;
   align-items: center;

package/src/chrome/regions/ViewportRegion.tsx

@@ -1,4 +1,4 @@
-import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
+import { useRovingTabIndex } from '../../passthrough/weasel-ui';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<ViewportRegion>`. */
@@ -12,18 +12,24 @@ export interface ViewportRegionProps {
  * rather than in the toolbar, which acts on the trial itself.
  */
 export function ViewportRegion({ contributions, ctx }: ViewportRegionProps) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'horizontal' });
   if (contributions.length === 0) return null;
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-viewport-controls"
       role="toolbar"
       aria-label="View"
       onKeyDown={onKeyDown}
     >
       {contributions.map((c) => {
-        if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+        if (c.render) {
+          return (
+            <span key={c.id} className="lk-viewport-controls__item">
+              {c.render(ctx)}
+            </span>
+          );
+        }
         if (c.region !== 'viewport' || !c.item) return null;
         const { icon: Icon, label, disabled, onActivate } = c.item;
         return (

package/src/chrome/types.ts

@@ -162,8 +162,10 @@ export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext
   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;
 

package/src/config/auto.ts

@@ -10,6 +10,7 @@ export const auto: unique symbol = Symbol('weasel.auto');
 /** The type of the `auto` sentinel, for widening a value parameter. */
 export type Auto = typeof auto;
 
+/** Whether `value` is the `auto` sentinel. */
 export function isAuto(value: unknown): value is Auto {
   return value === auto;
 }

package/src/config/builder.ts

@@ -124,6 +124,7 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   }
 }
 
+/** A numeric leaf, built by `f.number`. */
 export class NumberNode extends BaseNode<number> {
   readonly kind = 'number';
 
@@ -169,6 +170,7 @@ export class NumberNode extends BaseNode<number> {
   }
 }
 
+/** A true/false leaf, built by `f.boolean`; a checkbox unless `.toggle()`. */
 export class BooleanNode extends BaseNode<boolean> {
   readonly kind = 'boolean';
 
@@ -178,6 +180,7 @@ export class BooleanNode extends BaseNode<boolean> {
   }
 }
 
+/** A text leaf, built by `f.string`. */
 export class StringNode extends BaseNode<string> {
   readonly kind = 'string';
 
@@ -195,6 +198,7 @@ export class StringNode extends BaseNode<string> {
   }
 }
 
+/** A string-list leaf, built by `f.list`. */
 export class ListNode extends BaseNode<string[]> {
   readonly kind = 'list';
 
@@ -204,6 +208,7 @@ export class ListNode extends BaseNode<string[]> {
   }
 }
 
+/** A color leaf holding a hex string, built by `f.color`. */
 export class ColorNode extends BaseNode<string> {
   readonly kind = 'color';
 
@@ -214,6 +219,7 @@ export class ColorNode extends BaseNode<string> {
   }
 }
 
+/** A fixed-choice leaf, built by `f.enum`; a select unless `.radio()`. */
 export class EnumNode<T extends string> extends BaseNode<T> {
   readonly kind = 'enum';
 

package/src/config/types.ts

@@ -14,7 +14,8 @@ export 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. */
+   *  place of `label`, which stays the accessible name and becomes the tooltip;
+   *  a select draws it beside `label`. */
   icon?: string;
 }
 

package/src/controls/ControlPanel.test.tsx

@@ -919,6 +919,30 @@ describe('<ControlPanel> option icons', () => {
     expect(ok.textContent).toBe('');
     expect(screen.getByRole('radio', { name: 'bad' }).textContent).toBe('bad');
   });
+
+  it("draws an option's icon beside its label in a select's trigger and list", () => {
+    const status = f.enum('ok', [
+      { value: 'ok', label: 'ok', icon: 'statusSuccess' },
+      { value: 'bad', label: 'bad' },
+    ]);
+    render(
+      <ControlPanel
+        schema={resolveConfigSchema(f.schema({ status }), [])}
+        config={{ status: 'ok' }}
+        setConfig={() => {}}
+      />,
+    );
+    const trigger = screen.getByRole('button', { name: /ok/ });
+    expect(trigger.querySelector('[aria-hidden="true"] > svg')).not.toBeNull();
+    expect(trigger).toHaveTextContent('ok');
+    act(() => {
+      fireEvent.click(trigger);
+    });
+    expect(
+      screen.getByRole('option', { name: 'ok' }).querySelector('[aria-hidden="true"] > svg'),
+    ).not.toBeNull();
+    expect(screen.getByRole('option', { name: 'bad' }).querySelectorAll('svg')).toHaveLength(1);
+  });
 });
 
 describe('<ControlPanel> pair', () => {
@@ -1129,14 +1153,20 @@ describe('<ControlPanel> resettable group', () => {
   const schema = resolveConfigSchema(
     f.schema({
       name: f.string('a'),
-      modes: f.group({ one: f.number(0), two: f.number(0), inner: f.group({ three: f.number(1) }) }).resettable(),
+      modes: f
+        .group({ one: f.number(0), two: f.number(0), inner: f.group({ three: f.number(1) }) })
+        .resettable(),
       plain: f.group({ four: f.number(0) }),
     }),
   );
 
   it('puts a reset button on the group heading, disabled while nothing has changed', () => {
     render(
-      <ControlPanel schema={schema} config={{ name: 'a', modes: { one: 0, two: 0, inner: { three: 1 } }, plain: { four: 0 } }} setConfig={vi.fn()} />,
+      <ControlPanel
+        schema={schema}
+        config={{ name: 'a', modes: { one: 0, two: 0, inner: { three: 1 } }, plain: { four: 0 } }}
+        setConfig={vi.fn()}
+      />,
     );
     expect(screen.getByRole('button', { name: 'Reset Modes' })).toBeDisabled();
     expect(screen.queryByRole('button', { name: 'Reset Plain' })).toBeNull();
@@ -1145,7 +1175,11 @@ describe('<ControlPanel> resettable group', () => {
   it('writes the default of every changed value beneath the group and nothing else', () => {
     const setConfig = vi.fn();
     render(
-      <ControlPanel schema={schema} config={{ name: 'b', modes: { one: 2, two: 0, inner: { three: 5 } }, plain: { four: 3 } }} setConfig={setConfig} />,
+      <ControlPanel
+        schema={schema}
+        config={{ name: 'b', modes: { one: 2, two: 0, inner: { three: 5 } }, plain: { four: 3 } }}
+        setConfig={setConfig}
+      />,
     );
     fireEvent.click(screen.getByRole('button', { name: 'Reset Modes' }));
     expect(setConfig.mock.calls).toEqual([

package/src/controls/ControlPanel.tsx

@@ -123,7 +123,9 @@ const NO_AUTO: ReadonlySet<string> = new Set();
 function leavesUnder(group: PrefGroup, at: string): [string, unknown][] {
   return Object.entries(group.children).flatMap(([key, child]) => {
     const path = at === '' ? key : `${at}.${key}`;
-    return isPrefLeaf(child) ? [[path, child.default] as [string, unknown]] : leavesUnder(child, path);
+    return isPrefLeaf(child)
+      ? [[path, child.default] as [string, unknown]]
+      : leavesUnder(child, path);
   });
 }
 
@@ -140,7 +142,9 @@ function ResetGroup({
   config: Record<string, unknown>;
   setConfig: (path: string, value: unknown) => void;
 }) {
-  const changed = leavesUnder(group, path).filter(([p, d]) => !Object.is(valueAtPath(config, p), d));
+  const changed = leavesUnder(group, path).filter(
+    ([p, d]) => !Object.is(valueAtPath(config, p), d),
+  );
   return (
     <Button
       iconOnly
@@ -267,7 +271,12 @@ export function ControlPanel<TC extends Record<string, unknown>>({
         span
         actions={
           resolved.resettable?.has(path) ? (
-            <ResetGroup group={found} path={path} config={config as Record<string, unknown>} setConfig={setConfig} />
+            <ResetGroup
+              group={found}
+              path={path}
+              config={config as Record<string, unknown>}
+              setConfig={setConfig}
+            />
           ) : undefined
         }
         {...fold(path, undefined, rows.grid)}

package/src/dragdrop/DragDropRuntime.tsx

@@ -1,4 +1,5 @@
-import { openPointerSession, type PointerSession, useVisibleRaf } from '@weasel-js/core';
+import { openPointerSession, type PointerSession, useLatest, useVisibleRaf } from '@weasel-js/core';
+import { boxContainsPoint } from '@weasel-js/geom';
 import {
   type PointerEvent as ReactPointerEvent,
   type RefObject,
@@ -18,12 +19,16 @@ import type {
 } from '../instrument/types';
 import { DragGhost } from './DragGhost';
 
+/** A palette drag in progress. `screenPos` is in client pixels; `feedback` is
+ *  the last `onDragOver` answer — `null` off the canvas or without one. */
 export interface DragState {
   item: PaletteItem;
   screenPos: Point;
   feedback: DragFeedback | null;
 }
 
+/** Inputs to `useDragDrop`: the capability, the element that counts as the
+ *  drop target, and the trial state a drop rewrites. */
 export interface UseDragDropArgs<TS, TC> {
   capability: DragDropCapability<TS, TC>;
   canvasContainerRef: RefObject<HTMLElement | null>;
@@ -37,11 +42,18 @@ export interface UseDragDropArgs<TS, TC> {
   emit: (event: string) => void;
 }
 
+/** The live drag, and the handler a palette item calls on pointerdown. */
 export interface UseDragDropResult {
   drag: DragState | null;
   startDrag: (item: PaletteItem, e: ReactPointerEvent) => void;
 }
 
+/**
+ * Run palette-to-canvas drags for a `DragDropCapability`. Releasing over the
+ * container converts the pointer to world coordinates, applies `onDrop`'s
+ * state and emits `'canvas.itemAdded'`; releasing anywhere else, or a canceled
+ * gesture, drops nothing. `onDragOver` is probed at most once per frame.
+ */
 export function useDragDrop<TS, TC>({
   capability,
   canvasContainerRef,
@@ -53,8 +65,8 @@ export function useDragDrop<TS, TC>({
   worldSpec,
 }: UseDragDropArgs<TS, TC>): UseDragDropResult {
   const [drag, setDrag] = useState<DragState | null>(null);
+  // Owned by the handlers below, which write it alongside every `setDrag`.
   const dragRef = useRef<DragState | null>(null);
-  dragRef.current = drag;
   /** The move the next frame will resolve. Doubles as the throttle's flag:
    *  non-null means a frame is already queued. */
   const pendingPos = useRef<Point | null>(null);
@@ -62,20 +74,14 @@ export function useDragDrop<TS, TC>({
 
   /** A session keeps the closure it was opened with, so everything the drop
    *  reads has to come from here rather than from that closure. */
-  const liveRef = useRef({ capability, state, config, setState, emit, view, worldSpec });
-  liveRef.current = { capability, state, config, setState, emit, view, worldSpec };
+  const liveRef = useLatest({ capability, state, config, setState, emit, view, worldSpec });
 
   const isOverCanvas = useCallback(
     (screenPos: Point): boolean => {
       const el = canvasContainerRef.current;
       if (!el) return false;
       const r = el.getBoundingClientRect();
-      return (
-        screenPos.x >= r.left &&
-        screenPos.x <= r.right &&
-        screenPos.y >= r.top &&
-        screenPos.y <= r.bottom
-      );
+      return boxContainsPoint([r.left, r.top, r.right, r.bottom], screenPos.x, screenPos.y);
     },
     [canvasContainerRef],
   );
@@ -92,7 +98,7 @@ export function useDragDrop<TS, TC>({
         frame,
       );
     },
-    [canvasContainerRef],
+    [canvasContainerRef, liveRef],
   );
 
   const frameLoop = useVisibleRaf(() => {
@@ -106,7 +112,8 @@ export function useDragDrop<TS, TC>({
       const world = screenToWorldFromContainer(screenPos);
       if (world) feedback = live.capability.onDragOver(world, active.item, live.state, live.config);
     }
-    setDrag({ ...active, screenPos, feedback });
+    dragRef.current = { ...active, screenPos, feedback };
+    setDrag(dragRef.current);
   });
 
   const clearDrag = useCallback(() => {
@@ -154,7 +161,7 @@ export function useDragDrop<TS, TC>({
         onCancel: clearDrag,
       });
     },
-    [clearDrag, frameLoop, isOverCanvas, screenToWorldFromContainer],
+    [clearDrag, frameLoop, isOverCanvas, liveRef, screenToWorldFromContainer],
   );
 
   useEffect(() => () => sessionRef.current?.cancel(), []);
@@ -162,10 +169,12 @@ export function useDragDrop<TS, TC>({
   return { drag, startDrag };
 }
 
+/** Props for `DragOverlay`. */
 export interface DragOverlayProps {
   drag: DragState | null;
 }
 
+/** The ghost for `drag`, or nothing when no drag is live. */
 export function DragOverlay({ drag }: DragOverlayProps) {
   if (!drag) return null;
   return <DragGhost item={drag.item} screenPos={drag.screenPos} />;

package/src/dragdrop/DragGhost.tsx

@@ -2,11 +2,14 @@ import { type ReactPortal, useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 import type { PaletteItem, Point } from '../instrument/types';
 
+/** Props for `DragGhost`. `screenPos` is in client pixels. */
 export interface DragGhostProps {
   item: PaletteItem;
   screenPos: Point;
 }
 
+/** The dragged item's label, portaled to `document.body` just below-right of
+ *  `screenPos`. Renders nothing until mounted, so it is SSR-safe. */
 export function DragGhost({ item, screenPos }: DragGhostProps): ReactPortal | null {
   const [mounted, setMounted] = useState(false);
   useEffect(() => setMounted(true), []);

package/src/dragdrop/Palette.tsx

@@ -1,12 +1,14 @@
 import type { PointerEvent as ReactPointerEvent } from 'react';
 import type { PaletteItem } from '../instrument/types';
 
+/** Props for `Palette`. `onDragStart` is usually `useDragDrop`'s `startDrag`. */
 export interface PaletteProps {
   items: PaletteItem[];
   onDragStart: (item: PaletteItem, e: ReactPointerEvent) => void;
   className?: string;
 }
 
+/** One button per item, each starting a drag on pointerdown. */
 export function Palette({ items, onDragStart, className }: PaletteProps) {
   return (
     <div className={className ? `lk-palette ${className}` : 'lk-palette'}>

package/src/index.test.ts

@@ -49,6 +49,11 @@ describe('public export surface', () => {
     expect(labkit).toHaveProperty('useTrialState');
     expect(labkit).toHaveProperty('useTrialId');
   });
+
+  it('leaves the loupe to its own entry, so a lab without one does not load it', () => {
+    expect(labkit).not.toHaveProperty('TrialLoupe');
+    expect(labkit).not.toHaveProperty('useLoupe');
+  });
 });
 
 describe('ui re-exports', () => {

package/src/index.ts

@@ -80,6 +80,7 @@ export type {
   AnnotationMeaning,
   AnnotationPatch,
   AnnotationQuery,
+  AnnotationSelectionMode,
   AnnotationStatus,
   AnnotationStoreOptions,
   AnnotationsApi,
@@ -267,7 +268,6 @@ export * from './job';
 export * from './lab';
 export type { LayerListItem, LayerListProps, LayerMove } from './layers';
 export { LayerList, moveLayers } from './layers';
-export * from './loupe';
 export * from './primitives';
 export { SPECIMEN_SECTIONS, Specimen } from './specimen/Specimen';
 export {

package/src/instrument/types.ts

@@ -6,7 +6,6 @@ import type { TrialContribution } from '../chrome/types';
 import type { ConfigPath, ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
-import type { LoupeDeclaration } from '../loupe/types';
 import type { TrialInfo } from '../state/types';
 import type { ToolCapability } from '../tools/types';
 
@@ -182,11 +181,6 @@ export 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