@weasel-js/labkit 1.7.0 → 1.7.2

package/src/lab/LabZoom.test.tsx

@@ -1,4 +1,4 @@
-import { act, fireEvent, render, screen, within } from '@testing-library/react';
+import { act, fireEvent, screen, within } from '@testing-library/react';
 import {
   ActionsProvider,
   type ActionsRegistry,
@@ -8,6 +8,7 @@ import {
   useActionsRegistry,
   useGestureDispatcher,
 } from '@weasel-js/core';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { type ReactNode, useEffect } from 'react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
@@ -54,16 +55,16 @@ function Capture({ children }: { children?: ReactNode }) {
 const zoomBar = () => within(screen.getByRole('toolbar', { name: 'Zoom' }));
 const readout = () => zoomBar().getByRole('button', { name: /^Zoom \d+%|^Zoom unavailable/ });
 const press = (name: string) =>
-  act(() => {
+  act(async () => {
     fireEvent.click(zoomBar().getByRole('button', { name }));
   });
 
 const MOD = /mac/i.test(navigator.platform || navigator.userAgent)
   ? { metaKey: true }
   : { ctrlKey: true };
-function key(k: string): boolean {
+async function key(k: string): Promise<boolean> {
   let prevented = false;
-  act(() => {
+  await act(async () => {
     prevented = !fireEvent.keyDown(window, { key: k, ...MOD });
   });
   return prevented;
@@ -111,113 +112,123 @@ function stageZoom(container: HTMLElement, index = 0): number {
 }
 
 describe("the lab header's zoom controls", () => {
-  it('step the focused trial through its camera and read its zoom back', () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+  it('step the focused trial through its camera and read its zoom back', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
     expect(readout()).toHaveTextContent('100%');
-    press('Zoom in');
+    await press('Zoom in');
     expect(stageZoom(container)).toBeCloseTo(1.25);
     expect(readout()).toHaveTextContent('125%');
-    press('Zoom out');
+    await press('Zoom out');
     expect(stageZoom(container)).toBeCloseTo(1);
-    press('Zoom out');
+    await press('Zoom out');
     expect(readout()).toHaveTextContent('80%');
   });
 
-  it('reset to actual size from the readout', () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
-    press('Zoom out');
-    press('Zoom out');
-    act(() => {
+  it('reset to actual size from the readout', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
+    await press('Zoom out');
+    await press('Zoom out');
+    await act(async () => {
       fireEvent.click(readout());
     });
     expect(stageZoom(container)).toBe(1);
     expect(readout()).toHaveTextContent('100%');
   });
 
-  it("stop at the camera's own limit, and say so", () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
-    press('Zoom in');
-    press('Zoom in');
+  it("stop at the camera's own limit, and say so", async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
+    await press('Zoom in');
+    await press('Zoom in');
     expect(stageZoom(container)).toBe(1.5);
     expect(zoomBar().getByRole('button', { name: 'Zoom in' })).toBeDisabled();
     expect(zoomBar().getByRole('button', { name: 'Zoom out' })).toBeEnabled();
   });
 
-  it('answer Mod+=, Mod+- and Mod+0, claiming the key from the browser', () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
-    expect(key('=')).toBe(true);
+  it('answer Mod+=, Mod+- and Mod+0, claiming the key from the browser', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
+    expect(await key('=')).toBe(true);
     expect(stageZoom(container)).toBeCloseTo(1.25);
-    key('-');
-    key('-');
+    await key('-');
+    await key('-');
     expect(stageZoom(container)).toBeCloseTo(0.8);
-    key('0');
+    await key('0');
     expect(stageZoom(container)).toBe(1);
   });
 
-  it('go inert over a trial with no camera, and leave its keys to the browser', () => {
-    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+  it('go inert over a trial with no camera, and leave its keys to the browser', async () => {
+    await renderSettled(<Lab instruments={[plain]} defaultInstrument="Plain" />);
     for (const name of ['Zoom out', 'Zoom in']) {
       expect(zoomBar().getByRole('button', { name })).toBeDisabled();
     }
     expect(readout()).toBeDisabled();
     expect(readout()).toHaveTextContent('–');
-    expect(key('=')).toBe(false);
+    expect(await key('=')).toBe(false);
   });
 
-  it("take the key ahead of a story's own binding in a trial with a camera", () => {
+  it("take the key ahead of a story's own binding in a trial with a camera", async () => {
     const story = vi.fn();
     const zooming = defineInstrument<Record<string, never>, Record<string, never>>({
       ...staged,
       name: 'Zooming',
       render: () => <StoryZoomKey run={story} />,
     });
-    const { container } = render(<Lab instruments={[zooming]} defaultInstrument="Zooming" />);
-    key('=');
+    const { container } = await renderSettled(
+      <Lab instruments={[zooming]} defaultInstrument="Zooming" />,
+    );
+    await key('=');
     expect(stageZoom(container)).toBeCloseTo(1.25);
     expect(story).not.toHaveBeenCalled();
   });
 
-  it("leave the key to a story's own binding in a trial with no camera", () => {
+  it("leave the key to a story's own binding in a trial with no camera", async () => {
     const story = vi.fn();
     const zooming = defineInstrument<Record<string, never>, Record<string, never>>({
       ...plain,
       name: 'ZoomingPlain',
       render: () => <StoryZoomKey run={story} />,
     });
-    render(<Lab instruments={[zooming]} defaultInstrument="ZoomingPlain" />);
-    key('=');
+    await renderSettled(<Lab instruments={[zooming]} defaultInstrument="ZoomingPlain" />);
+    await key('=');
     expect(story).toHaveBeenCalledTimes(1);
   });
 
-  it('follow the focus from trial to trial', () => {
-    const { container } = render(
+  it('follow the focus from trial to trial', async () => {
+    const { container } = await renderSettled(
       <Lab instruments={[staged, plain]} defaultInstrument="Staged">
         <Capture />
       </Lab>,
     );
-    act(() => lab?.addTrial('Staged'));
-    act(() => lab?.addTrial('Plain'));
+    await act(async () => lab?.addTrial('Staged'));
+    await act(async () => lab?.addTrial('Plain'));
     const [first, second, third] = lab?.trials.map((t) => t.id) ?? [];
     expect(zoomBar().getByRole('button', { name: 'Zoom in' })).toBeDisabled();
 
-    act(() => lab?.focusTrial(second ?? ''));
-    press('Zoom out');
+    await act(async () => lab?.focusTrial(second ?? ''));
+    await press('Zoom out');
     expect(stageZoom(container, 1)).toBeCloseTo(0.8);
     expect(stageZoom(container, 0)).toBe(1);
     expect(readout()).toHaveTextContent('80%');
 
-    act(() => lab?.focusTrial(first ?? ''));
+    await act(async () => lab?.focusTrial(first ?? ''));
     expect(readout()).toHaveTextContent('100%');
-    key('=');
+    await key('=');
     expect(stageZoom(container, 0)).toBeCloseTo(1.25);
     expect(stageZoom(container, 1)).toBeCloseTo(0.8);
 
-    act(() => lab?.focusTrial(third ?? ''));
+    await act(async () => lab?.focusTrial(third ?? ''));
     expect(readout()).toBeDisabled();
   });
 
-  it('are left out when the lab says so', () => {
-    render(<Lab instruments={[staged]} defaultInstrument="Staged" zoom={false} />);
+  it('are left out when the lab says so', async () => {
+    await renderSettled(<Lab instruments={[staged]} defaultInstrument="Staged" zoom={false} />);
     expect(screen.queryByRole('toolbar', { name: 'Zoom' })).toBeNull();
   });
 });

package/src/lab/LabZoom.tsx

@@ -10,10 +10,11 @@ import {
   useActionsRegistry,
   useDepSource,
   useGestureDispatcher,
+  useLatest,
   type ViewApi,
 } from '@weasel-js/core';
 import { ZoomInIcon, ZoomOutIcon } from '@weasel-js/ui';
-import { useContext, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useContext, useEffect, useMemo, useSyncExternalStore } from 'react';
 import { useStore } from 'zustand/react';
 import type { CameraView } from '../canvas/CameraInput';
 import { CameraRegistryContext } from '../canvas/cameraRegistry';
@@ -96,8 +97,7 @@ function LabZoomControls() {
 
   const live = zoom !== null && camera !== null;
   const view = useMemo(() => (camera ? forZoom(camera) : null), [camera]);
-  const viewRef = useRef(view);
-  viewRef.current = live ? view : null;
+  const viewRef = useLatest(live ? view : null);
 
   useDepSource('view', () => viewRef.current as ViewApi);
 
@@ -108,7 +108,7 @@ function LabZoomControls() {
       enabled: () => (viewRef.current ? true : ActionDisabledReason.NotApplicable),
     };
     return registry.register(action);
-  }, [registry]);
+  }, [registry, viewRef]);
 
   // First, so a story's own zoom keys do not also fire over a trial with a
   // camera; over one without, the action is disabled and the keys pass on.

package/src/lab/Workspace.surface.test.tsx

@@ -1,4 +1,5 @@
-import { render } from '@testing-library/react';
+import { act } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, it, vi } from 'vitest';
 import { SurfaceContext } from '../surface/SurfaceContext';
 import type { SurfaceHandle } from '../surface/useTiledSurface';
@@ -18,9 +19,9 @@ function fakeHandle(): SurfaceHandle {
 }
 
 describe('Workspace with a surface above it', () => {
-  it('invalidates rects when the tile set changes, because a re-tile moves tiles', () => {
+  it('invalidates rects when the tile set changes, because a re-tile moves tiles', async () => {
     const handle = fakeHandle();
-    const { rerender } = render(
+    const { rerender } = await renderSettled(
       <SurfaceContext.Provider value={handle}>
         <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
           <div>a</div>
@@ -29,20 +30,22 @@ describe('Workspace with a surface above it', () => {
     );
     (handle.invalidateRects as ReturnType<typeof vi.fn>).mockClear();
 
-    rerender(
-      <SurfaceContext.Provider value={handle}>
-        <Workspace ids={['a', 'b']} viewport={{ w: 800, h: 600 }}>
-          <div>a</div>
-          <div>b</div>
-        </Workspace>
-      </SurfaceContext.Provider>,
-    );
+    await act(async () => {
+      rerender(
+        <SurfaceContext.Provider value={handle}>
+          <Workspace ids={['a', 'b']} viewport={{ w: 800, h: 600 }}>
+            <div>a</div>
+            <div>b</div>
+          </Workspace>
+        </SurfaceContext.Provider>,
+      );
+    });
 
     expect(handle.invalidateRects).toHaveBeenCalled();
   });
 
-  it('renders unchanged with no surface above it', () => {
-    const { getByText } = render(
+  it('renders unchanged with no surface above it', async () => {
+    const { getByText } = await renderSettled(
       <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
         <div>a</div>
       </Workspace>,

package/src/lab/Workspace.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen } from '@testing-library/react';
+import { act, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, test, vi } from 'vitest';
 import { useTrialDrag } from '../trial/TrialDragContext';
 import { Workspace } from './Workspace';
@@ -13,8 +14,8 @@ function DragProbe({ label }: { label: string }) {
 const VIEWPORT = { w: 800, h: 600 };
 
 describe('Workspace', () => {
-  test('renders all children', () => {
-    render(
+  test('renders all children', async () => {
+    await renderSettled(
       <Workspace viewport={VIEWPORT}>
         <div>one</div>
         <div>two</div>
@@ -26,9 +27,9 @@ describe('Workspace', () => {
     expect(screen.getByText('three')).toBeInTheDocument();
   });
 
-  test('keeps a child with the tile its id names when an earlier one closes', () => {
+  test('keeps a child with the tile its id names when an earlier one closes', async () => {
     const ids = ['a', 'b', 'c'];
-    const { rerender, container } = render(
+    const { rerender, container } = await renderSettled(
       <Workspace ids={ids} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
@@ -37,18 +38,20 @@ describe('Workspace', () => {
     );
     expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
 
-    rerender(
-      <Workspace ids={['b', 'c']} viewport={VIEWPORT}>
-        <div>b</div>
-        <div>c</div>
-      </Workspace>,
-    );
+    await act(async () => {
+      rerender(
+        <Workspace ids={['b', 'c']} viewport={VIEWPORT}>
+          <div>b</div>
+          <div>c</div>
+        </Workspace>,
+      );
+    });
     expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
     expect(container.querySelector('[data-node="a"]')).toBeNull();
   });
 
-  test('uses lk-workspace class', () => {
-    const { container } = render(
+  test('uses lk-workspace class', async () => {
+    const { container } = await renderSettled(
       <Workspace viewport={VIEWPORT}>
         <div />
       </Workspace>,
@@ -56,8 +59,8 @@ describe('Workspace', () => {
     expect((container.firstChild as HTMLElement).className).toContain('lk-workspace');
   });
 
-  test('renders resize affordances only when resizable', () => {
-    const { container, rerender } = render(
+  test('renders resize affordances only when resizable', async () => {
+    const { container, rerender } = await renderSettled(
       <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
@@ -65,17 +68,19 @@ describe('Workspace', () => {
     );
     expect(container.querySelectorAll('[role="separator"]')).toHaveLength(0);
 
-    rerender(
-      <Workspace ids={['a', 'b']} resizable viewport={VIEWPORT}>
-        <div>a</div>
-        <div>b</div>
-      </Workspace>,
-    );
+    await act(async () => {
+      rerender(
+        <Workspace ids={['a', 'b']} resizable viewport={VIEWPORT}>
+          <div>a</div>
+          <div>b</div>
+        </Workspace>,
+      );
+    });
     expect(container.querySelectorAll('[role="separator"]').length).toBeGreaterThan(0);
   });
 
-  test('applies a saved extent to a tile as it registers', () => {
-    const { container } = render(
+  test('applies a saved extent to a tile as it registers', async () => {
+    const { container } = await renderSettled(
       <Workspace
         ids={['a', 'b']}
         resizable
@@ -92,9 +97,9 @@ describe('Workspace', () => {
     expect(Number.parseFloat(a.style.width)).toBeGreaterThan(Number.parseFloat(b.style.width));
   });
 
-  test('reports the order a drop would produce instead of applying it', () => {
+  test('reports the order a drop would produce instead of applying it', async () => {
     const onReorder = vi.fn();
-    const { container } = render(
+    const { container } = await renderSettled(
       <Workspace ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
         <DragProbe label="a" />
         <DragProbe label="b" />
@@ -111,8 +116,8 @@ describe('Workspace', () => {
     expect(nodes).toEqual(['a', 'b']);
   });
 
-  test('offers no drag source unless reorderable', () => {
-    render(
+  test('offers no drag source unless reorderable', async () => {
+    await renderSettled(
       <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
         <DragProbe label="a" />
         <DragProbe label="b" />

package/src/lab/Workspace.tsx

@@ -1,3 +1,4 @@
+import { useLatest } from '@weasel-js/core';
 import {
   Children,
   type ReactNode,
@@ -33,6 +34,7 @@ export type TrialLayout = Record<
   { size?: { w?: number; h?: number }; span?: { cols?: number; rows?: number } }
 >;
 
+/** Props for `Workspace`. */
 export interface WorkspaceProps {
   children: ReactNode;
   /**
@@ -61,7 +63,7 @@ export interface WorkspaceProps {
   padding?: number;
   /** Undocked sidebar panels to render alongside the trials. A `'tile'` panel
    *  joins the grid as a peer of the trials; a `'floating'` one goes into the
-   *  floating zone above it. The body is portalled in by the trial that owns
+   *  floating zone above it. The body is portaled in by the trial that owns
    *  it, so all this renders is the frame and the host. */
   panels?: readonly PanelDescriptor[];
   /**
@@ -72,6 +74,26 @@ export interface WorkspaceProps {
   viewport?: { w: number; h: number };
 }
 
+/** The layout store a workspace keeps for its lifetime: the tile grid, and the zone floating panels live in. */
+function createWorkspaceStore(grid: { resizable: boolean; gap: number; padding: number }): Store {
+  const store = new Store();
+  store.registerNode(
+    createNode({
+      kind: 'zone',
+      id: ZONE_ID,
+      container: { strategyId: 'grid', config: grid },
+    }),
+  );
+  store.registerNode(
+    createNode({
+      kind: 'zone',
+      id: FLOAT_ZONE_ID,
+      container: { strategyId: 'floating', config: {} },
+    }),
+  );
+  return store;
+}
+
 function extentOf(store: Store, id: NodeId): TrialLayout[string] | null {
   const p = store.getNode(id)?.membership?.placement as TrialLayout[string] | undefined;
   if (!p) return null;
@@ -81,21 +103,6 @@ function extentOf(store: Store, id: NodeId): TrialLayout[string] | null {
   return Object.keys(out).length > 0 ? out : null;
 }
 
-/**
- * Auto-balanced tiling of trials, `ceil(sqrt(n))` columns wide.
- *
- * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
- * laid out by CSS — `windease/styles.css` (folded into
- * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
- *
- * `panels` are undocked sidebar sections. A `'tile'` panel is registered as a
- * peer of the trials under `PANEL_KIND`, so the grid places and resizes it like
- * one; a `'floating'` panel goes in the overlay above. Either way this renders
- * only the frame and an empty host: the section's content is portalled in by
- * the trial that owns it, which is what keeps a torn-out section inside its
- * trial's React tree instead of rebuilding it as a sibling.
- */
-
 /** The frame an undocked panel gets: a box, and the host element its trial
  *  portals into. The title and the dock control come through the portal with
  *  the body — the workspace knows a panel's key, not what is in it. */
@@ -116,6 +123,20 @@ export interface PanelDescriptor {
   as: 'tile' | 'floating';
 }
 
+/**
+ * Auto-balanced tiling of trials, `ceil(sqrt(n))` columns wide.
+ *
+ * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
+ * laid out by CSS — `windease/styles.css` (folded into
+ * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
+ *
+ * `panels` are undocked sidebar sections. A `'tile'` panel is registered as a
+ * peer of the trials under `PANEL_KIND`, so the grid places and resizes it like
+ * one; a `'floating'` panel goes in the overlay above. Either way this renders
+ * only the frame and an empty host: the section's content is portaled in by
+ * the trial that owns it, which is what keeps a torn-out section inside its
+ * trial's React tree instead of rebuilding it as a sibling.
+ */
 export function Workspace({
   children,
   ids,
@@ -134,50 +155,25 @@ export function Workspace({
   const floatPanels = useMemo(() => (panels ?? []).filter((p) => p.as === 'floating'), [panels]);
   // Identity has to be stable while the id *contents* are unchanged: the sync
   // effect below keys off it, and a fresh array every render would re-register
-  // every tile forever. A ref keyed on the joined ids says that directly, where
-  // a `useMemo` on the same key can only say it by suppressing both linters.
-  const wantedIds = [
+  // every tile forever. So the ids are memoized on a serialized key, and read
+  // back from it.
+  const idKey = JSON.stringify([
     ...items.map((_, i) => ids?.[i] ?? `lk-ws-${i}`),
     ...tilePanels.map((p) => `lk-panel-${p.key}`),
-  ];
-  const idKey = wantedIds.join(',');
-  const idKeyRef = useRef<string | null>(null);
-  const nodeIdsRef = useRef<NodeId[]>([]);
-  if (idKeyRef.current !== idKey) {
-    idKeyRef.current = idKey;
-    nodeIdsRef.current = wantedIds.map(asNodeId);
-  }
-  const nodeIds = nodeIdsRef.current;
+  ]);
+  const nodeIds = useMemo(() => (JSON.parse(idKey) as string[]).map(asNodeId), [idKey]);
 
   // Held in refs rather than depended on: a fresh object each render would
   // re-run the sync effect, and only a newly registered tile reads `layout`.
-  const layoutRef = useRef(layout);
-  layoutRef.current = layout;
-  const onLayoutChangeRef = useRef(onLayoutChange);
-  onLayoutChangeRef.current = onLayoutChange;
+  const layoutRef = useLatest(layout);
+  const onLayoutChangeRef = useLatest(onLayoutChange);
 
   // One store for the component's lifetime: a tile's dragged extent lives in
   // its node, so rebuilding the store on every add or close would silently
   // reset every pane.
   const storeRef = useRef<Store | null>(null);
-  if (storeRef.current === null) {
-    const store = new Store();
-    store.registerNode(
-      createNode({
-        kind: 'zone',
-        id: ZONE_ID,
-        container: { strategyId: 'grid', config: { resizable, gap, padding } },
-      }),
-    );
-    store.registerNode(
-      createNode({
-        kind: 'zone',
-        id: FLOAT_ZONE_ID,
-        container: { strategyId: 'floating', config: {} },
-      }),
-    );
-    storeRef.current = store;
-  }
+  if (storeRef.current === null)
+    storeRef.current = createWorkspaceStore({ resizable, gap, padding });
   const store = storeRef.current;
 
   // A tile that only moves reports nothing to a ResizeObserver, and only this
@@ -203,7 +199,7 @@ export function Workspace({
       if (saved) store.patchPlacement(id, saved);
     }
     store.setChildOrder(ZONE_ID, [...nodeIds]);
-  }, [store, nodeIds]);
+  }, [store, nodeIds, layoutRef]);
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: nodeIds is the signal that the tile set changed — a re-tile moves tiles without resizing any — not a value this reads
   useEffect(() => {
@@ -222,7 +218,7 @@ export function Workspace({
       }
       onLayoutChangeRef.current?.(next);
     });
-  }, [store, onLayoutChange]);
+  }, [store, onLayoutChange, onLayoutChangeRef]);
 
   const commitOrder = useCallback(
     (nextIds: NodeId[]) => onReorder?.(nextIds.map(String)),

package/src/loupe/AGENTS.md

@@ -1,7 +1,9 @@
 # Loupe — Agent Guide
 
-`src/loupe/` is the `loupe` instrument capability: a magnifier a trial can turn
-on, painted by whichever painter suits the instrument's content.
+`src/loupe/` is `@weasel-js/labkit/loupe`: `<TrialLoupe>`, a magnifier the
+instrument mounts in its own content, painted by whichever painter suits it.
+Its own bundle entry; nothing in the main bundle imports it, so a lab that
+mounts no lens never loads it.
 
 The magnifier itself is not here. `@weasel-js/loupe` holds the model — aim,
 factor, mode, color, picking — over a `LoupeSurface` it asks five questions.
@@ -11,29 +13,40 @@ This directory binds that model to a labkit trial and draws it.
 
 | File | Role |
 |---|---|
-| `types.ts` | `LoupeCapability`, and `resolveLoupe` filling in every default |
+| `types.ts` | `LoupeOptions`, and `resolveLoupe` filling in every default |
 | `useLoupe.ts` | The model over a host element, and pointer aiming |
 | `loupeActions.ts` | `loupe.peek` and `loupe.magnify`, as `Action` descriptors |
 | `LoupeGestures.tsx` | Registers those, and mounts a dispatcher on the host when no camera has one there |
-| `TrialLoupe.tsx` | Picks the painter and mounts the lens |
+| `TrialLoupe.tsx` | Finds its host and the trial's switch, picks the painter, mounts the lens |
 | `LoupeBubble.tsx` | The circular clip, positioned on the aim |
 | `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
 | `canvasLens.ts` | That painter's geometry and drawing, with no React in it |
 | `DomLoupe.tsx` | Painter for DOM content |
 | `useHostSize.ts` | The host's measured box, for the DOM stage |
 
-## Which painter
+## How it reads the trial
+
+Only through context, the way `<TrialOverview>` does. `CanvasStackContext`'s
+`surface` gives the canvas painter the stack's layers, pixels and `worldSpec`;
+`CameraContext` gives a lens in a `<Stage>` its element and camera. Outside
+both, it tracks `hostRef`, or failing that wraps its `children` in a
+`.lk-loupe-host` box of its own.
 
-`LoupeCapability.render` decides. Absent, the lens re-runs the instrument's own
-canvas layers through `lensCamera` — sharp at any factor, and `mode: 'pixel'`
-enlarges the presented pixels with smoothing off instead. Present, the
-instrument is handed a camera and draws itself again; a DOM loupe is always
-`vector`, since DOM has no framebuffer to enlarge.
+The toolbar toggle is `LoupeSwitchContext` (`src/trial/loupeSwitch.ts`, main
+bundle). A lens with no `enabled` prop calls `mount` and follows `on`; the
+trial offers its Loupe toggle while any lens is mounted. `enabled` opts a lens
+out of the switch entirely. Because the lens mounts after the trial's first
+render, `loupe` is in `TRANSIENT_BUILTINS`, so suppressing it before then is
+not a typo.
+
+## Which painter
 
-The canvas painter needs the stack's own pixels and layers, which is why
-`TrialLoupe` mounts *inside* `<CanvasStack>` for a drawing instrument and reads
-`CanvasStackContext`'s `surface`. A DOM instrument gets a
-`.lk-trial__loupe-host` wrapper from `Trial` and the lens tracks that.
+`render` decides. Absent, the lens re-runs the stack's canvas layers through
+`lensCamera` — sharp at any factor, and `mode: 'pixel'` enlarges the presented
+pixels with smoothing off instead. Present, it is handed a camera and draws the
+content again; a DOM loupe is always `vector`, since DOM has no framebuffer to
+enlarge. The canvas painter needs the stack's own pixels, which is why a
+drawing instrument mounts the lens in its `render`, inside `<CanvasStack>`.
 
 ## Traps
 
@@ -51,7 +64,7 @@ In a trial the loupe's actions join the camera's dispatcher (`CameraInput`).
 `loupe.magnify` sits in the hotkey tier, so while the lens is up it outranks
 the camera's wheel zoom; while it is down its `enabled` returns a disabled
 reason and the dispatcher falls through to the zoom. Outside a camera — the DOM
-`.lk-trial__loupe-host` — `<LoupeGestures>` mounts a dispatcher of its own.
+`.lk-loupe-host` — `<LoupeGestures>` mounts a dispatcher of its own.
 
 **Aiming is a plain listener because a hover is not a gesture.**
 `GESTURE_DESCRIPTORS` names no continuous-motion gesture, so `pointermove` /

package/src/loupe/CanvasLoupe.tsx

@@ -1,4 +1,4 @@
-import { useVisibleRaf } from '@weasel-js/core';
+import { useLatest, useVisibleRaf } from '@weasel-js/core';
 import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
 import { useEffect, useRef } from 'react';
 import type { CanvasStackSurface } from '../canvas/CanvasStackContext';
@@ -40,8 +40,7 @@ export function CanvasLoupe({
   // Whatever the stack redraws every frame, the lens has to redraw too — an
   // instrument that animates from its own loop never re-renders this component.
   const args = { aim, factor, mode, diameter, dpr, view, frame, worldSpec, surface };
-  const argsRef = useRef(args);
-  argsRef.current = args;
+  const argsRef = useLatest(args);
 
   const loop = useVisibleRaf(
     () => {