@weasel-js/labkit 1.6.1 → 1.7.1

package/src/loupe/types.ts

@@ -3,11 +3,9 @@ import type { ReactNode } from 'react';
 import type { ViewportSize } from '../canvas/worldSpec';
 import type { ViewTransform } from '../instrument/types';
 
-/** What a DOM instrument's loupe `render` is handed: the same data its own
- *  `render` gets, and the camera to draw it through. */
-export interface LoupeRenderArgs<TS = unknown, TC = unknown> {
-  state: TS;
-  config: TC;
+/** What a DOM loupe's `render` is handed: the camera to draw the content
+ *  through again. */
+export interface LoupeRenderArgs {
   /** The trial's own camera composed with the magnification, about the aimed
    *  point — so drawing the same content through it magnifies in place. */
   view: ViewTransform;
@@ -21,14 +19,14 @@ export interface LoupeRenderArgs<TS = unknown, TC = unknown> {
 }
 
 /**
- * Declares that an instrument can be magnified.
+ * How a lens magnifies.
  *
- * With no `render`, the loupe re-draws the instrument's canvas layers through a
- * zoomed camera, so it stays sharp at any factor. An instrument whose content is
- * DOM supplies `render` instead: given a camera, draw me again.
+ * With no `render`, the lens re-draws the canvas stack's layers through a
+ * zoomed camera, so it stays sharp at any factor. Over DOM content, `render`
+ * draws it instead: given a camera, draw me again.
  */
-export interface LoupeCapability<TS = unknown, TC = unknown> {
-  render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+export interface LoupeOptions {
+  render?: (args: LoupeRenderArgs) => ReactNode;
   /** Opening magnification, clamped to the bounds below. Default 6. */
   factor?: number;
   /** What the wheel clamps to. Defaults 2 and 32. */
@@ -48,12 +46,9 @@ export interface LoupeCapability<TS = unknown, TC = unknown> {
   onColorChange?: (hex: string) => void;
 }
 
-/** An instrument's loupe declaration. `true` takes every default. */
-export type LoupeDeclaration<TS = unknown, TC = unknown> = true | LoupeCapability<TS, TC>;
-
-/** A {@link LoupeCapability} with every default filled in. */
-export interface ResolvedLoupe<TS = unknown, TC = unknown> {
-  render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+/** {@link LoupeOptions} with every default filled in. */
+export interface ResolvedLoupe {
+  render?: (args: LoupeRenderArgs) => ReactNode;
   onColorChange?: (hex: string) => void;
   factor: number;
   minFactor: number;
@@ -63,6 +58,7 @@ export interface ResolvedLoupe<TS = unknown, TC = unknown> {
   peekKey: string | null;
 }
 
+/** What `resolveLoupe` fills in for anything a declaration leaves unset. */
 export const LOUPE_DEFAULTS = {
   factor: 6,
   minFactor: 2,
@@ -72,19 +68,20 @@ export const LOUPE_DEFAULTS = {
   peekKey: 'Alt',
 } as const satisfies Omit<ResolvedLoupe, 'render' | 'onColorChange'>;
 
-export function resolveLoupe<TS, TC>(declared: LoupeDeclaration<TS, TC>): ResolvedLoupe<TS, TC> {
-  const cap = declared === true ? {} : declared;
-  const minFactor = cap.minFactor ?? LOUPE_DEFAULTS.minFactor;
-  const maxFactor = cap.maxFactor ?? LOUPE_DEFAULTS.maxFactor;
+/** `options` with every default filled in and `factor` clamped to
+ *  `[minFactor, maxFactor]`. A loupe with its own `render` is always `'vector'`. */
+export function resolveLoupe(options: LoupeOptions = {}): ResolvedLoupe {
+  const minFactor = options.minFactor ?? LOUPE_DEFAULTS.minFactor;
+  const maxFactor = options.maxFactor ?? LOUPE_DEFAULTS.maxFactor;
   return {
-    render: cap.render,
-    onColorChange: cap.onColorChange,
+    render: options.render,
+    onColorChange: options.onColorChange,
     minFactor,
     maxFactor,
-    factor: Math.min(maxFactor, Math.max(minFactor, cap.factor ?? LOUPE_DEFAULTS.factor)),
-    diameter: cap.diameter ?? LOUPE_DEFAULTS.diameter,
-    peekKey: cap.peekKey === undefined ? LOUPE_DEFAULTS.peekKey : cap.peekKey,
+    factor: Math.min(maxFactor, Math.max(minFactor, options.factor ?? LOUPE_DEFAULTS.factor)),
+    diameter: options.diameter ?? LOUPE_DEFAULTS.diameter,
+    peekKey: options.peekKey === undefined ? LOUPE_DEFAULTS.peekKey : options.peekKey,
     // A DOM loupe has no framebuffer, so `pixel` would have nothing to enlarge.
-    mode: cap.render ? 'vector' : (cap.mode ?? LOUPE_DEFAULTS.mode),
+    mode: options.render ? 'vector' : (options.mode ?? LOUPE_DEFAULTS.mode),
   };
 }

package/src/loupe/useLoupe.test.tsx

@@ -1,5 +1,6 @@
 import { act, fireEvent, render, screen } from '@testing-library/react';
 import { WeaselProvider } from '@weasel-js/core';
+import { renderThenAbandon } from '@weasel-js/react/testing/abandonRender';
 import { type RefObject, StrictMode, useRef } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import { LoupeGestures } from './LoupeGestures';
@@ -23,12 +24,12 @@ interface HarnessProps {
  *  cases below exercise the real dispatcher route rather than a stand-in. */
 function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
   const hostRef = useRef<HTMLDivElement | null>(null);
-  const capability = resolveLoupe(rest);
+  const options = resolveLoupe(rest);
   const loupe = useLoupe({
     hostRef: hostRef as RefObject<HTMLElement | null>,
     enabled,
     sample,
-    capability,
+    options,
   });
   seen?.(loupe);
   return (
@@ -37,7 +38,7 @@ function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
         <LoupeGestures
           hostRef={hostRef as RefObject<HTMLElement | null>}
           input={loupe.input}
-          peekKey={capability.peekKey ?? null}
+          peekKey={options.peekKey ?? null}
         />
       </WeaselProvider>
       <span data-testid="visible">{String(loupe.visible)}</span>
@@ -92,7 +93,7 @@ describe('useLoupe', () => {
     expect(read('visible')).toBe('false');
   });
 
-  it('does not peek when the capability turned the key off', () => {
+  it('does not peek when its options turned the key off', () => {
     render(<Harness enabled={false} peekKey={null} />);
     move(40, 25);
     act(() => {
@@ -251,4 +252,28 @@ describe('useLoupe', () => {
     });
     expect(read('mode')).toBe('pixel');
   });
+
+  it('aims as the committed `enabled` allows, not an abandoned render', () => {
+    const seen: LoupeState[] = [];
+    // Reads the aim back through the model: the DOM is not re-rendered while
+    // the abandoned transition is still pending.
+    const aimOf = (p: { x: number; y: number }) => `${p.x},${p.y}`;
+    renderThenAbandon({ enabled: false }, { enabled: true }, (p) => (
+      <Harness enabled={p.enabled} sample={aimOf} seen={(l) => seen.push(l)} />
+    ));
+    const before = seen[0]?.pick();
+    move(40, 25);
+    expect(seen[0]?.pick()).toBe(before);
+  });
+
+  it('samples through the committed `sample`, not an abandoned render', () => {
+    const seen: LoupeState[] = [];
+    const committed = vi.fn(() => '#111111');
+    const abandoned = vi.fn(() => '#222222');
+    renderThenAbandon({ sample: committed }, { sample: abandoned }, (p) => (
+      <Harness sample={p.sample} seen={(l) => seen.push(l)} />
+    ));
+    expect(seen[0]?.pick()).toBe('#111111');
+    expect(abandoned).not.toHaveBeenCalled();
+  });
 });

package/src/loupe/useLoupe.ts

@@ -1,3 +1,4 @@
+import { useLatest } from '@weasel-js/core';
 import {
   createLoupeModel,
   type LoupeMode,
@@ -11,7 +12,7 @@ import type { ResolvedLoupe } from './types';
 
 /** Options for {@link useLoupe}. */
 export interface UseLoupeOptions {
-  capability: ResolvedLoupe;
+  options: ResolvedLoupe;
   /** The element the lens tracks the pointer across. */
   hostRef: RefObject<HTMLElement | null>;
   /** Whether the loupe is turned on. Hold-to-peek shows it regardless. */
@@ -39,6 +40,11 @@ export interface LoupeState {
   input: LoupeInputApi;
 }
 
+/** Whether the lens is up: the pointer is over the host, and the loupe is on or peeked. */
+function lensShown(over: boolean, enabled: boolean, peeking: boolean): boolean {
+  return over && (enabled || peeking);
+}
+
 /**
  * Binds `@weasel-js/loupe`'s model to a host element and tracks the pointer
  * across it.
@@ -50,31 +56,28 @@ export interface LoupeState {
  * has no continuous-motion entry, and inventing one to carry the lens' aim
  * would be an input taxonomy change, not a loupe change.
  */
-export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptions): LoupeState {
+export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions): LoupeState {
   const [, bump] = useReducer((n: number) => n + 1, 0);
 
   const overRef = useRef(false);
   const peekingRef = useRef(false);
-  const enabledRef = useRef(enabled);
-  enabledRef.current = enabled;
-  const sampleRef = useRef(sample);
-  sampleRef.current = sample;
-  const onColorChangeRef = useRef(capability.onColorChange);
-  onColorChangeRef.current = capability.onColorChange;
+  const enabledRef = useLatest(enabled);
+  const sampleRef = useLatest(sample);
+  const onColorChangeRef = useLatest(options.onColorChange);
 
   // Reads nothing but refs, so it is stable and an effect may depend on it.
   const shown = useCallback(
-    (): boolean => overRef.current && (enabledRef.current || peekingRef.current),
-    [],
+    (): boolean => lensShown(overRef.current, enabledRef.current, peekingRef.current),
+    [enabledRef],
   );
 
   const modelRef = useRef<LoupeModel | null>(null);
   if (modelRef.current === null) {
     modelRef.current = createLoupeModel({
-      mode: capability.mode,
-      factor: capability.factor,
-      minFactor: capability.minFactor,
-      maxFactor: capability.maxFactor,
+      mode: options.mode,
+      factor: options.factor,
+      minFactor: options.minFactor,
+      maxFactor: options.maxFactor,
       onColorChange: (hex) => onColorChangeRef.current?.(hex),
       surface: {
         lens: () => {
@@ -94,8 +97,7 @@ export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptio
   }
   const model = modelRef.current;
 
-  const diameterRef = useRef(capability.diameter);
-  diameterRef.current = capability.diameter;
+  const diameterRef = useLatest(options.diameter);
   const goneRef = useRef(false);
 
   // The model holds no resources, and `dispose` is one-way — so unmounting only
@@ -156,7 +158,8 @@ export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptio
   }
 
   return {
-    visible: shown(),
+    // This render's `enabled`: `enabledRef` holds the last committed one.
+    visible: lensShown(overRef.current, enabled, peekingRef.current),
     aim: model.aim,
     factor: model.factor,
     mode: model.mode,

package/src/overview/OverviewMarks.tsx

@@ -1,6 +1,7 @@
 /**
  * Every annotation target's marks, drawn read-only on the overview through the
- * export's own vector path: `markSvgNodes`, then `serializeSvg`.
+ * export's own vector path: `markSvgNodes`, then `serializeSvg` — synchronous
+ * with no `warmSvg`, since marks export nothing that loads on demand.
  */
 import type { View } from '@weasel-js/core';
 import { serializeSvg } from '@weasel-js/svg';
@@ -40,10 +41,17 @@ function elementOf(target: object): HTMLElement | null {
   return (target as { ref?: RefObject<HTMLElement | null> }).ref?.current ?? null;
 }
 
-function markupOf(api: AnnotationsApi, target: string, content: { w: number; h: number }): string {
+function markupOf(
+  api: AnnotationsApi,
+  target: string,
+  content: { w: number; h: number },
+  shown: { w: number; h: number },
+): string {
   const painted = api.paintedMarks(target);
   if (painted.length === 0) return '';
-  const nodes = painted.flatMap(({ mark, style }) => markSvgNodes(mark, content, style));
+  // The document is shown at `shown` px, fitted like any SVG viewBox.
+  const k = Math.min(shown.w / content.w, shown.h / content.h) || 1;
+  const nodes = painted.flatMap(({ mark, style }) => markSvgNodes(mark, style, { x: k, y: k }));
   return serializeSvg(nodes, { viewBox: { x: 0, y: 0, width: content.w, height: content.h } });
 }
 
@@ -69,7 +77,7 @@ export function OverviewMarks({ fit, camera }: OverviewMarksProps) {
       {api.targets().map((t) => {
         const el = elementOf(t);
         const box = el ? localRectOf(el, camera) : null;
-        const markup = box ? markupOf(api, t.id, t.content) : '';
+        const markup = box ? markupOf(api, t.id, t.content, { w: box.w * s, h: box.h * s }) : '';
         if (!box || !markup) return null;
         const place = {
           ['--lk-overview-mx' as string]: `${(box.x - fit.x) * s}px`,

package/src/overview/TrialOverview.tsx

@@ -20,6 +20,7 @@ import {
   useActionsRegistry,
   useDepSource,
   useGestureDispatcher,
+  useLatest,
   usePointerPosition,
   type View,
   type ViewApi,
@@ -163,11 +164,13 @@ function Overview({
 }: TrialOverviewProps & { camera: CameraContextValue }) {
   const size = useMemo(() => ({ width, height }), [width, height]);
   const content = bounds ? toLocalRect(bounds, camera.frame) : camera.content;
-  const contentKey = content ? `${content.x},${content.y},${content.width},${content.height}` : '';
-  // biome-ignore lint/correctness/useExhaustiveDependencies: `content` is rebuilt every render; its numbers, in `contentKey`, are what the fit depends on.
+  // `content` is rebuilt every render, so the fit keys on its numbers.
+  const framed = content !== null && content !== undefined;
+  const { x = 0, y = 0, width: w = 0, height: h = 0 } = content ?? {};
   const fit = useMemo(
-    () => (content ? fitRect(content, size) : { x: 0, y: 0, scale: { x: 1, y: 1 } }),
-    [contentKey, size],
+    () =>
+      framed ? fitRect({ x, y, width: w, height: h }, size) : { x: 0, y: 0, scale: { x: 1, y: 1 } },
+    [framed, x, y, w, h, size],
   );
   const boxRef = useRef<HTMLDivElement | null>(null);
 
@@ -312,8 +315,7 @@ function OverviewDispatch({
   camera: CameraContextValue;
 }) {
   const registry = useActionsRegistry();
-  const fitRef = useRef(fit);
-  fitRef.current = fit;
+  const fitRef = useLatest(fit);
   const root = camera.view;
   useDepSource('rootView', () => root as ViewApi);
 
@@ -334,14 +336,14 @@ function OverviewDispatch({
         y: (cy - (r?.top ?? 0)) / f.scale.y + f.y,
       };
     },
-    [boxRef],
+    [boxRef, fitRef],
   );
 
   useGestureDispatcher({
     canvasRef: boxRef,
     // Always present: `OverviewInput` mounts the provider directly above.
     actions: registry as NonNullable<typeof registry>,
-    toolsById: TOOLS_BY_ID,
+    entriesById: TOOLS_BY_ID,
     clientToWorld: clientToLocal,
     keyboard: false,
     channels: CHANNELS,

package/src/passthrough/weasel-ui.test.ts

@@ -24,6 +24,7 @@ import {
   Sidebar,
   Slider,
   Switch,
+  sampleByInterpolation,
   Tabs,
   ToolPalette,
   useReorderDragList,
@@ -38,6 +39,7 @@ describe('weasel-ui passthrough', () => {
     expect(typeof useReorderDragList).toBe('function');
     expect(typeof paintGradientTrack).toBe('function');
     expect(typeof oklchToHex).toBe('function');
+    expect(typeof sampleByInterpolation).toBe('function');
     expect(typeof chromaAt).toBe('function');
   });
 

package/src/passthrough/weasel-ui.ts

@@ -5,6 +5,7 @@
  * future without consumer churn.
  */
 
+export { formatNumber, MINUS_SIGN } from '@weasel-js/quantity';
 export {
   ActionBar,
   type ActionBarProps,
@@ -21,6 +22,7 @@ export {
   type BadgeVariant,
   type BoundsCtx,
   type BuiltInEdgeName,
+  type BuiltInProfileName,
   type BuiltinPref,
   Button,
   ButtonBar,
@@ -38,6 +40,9 @@ export {
   type CheckboxProps,
   type ChromaCurve,
   type ChromaCurvePoint,
+  CloseButton,
+  type CloseButtonProps,
+  COLOR_MODE_OPTIONS,
   ColorModeControl,
   type ColorModeControlProps,
   ComboBox,
@@ -65,8 +70,8 @@ export {
   type DisclosureRowProps,
   DragGhost,
   type DragGhostProps,
-  DragHandleGlyph,
-  type DragHandleGlyphProps,
+  DragGrip,
+  type DragGripProps,
   detectPlatform,
   dlog,
   EDGE_PROFILES,
@@ -78,11 +83,13 @@ export {
   type FieldProps,
   type FillSettings,
   fieldClasses,
-  formatNumber,
   formatShortcut,
   formatShortcutParts,
+  GestureRoute,
+  type GestureRouteProps,
   type GradientTrackOpts,
   type GridSettings,
+  gestureRouteSegments,
   ICON_PATHS,
   Icon,
   type IconName,
@@ -98,6 +105,7 @@ export {
   type KeyCapVariant,
   type KeycapKind,
   KeySequence,
+  type KeySequenceJoins,
   type KeySequenceProps,
   type KeySpec,
   keyGlyph,
@@ -115,7 +123,6 @@ export {
   MenuButton,
   type MenuButtonItem,
   type MenuButtonProps,
-  MINUS_SIGN,
   moveLayers,
   NumberField,
   type NumberFieldProps,
@@ -138,6 +145,7 @@ export {
   type PowerlineSegment,
   type PrefBoolean,
   type PrefBooleanControl,
+  type PrefBooleanEncoding,
   type PrefColor,
   type PrefCustom,
   type PrefEnum,
@@ -174,7 +182,7 @@ export {
   type ReorderDragHandlers,
   type ReorderDragState,
   type ReorderGhost,
-  type RovingItem,
+  type RovingOrientation,
   type RovingTabIndex,
   type SegmentTooltipFields,
   Select,
@@ -191,6 +199,7 @@ export {
   type StanceProps,
   Switch,
   type SwitchProps,
+  sampleByInterpolation,
   Tab,
   TabList,
   type TabListProps,
@@ -199,6 +208,9 @@ export {
   type TabProps,
   Tabs,
   type TabsProps,
+  ThemeSwitcher,
+  type ThemeSwitcherOption,
+  type ThemeSwitcherProps,
   type Thumb,
   type ThumbRenderCtx,
   type ThumbShape,

package/src/primitives/FloatingPanel.test.tsx

@@ -1,4 +1,5 @@
 import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { DRAG_THRESHOLD_PX } from '@weasel-js/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createMemoryAdapter } from '../state/adapters';
 import { labPrefix } from '../state/labRecords';
@@ -130,6 +131,16 @@ describe('FloatingPanel dragging', () => {
     expect(panel.dataset.dragging).toBeUndefined();
   });
 
+  it('becomes a drag at the kit drag threshold, not before', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { clientX: 100 + DRAG_THRESHOLD_PX - 0.5, clientY: 100 });
+    expect(panel.dataset.dragging).toBeUndefined();
+    fireEvent.pointerMove(panel, { clientX: 100 + DRAG_THRESHOLD_PX, clientY: 100 });
+    expect(panel.dataset.dragging).toBe('true');
+    fireEvent.pointerUp(panel);
+  });
+
   it('a press that never moves is not a drag', () => {
     const { panel } = renderPanel(<FloatingPanel anchor="top-left">x</FloatingPanel>);
     const before = panel.style.left;

package/src/primitives/FloatingPanel.tsx

@@ -1,4 +1,9 @@
-import { openPointerSession, type PointerSession } from '@weasel-js/core';
+import {
+  openPointerSession,
+  type PointerSession,
+  pastDragThreshold,
+  useLatest,
+} from '@weasel-js/core';
 import type React from 'react';
 import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 import {
@@ -41,9 +46,6 @@ function borderBoxOf(entry: ResizeObserverEntry): { w: number; h: number } {
   return { w: entry.contentRect.width, h: entry.contentRect.height };
 }
 
-/** How far the pointer must travel before a press becomes a drag. */
-const DRAG_THRESHOLD = 3;
-
 /** A pointerdown on one of these is the child's, not a drag. */
 function isInteractive(target: EventTarget | null): boolean {
   if (!(target instanceof Element)) return false;
@@ -122,8 +124,7 @@ export function FloatingPanel({
   // A drag outlives the render that started it, so the reducer's inputs are
   // read here and not from that render's closure — a container resized
   // mid-drag would otherwise place the panel against its old box.
-  const layout = useRef({ container, options, item });
-  layout.current = { container, options, item };
+  const layout = useLatest({ container, options, item });
 
   useEffect(() => () => session.current?.cancel(), []);
 
@@ -158,7 +159,7 @@ export function FloatingPanel({
       {
         onMove: (ev) => {
           if (!dragging.current) {
-            if (Math.hypot(ev.clientX - start.x, ev.clientY - start.y) < DRAG_THRESHOLD) return;
+            if (!pastDragThreshold({ clientX: start.x, clientY: start.y }, ev)) return;
             dragging.current = { ...start };
             setDragging(true);
             origin.setPointerCapture?.(pointerId);

package/src/primitives/JobProgress.less

@@ -18,7 +18,7 @@
     height: 100%;
     background: var(--wzl-accent);
     transform-origin: left center;
-    transition: transform 120ms linear;
+    transition: transform var(--wzl-motion-fast) linear;
   }
 
   // A job that never reports a total sweeps instead of filling, so the bar
@@ -31,6 +31,7 @@
 
   &__count {
     font-variant-numeric: tabular-nums;
+    font-family: var(--wzl-font-numeric);
     white-space: nowrap;
   }
 

package/src/primitives/Legend.stories.tsx

@@ -10,6 +10,7 @@ export default meta;
 type Story = StoryObj<typeof Legend>;
 
 export const AllMarks: Story = {
+  tags: ['gallery'],
   args: {
     entries: [
       { key: 'contour', label: 'contour', color: '#7d7f86' },