@weasel-js/labkit 1.6.1 → 1.7.1

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/lab/index.ts

@@ -11,5 +11,6 @@ export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
 export type { LabPage, LabSwitcherProps } from './LabSwitcher';
 export { currentPage, LabSwitcher } from './LabSwitcher';
+export { LabZoom } from './LabZoom';
 export type { PanelDescriptor, TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

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(
     () => {

package/src/loupe/DomLoupe.tsx

@@ -16,13 +16,11 @@ export interface DomLoupeProps {
   /** The trial's own camera. */
   view: ViewTransform;
   frame?: WorldFrame;
-  state: unknown;
-  config: unknown;
   render: (args: LoupeRenderArgs) => React.ReactNode;
 }
 
 /**
- * Paints a lens over DOM content by asking the instrument to draw itself again
+ * Paints a lens over DOM content by asking its `render` to draw it again
  * at a magnified camera.
  *
  * The stage is a full copy of the host, so the instrument's own layout still
@@ -38,8 +36,6 @@ export function DomLoupe({
   size,
   view,
   frame,
-  state,
-  config,
   render,
 }: DomLoupeProps) {
   const style: CSSProperties = {
@@ -50,8 +46,6 @@ export function DomLoupe({
   return (
     <div className="lk-loupe__stage" style={style}>
       {render({
-        state,
-        config,
         view: zoomAt(view, factor, aim, { frame }),
         factor,
         mode,

package/src/loupe/Loupe.less

@@ -36,3 +36,19 @@
   left: 0;
   transform-origin: 0 0;
 }
+
+// The box a lens wraps around DOM content when nothing around it has one to
+// track. Reproduces the content well's column so the content still stretches
+// to it rather than collapsing to its intrinsic height.
+.lk-loupe-host {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  height: 100%;
+
+  > * {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+}

package/src/loupe/LoupeGestures.tsx

@@ -50,7 +50,7 @@ function LoupeDispatch({
   useGestureDispatcher({
     canvasRef: hostRef,
     actions: registry,
-    toolsById: NO_TOOLS,
+    entriesById: NO_TOOLS,
     channels: CHANNELS,
     enabled: ownDispatcher,
   });

package/src/loupe/TrialLoupe.tsx

@@ -1,53 +1,97 @@
-import { type RefObject, useContext, useMemo } from 'react';
-import { CameraScope } from '../canvas/CameraInput';
+import { type ReactNode, type RefObject, useContext, useEffect, useMemo, useRef } from 'react';
+import { CameraContext, CameraScope } from '../canvas/CameraInput';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
-import type { WorldSpec } from '../canvas/worldSpec';
+import { fromCameraView } from '../canvas/cameraView';
 import type { ViewTransform } from '../instrument/types';
+import { LoupeSwitchContext } from '../trial/loupeSwitch';
 import { CanvasLoupe } from './CanvasLoupe';
 import { sampleStack } from './canvasLens';
 import { DomLoupe } from './DomLoupe';
 import { LoupeBubble } from './LoupeBubble';
 import { LoupeGestures } from './LoupeGestures';
-import type { ResolvedLoupe } from './types';
+import { type LoupeOptions, resolveLoupe } from './types';
 import { useHostSize } from './useHostSize';
 import { useLoupe } from './useLoupe';
 
 /** Props for `<TrialLoupe>`. */
-export interface TrialLoupeProps {
-  capability: ResolvedLoupe;
-  /** Whether the trial's loupe is turned on. Hold-to-peek shows it anyway. */
-  enabled: boolean;
-  state: unknown;
-  config: unknown;
-  /** The trial's own camera. */
-  view: ViewTransform;
-  worldSpec?: WorldSpec;
-  /** The element the lens tracks. A loupe mounted inside a `<CanvasStack>`
-   *  takes the stack's own element instead, and this goes unused. */
+export interface TrialLoupeProps extends LoupeOptions {
+  /** Whether the lens is turned on. Omitted, it follows the trial's toolbar
+   *  toggle, which the trial offers while a lens like this is mounted — and is
+   *  off outside a trial. Hold-to-peek shows it either way. */
+  enabled?: boolean;
+  /** The camera a `render` lens composes its magnification onto. Defaults to
+   *  the camera around it, and to the identity outside one. */
+  view?: ViewTransform;
+  /** The element the lens tracks. Defaults to the canvas stack or stage around
+   *  it, and outside both to a box wrapped around `children`. */
   hostRef?: RefObject<HTMLElement | null>;
+  /** Content for the lens to sit over. Wrapped in a box of the lens's own only
+   *  when nothing around it gives the lens an element to track. */
+  children?: ReactNode;
 }
 
-/** Stable stand-in, so a loupe with nothing to track does not re-bind its
- *  listeners on every render. */
-const NO_HOST: RefObject<HTMLElement | null> = { current: null };
+const IDENTITY: ViewTransform = { zoom: 1, pan: { x: 0, y: 0 } };
 
 /**
- * A trial's loupe, painted by whichever painter suits its content: the canvas
- * stack it is mounted inside, or the instrument's own `render` at a magnified
- * camera.
+ * A trial's magnifier, mounted by the instrument wherever its content is: in
+ * a canvas instrument's `render`, a stage's `overlay`, or around DOM content.
+ *
+ * With no `render` inside a `<CanvasStack>`, it re-draws the stack's own
+ * layers through a zoomed camera. With `render`, it asks for the content again
+ * at a magnified camera.
  */
 export function TrialLoupe({
-  capability,
   enabled,
-  state,
-  config,
   view,
-  worldSpec,
   hostRef,
+  children,
+  render,
+  factor,
+  minFactor,
+  maxFactor,
+  mode,
+  diameter,
+  peekKey,
+  onColorChange,
 }: TrialLoupeProps) {
+  const options = useMemo(
+    () =>
+      resolveLoupe({
+        render,
+        factor,
+        minFactor,
+        maxFactor,
+        mode,
+        diameter,
+        peekKey,
+        onColorChange,
+      }),
+    [render, factor, minFactor, maxFactor, mode, diameter, peekKey, onColorChange],
+  );
+
   const stack = useContext(CanvasStackContext);
-  const surface = capability.render ? undefined : stack?.surface;
-  const host = surface?.element ?? hostRef ?? NO_HOST;
+  const camera = useContext(CameraContext);
+  const loupeSwitch = useContext(LoupeSwitchContext);
+  const surface = options.render ? undefined : stack?.surface;
+
+  const ownHost = useRef<HTMLDivElement | null>(null);
+  const cameraHost = useMemo<RefObject<HTMLElement | null> | null>(
+    () =>
+      camera
+        ? {
+            get current() {
+              return camera.element();
+            },
+          }
+        : null,
+    [camera],
+  );
+  const host = surface?.element ?? hostRef ?? cameraHost ?? ownHost;
+  const wraps = host === ownHost;
+
+  // A lens told whether it is on has no use for the trial's toggle.
+  const mount = enabled === undefined ? loupeSwitch?.mount : undefined;
+  useEffect(() => mount?.(), [mount]);
 
   const sample = useMemo(() => {
     if (!surface) return undefined;
@@ -57,7 +101,12 @@ export function TrialLoupe({
     };
   }, [surface]);
 
-  const loupe = useLoupe({ capability, hostRef: host, enabled, sample });
+  const loupe = useLoupe({
+    options,
+    hostRef: host,
+    enabled: enabled ?? loupeSwitch?.on ?? false,
+    sample,
+  });
   const measured = useHostSize(host);
   const size = surface?.size ?? measured;
 
@@ -67,42 +116,56 @@ export function TrialLoupe({
   // dispatcher; outside one, `<CameraScope>` gives them an isolated scope.
   const gestures = (
     <CameraScope>
-      <LoupeGestures hostRef={host} input={loupe.input} peekKey={capability.peekKey ?? null} />
+      <LoupeGestures hostRef={host} input={loupe.input} peekKey={options.peekKey ?? null} />
     </CameraScope>
   );
 
-  if (!loupe.visible) return gestures;
+  const lens = loupe.visible ? (
+    <LoupeBubble aim={loupe.aim} diameter={options.diameter}>
+      {options.render ? (
+        <DomLoupe
+          aim={loupe.aim}
+          factor={loupe.factor}
+          mode={loupe.mode}
+          diameter={options.diameter}
+          size={size}
+          view={
+            view ??
+            stack?.view ??
+            (camera ? fromCameraView(camera.view.get(), camera.frame) : IDENTITY)
+          }
+          frame={stack?.frame ?? camera?.frame}
+          render={options.render}
+        />
+      ) : surface && stack ? (
+        <CanvasLoupe
+          aim={loupe.aim}
+          factor={loupe.factor}
+          mode={loupe.mode}
+          diameter={options.diameter}
+          surface={surface}
+          view={stack.view}
+          frame={stack.frame}
+          worldSpec={surface.worldSpec}
+        />
+      ) : null}
+    </LoupeBubble>
+  ) : null;
 
+  if (wraps) {
+    return (
+      <div ref={ownHost} className="lk-loupe-host">
+        {children}
+        {gestures}
+        {lens}
+      </div>
+    );
+  }
   return (
     <>
+      {children}
       {gestures}
-      <LoupeBubble aim={loupe.aim} diameter={capability.diameter}>
-        {capability.render ? (
-          <DomLoupe
-            aim={loupe.aim}
-            factor={loupe.factor}
-            mode={loupe.mode}
-            diameter={capability.diameter}
-            size={size}
-            view={view}
-            frame={stack?.frame}
-            state={state}
-            config={config}
-            render={capability.render}
-          />
-        ) : surface && stack ? (
-          <CanvasLoupe
-            aim={loupe.aim}
-            factor={loupe.factor}
-            mode={loupe.mode}
-            diameter={capability.diameter}
-            surface={surface}
-            view={stack.view}
-            frame={stack.frame}
-            worldSpec={worldSpec}
-          />
-        ) : null}
-      </LoupeBubble>
+      {lens}
     </>
   );
 }

package/src/loupe/index.ts

@@ -13,12 +13,7 @@ export type { LoupeInputApi } from './loupeActions';
 export { createLoupeActions, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID } from './loupeActions';
 export type { TrialLoupeProps } from './TrialLoupe';
 export { TrialLoupe } from './TrialLoupe';
-export type {
-  LoupeCapability,
-  LoupeDeclaration,
-  LoupeRenderArgs,
-  ResolvedLoupe,
-} from './types';
+export type { LoupeOptions, LoupeRenderArgs, ResolvedLoupe } from './types';
 export { LOUPE_DEFAULTS, resolveLoupe } from './types';
 export type { LoupeState, UseLoupeOptions } from './useLoupe';
 export { useLoupe } from './useLoupe';

package/src/loupe/types.test.ts

@@ -2,11 +2,11 @@ import { describe, expect, it } from 'vitest';
 import { LOUPE_DEFAULTS, resolveLoupe } from './types';
 
 describe('resolveLoupe', () => {
-  it('takes every default from a bare `true`', () => {
-    expect(resolveLoupe(true)).toMatchObject(LOUPE_DEFAULTS);
+  it('takes every default when given nothing', () => {
+    expect(resolveLoupe()).toMatchObject(LOUPE_DEFAULTS);
   });
 
-  it('keeps what the instrument declared', () => {
+  it('keeps what it was given', () => {
     const cap = resolveLoupe({ factor: 12, diameter: 320, minFactor: 1, maxFactor: 40 });
     expect(cap).toMatchObject({ factor: 12, diameter: 320, minFactor: 1, maxFactor: 40 });
   });