@weasel-js/labkit 1.7.0 → 1.7.1

package/src/job/useJob.ts

@@ -1,6 +1,9 @@
+import { useLatest } from '@weasel-js/core';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { JobCapability, JobFailure, JobHandle, JobStatus } from './types';
 
+/** Inputs to `useJob`. `setState` receives each item folded in by the
+ *  capability's `onItem`. */
 export interface UseJobOptions<TS, TC, TItem> {
   capability: JobCapability<TS, TC, TItem>;
   config: TC;
@@ -23,6 +26,12 @@ function sameKey(a: readonly unknown[] | null, b: readonly unknown[] | null): bo
   return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
 }
 
+/**
+ * Drive a `JobCapability` and report its progress. `start` cancels any run in
+ * flight and begins again; results from a superseded or canceled run are
+ * dropped. With `auto`, it starts on mount and again whenever `key` changes
+ * element-wise. Unmounting aborts the run.
+ */
 export function useJob<TS, TC, TItem>({
   capability,
   config,
@@ -38,14 +47,10 @@ export function useJob<TS, TC, TItem>({
 
   // Read through refs: `run` is called once per run and must see the values as of
   // that moment rather than re-subscribing on every render.
-  const capRef = useRef(capability);
-  capRef.current = capability;
-  const configRef = useRef(config);
-  configRef.current = config;
-  const stateRef = useRef(state);
-  stateRef.current = state;
-  const setStateRef = useRef(setState);
-  setStateRef.current = setState;
+  const capRef = useLatest(capability);
+  const configRef = useLatest(config);
+  const stateRef = useLatest(state);
+  const setStateRef = useLatest(setState);
 
   const cancel = useCallback(() => {
     token.current += 1;
@@ -96,7 +101,7 @@ export function useJob<TS, TC, TItem>({
         }));
       }
     })();
-  }, []);
+  }, [capRef, configRef, setStateRef, stateRef]);
 
   // Re-run when the declared key changes. `auto` covers the first mount too.
   const lastKey = useRef<readonly unknown[] | null>(null);

package/src/lab/Lab.tsx

@@ -5,6 +5,7 @@ import {
   type ReactNode,
   useCallback,
   useEffect,
+  useInsertionEffect,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -418,7 +419,10 @@ function LabRuntime({
   }, []);
 
   const ownSurface = useTiledSurface({ onFrame });
-  surfaceRef.current = ownSurface;
+  // Not `useLatest`: `onFrame` reads it, and is needed before the surface exists.
+  useInsertionEffect(() => {
+    surfaceRef.current = ownSurface;
+  }, [ownSurface]);
   const [labBody, setLabBody] = useState<HTMLDivElement | null>(null);
   const attachOwnSurface = ownSurface.containerRef;
   const labBodyRef = useCallback(

package/src/lab/LabShell.less

@@ -163,4 +163,5 @@
   min-width: 5ch;
   text-align: center;
   font-variant-numeric: tabular-nums;
+  font-family: var(--wzl-font-numeric);
 }

package/src/lab/LabSwitcher.browser.test.tsx

@@ -0,0 +1,27 @@
+import '@weasel-js/theme/tokens.css';
+import '../styles.less';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import { LabShell } from './LabShell';
+
+// The menu sits under the shell's title, so what it inherits from the title is
+// cascade, which only a real browser computes.
+
+afterEach(cleanup);
+
+const PAGES = [
+  { href: '/corpus', label: 'Wall' },
+  { href: '/stats', label: 'Dashboard' },
+];
+
+test('only the open page is bold in the shell title menu', () => {
+  render(
+    <LabShell title="corpus" pages={PAGES} path="/corpus">
+      <p>body</p>
+    </LabShell>,
+  );
+  fireEvent.click(screen.getByRole('button', { name: /corpus/ }));
+  const weight = (name: string) =>
+    Number(getComputedStyle(screen.getByRole('menuitem', { name })).fontWeight);
+  expect(weight('Wall')).toBeGreaterThan(weight('Dashboard'));
+});

package/src/lab/LabSwitcher.less

@@ -59,6 +59,8 @@
   display: flex;
   flex-direction: column;
   padding: var(--wzl-space-xs);
+  // A host's title class lands on the wrapper, so the menu would inherit its weight.
+  font-weight: var(--wzl-font-weight-normal);
   // `--wzl-surface-raised` is translucent by design -- it is for panels that
   // blur what sits behind them. A menu has to be read, so it takes the opaque
   // surface, the way `FloatingPanel` does.

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

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;
+  }
+}