@weasel-js/labkit 1.2.0 → 1.3.0-pre.0

package/dist/surface/index.js

@@ -1,3 +1,4 @@
-export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-THBG7FQZ.js';
+export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-HFDVGF4X.js';
+import '../chunk-Z6HJ5FEM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/ui/layers/index.js

@@ -1,5 +1,6 @@
-export { LayerStack } from '../../chunk-G5TJVQQT.js';
-import '../../chunk-73KA7WBO.js';
-import '../../chunk-BOHF3PQO.js';
+export { LayerStack } from '../../chunk-O2BULFHX.js';
+import '../../chunk-TLGRYALP.js';
+import '../../chunk-Z6HJ5FEM.js';
+import '../../chunk-PQJ5B2U2.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,6 +1,8 @@
-export { U as UndoCapability } from '../_dts/index-JFAYj5Tv.js';
+export { U as UndoCapability } from '../_dts/index-DgcNdEdh.js';
 import 'react';
-import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-AHlQxBNN.js';
+import '../_dts/PrefsForm-BYa6cWnO.js';
+import '../_dts/types-1Sdxy_Pv.js';
 import '../_dts/types-DJ79Tg5J.js';
 
 /** A subscriber to a named event. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.2.0",
+  "version": "1.3.0-pre.0",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -14,6 +14,9 @@
     "url": "https://github.com/orochi235/weasel/issues"
   },
   "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -27,6 +30,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./chrome": {
+      "types": "./dist/chrome/index.d.ts",
+      "import": "./dist/chrome/index.js"
+    },
     "./primitives": {
       "types": "./dist/primitives/index.d.ts",
       "import": "./dist/primitives/index.js"
@@ -89,31 +96,33 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:smoke:consumer": "node scripts/smoke-consumer-bundle.mjs",
-    "lint": "biome check . && tsx scripts/check-class-prefix.ts",
+    "lint": "biome check . && tsx scripts/check-class-prefix.ts && tsx scripts/check-design-tokens.ts",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "dev:schema": "LABKIT_EXAMPLE=schema-lab vite"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/theme": "*",
+    "@weasel-js/core": "1.3.0-pre.0",
+    "@weasel-js/theme": "1.3.0-pre.0",
+    "@weasel-js/ui": "1.3.0-pre.0",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
-    "windease": "^1.2.1",
+    "windease": "^1.3.0",
     "zustand": "^5.0.12"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "*",
-    "@weasel-js/ui": "*",
+    "@weasel-js/modes": "1.3.0-pre.0",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/canvas/AGENTS.md

@@ -28,6 +28,8 @@ interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];      // { id, visible, render(ctx, view) }
   view: ViewTransform;                  // { zoom, pan: { x, y } }
   onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;                     // default 0.1, forwarded to usePanZoom
+  maxZoom?: number;                     // default 32, forwarded to usePanZoom
   width?: number | string;              // default '100%'
   height?: number | string;             // default '100%'
   className?: string;
@@ -79,6 +81,8 @@ Both are pure. Pan is applied in screen space; zoom multiplies world coordinates
 
 Implemented in `usePanZoom`. Mouse-wheel zoom is anchored at the cursor; primary-button drag pans. `isDragging()` is exposed so consumers can suppress click handlers during a pan.
 
+Zoom is clamped to `[minZoom, maxZoom]` (defaults 0.1 / 32), settable via `CanvasStack`'s props and, for an instrument's own canvas, `CanvasCapability.minZoom` / `maxZoom`. The clamp always widens to admit whatever zoom the canvas opened at — an instrument declaring `initialView.zoom: 1600` with the default range is not clamped down to 32 on the first wheel event.
+
 ## Testing notes
 
 JSDOM does not provide a real `CanvasRenderingContext2D`. Tests in `CanvasStack.test.tsx` rely on the scheduler's defensive checks; they do not assert pixels. For pixel testing, use Storybook's `chromatic` or visual snapshots in a real browser.

package/src/canvas/CanvasStack.tsx

@@ -10,6 +10,8 @@ export interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];
   view: ViewTransform;
   onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;
+  maxZoom?: number;
   width?: number | string;
   height?: number | string;
   className?: string;
@@ -24,6 +26,8 @@ export function CanvasStack({
   layers,
   view,
   onViewChange,
+  minZoom,
+  maxZoom,
   width = '100%',
   height = '100%',
   className,
@@ -59,8 +63,8 @@ export function CanvasStack({
     return () => ro.disconnect();
   }, []);
 
-  const handlers = usePanZoom({ view, onViewChange });
-  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size });
+  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom });
+  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(() => ({ view }), [view]);
 

package/src/canvas/useLayerScheduler.ts

@@ -1,3 +1,4 @@
+import { useVisibleRaf } from '@weasel-js/core';
 import { type RefObject, useEffect, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
 
@@ -14,11 +15,19 @@ interface SchedulerOptions {
   view: ViewTransform;
   canvasRefs: RefObject<Map<string, HTMLCanvasElement>>;
   size: { width: number; height: number; dpr: number };
+  /** The element the stack occupies. Given one, the scheduler also stops while
+   *  the stack sits outside the viewport. */
+  host?: RefObject<Element | null>;
 }
 
-export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerOptions): void {
+export function useLayerScheduler({
+  layers,
+  view,
+  canvasRefs,
+  size,
+  host,
+}: SchedulerOptions): void {
   const dirty = useRef<Set<string>>(new Set());
-  const rafId = useRef<number | null>(null);
   const lastRenderRef = useRef<Map<string, CanvasLayerDescriptor['render']>>(new Map());
 
   useEffect(() => {
@@ -37,9 +46,11 @@ export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerO
     for (const layer of layers) dirty.current.add(layer.id);
   }, [view, size, layers]);
 
-  useEffect(() => {
-    const tick = () => {
-      rafId.current = null;
+  // Painting only what is dirty is not the same as doing nothing: a hidden tab
+  // still commits React updates, and the effect above marks every layer dirty
+  // on any view or size change. The gate is what actually stops the work.
+  const frameLoop = useVisibleRaf(
+    () => {
       if (dirty.current.size === 0) return;
       const map = canvasRefs.current;
       if (!map) {
@@ -60,15 +71,11 @@ export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerO
         ctx.restore();
       }
       dirty.current.clear();
-    };
-    if (dirty.current.size > 0 && rafId.current === null) {
-      rafId.current = requestAnimationFrame(tick);
-    }
-    return () => {
-      if (rafId.current !== null) {
-        cancelAnimationFrame(rafId.current);
-        rafId.current = null;
-      }
-    };
+    },
+    { target: host },
+  );
+
+  useEffect(() => {
+    if (dirty.current.size > 0) frameLoop.request();
   });
 }

package/src/canvas/usePanZoom.test.ts

@@ -0,0 +1,80 @@
+import { act, renderHook } from '@testing-library/react';
+import type { WheelEvent } from 'react';
+import { describe, expect, it } from 'vitest';
+import type { ViewTransform } from '../instrument/types';
+import { type UsePanZoomOptions, usePanZoom } from './usePanZoom';
+
+function wheelEvent(deltaY: number): WheelEvent<HTMLElement> {
+  return {
+    deltaY,
+    clientX: 0,
+    clientY: 0,
+    preventDefault: () => {},
+    currentTarget: { getBoundingClientRect: () => ({ left: 0, top: 0, width: 0, height: 0 }) },
+  } as unknown as WheelEvent<HTMLElement>;
+}
+
+/** Renders the hook the way `CanvasStack` drives it: `view` lives in the
+ *  test, `onViewChange` writes it, and each wheel call re-renders the hook
+ *  with the updated view before returning it. */
+function setup(initialView: ViewTransform, options?: Partial<UsePanZoomOptions>) {
+  let view = initialView;
+  const onViewChange = (v: ViewTransform) => {
+    view = v;
+  };
+  const { result, rerender } = renderHook(
+    (props: { view: ViewTransform }) => usePanZoom({ ...options, view: props.view, onViewChange }),
+    { initialProps: { view: initialView } },
+  );
+  const wheel = (deltaY: number): ViewTransform => {
+    act(() => result.current.onWheel(wheelEvent(deltaY)));
+    rerender({ view });
+    return view;
+  };
+  return { wheel, getView: () => view };
+}
+
+describe('usePanZoom', () => {
+  it('does not collapse a canvas opening far outside the default range on the first wheel event', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } });
+    const next = wheel(-1); // zoom in slightly
+    expect(next.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('keeps the opening zoom reachable after zooming away from it', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } });
+    // Zoom far out.
+    for (let i = 0; i < 20; i++) wheel(1000);
+    const zoomedOut = wheel(1000);
+    expect(zoomedOut.zoom).toBeLessThan(1600);
+    // Zoom back in — the opening view must still be reachable.
+    for (let i = 0; i < 40; i++) wheel(-1000);
+    const zoomedIn = wheel(-1000);
+    expect(zoomedIn.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('admits the opening zoom even when an explicit maxZoom is lower than it', () => {
+    const { wheel } = setup({ zoom: 1600, pan: { x: 0, y: 0 } }, { maxZoom: 32 });
+    const next = wheel(-1);
+    expect(next.zoom).toBeCloseTo(1600, 0);
+  });
+
+  it('falls back to the plain defaults when the opening zoom is non-finite or zero', () => {
+    const nanCase = setup({ zoom: Number.NaN, pan: { x: 0, y: 0 } });
+    const nanResult = nanCase.wheel(-100000);
+    expect(nanResult.zoom).toBeCloseTo(32, 5);
+    expect(Number.isNaN(nanResult.zoom)).toBe(false);
+
+    const zeroCase = setup({ zoom: 0, pan: { x: 0, y: 0 } });
+    const zeroResult = zeroCase.wheel(100000);
+    expect(zeroResult.zoom).toBeCloseTo(0.1, 5);
+  });
+
+  it('still clamps ordinary views to the default range', () => {
+    const { wheel } = setup({ zoom: 1, pan: { x: 0, y: 0 } });
+    const zoomedIn = wheel(-1_000_000);
+    expect(zoomedIn.zoom).toBeCloseTo(32, 5);
+    const zoomedOut = wheel(1_000_000);
+    expect(zoomedOut.zoom).toBeCloseTo(0.1, 5);
+  });
+});

package/src/canvas/usePanZoom.ts

@@ -4,6 +4,8 @@ import type { ViewTransform } from '../instrument/types';
 export interface UsePanZoomOptions {
   view: ViewTransform;
   onViewChange: (v: ViewTransform) => void;
+  /** The opening `view.zoom` always stays reachable, widening these past
+   *  whatever is passed here if it would otherwise exclude it. */
   minZoom?: number;
   maxZoom?: number;
 }
@@ -26,6 +28,10 @@ interface DragState {
 
 const DRAG_THRESHOLD = 3;
 
+function isPositiveFinite(n: number): boolean {
+  return Number.isFinite(n) && n > 0;
+}
+
 export function usePanZoom({
   view,
   onViewChange,
@@ -35,6 +41,10 @@ export function usePanZoom({
   const dragRef = useRef<DragState | null>(null);
   const viewRef = useRef(view);
   viewRef.current = view;
+  // Captured once, from the view the canvas opened at — not the current view,
+  // which would let a prior zoom-out shrink the range and trap the opening
+  // view unreachable behind it.
+  const initialZoomRef = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
 
   const onWheel = useCallback(
     (e: WheelEvent<HTMLElement>) => {
@@ -43,9 +53,13 @@ export function usePanZoom({
       const cursorX = e.clientX - rect.left;
       const cursorY = e.clientY - rect.top;
       const v = viewRef.current;
+      const initialZoom = initialZoomRef.current;
+      const effectiveMin = initialZoom == null ? minZoom : Math.min(minZoom, initialZoom);
+      const effectiveMax = initialZoom == null ? maxZoom : Math.max(maxZoom, initialZoom);
       const factor = Math.exp(-e.deltaY * 0.001);
-      const nextZoom = Math.min(maxZoom, Math.max(minZoom, v.zoom * factor));
-      const ratio = nextZoom / v.zoom;
+      const rawZoom = isPositiveFinite(v.zoom) ? v.zoom : 1;
+      const nextZoom = Math.min(effectiveMax, Math.max(effectiveMin, rawZoom * factor));
+      const ratio = nextZoom / rawZoom;
       const nextPan = {
         x: cursorX - (cursorX - v.pan.x) * ratio,
         y: cursorY - (cursorY - v.pan.y) * ratio,

package/src/chrome/ChromeRegions.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { CrosshairIcon, HandIcon, PencilIcon } from '@weasel-js/ui';
+import type { ConfigField } from '../controls/types';
+import type { Instrument } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+
+interface DemoConfig extends Record<string, unknown> {
+  radius: number;
+  filled: boolean;
+}
+
+interface DemoState extends Record<string, unknown> {
+  spokes: number;
+}
+
+const fields: ConfigField[] = [
+  { key: 'radius', label: 'Radius', type: 'slider', default: 60, min: 10, max: 120, step: 1 },
+  { key: 'filled', label: 'Filled', type: 'checkbox', default: true },
+];
+
+/** Declares every capability that contributes chrome, so all five trial
+ *  regions render at once. */
+const FullInstrument: Instrument<DemoState, DemoConfig> = {
+  name: 'Every Region',
+  defaultConfig: () => ({ radius: 60, filled: true }),
+  initialState: () => ({ spokes: 7 }),
+  configSchema: () => fields,
+  undo: {},
+  layers: { ids: ['wheel'] },
+  tools: {
+    tools: [
+      { id: 'draw', label: 'Draw', icon: PencilIcon, shortcut: 'D' },
+      { id: 'pan', label: 'Pan', icon: HandIcon, shortcut: 'H' },
+      { id: 'measure', label: 'Measure', icon: CrosshairIcon, shortcut: 'M' },
+    ],
+  },
+  canvas: {
+    layers: [
+      {
+        id: 'wheel',
+        draw: (ctx, { state, config }) => {
+          ctx.strokeStyle = '#8ab';
+          ctx.fillStyle = 'rgba(136, 170, 187, 0.25)';
+          ctx.lineWidth = 1.5;
+          ctx.beginPath();
+          ctx.arc(160, 120, config.radius, 0, Math.PI * 2);
+          if (config.filled) ctx.fill();
+          ctx.stroke();
+          for (let i = 0; i < state.spokes; i++) {
+            const a = (i / state.spokes) * Math.PI * 2;
+            ctx.beginPath();
+            ctx.moveTo(160, 120);
+            ctx.lineTo(160 + Math.cos(a) * config.radius, 120 + Math.sin(a) * config.radius);
+            ctx.stroke();
+          }
+        },
+      },
+    ],
+  },
+  render: ({ trial }) => (
+    <div className="lk-region-demo-readout">tool: {trial.activeToolId ?? 'none'}</div>
+  ),
+};
+
+const meta: Meta<typeof Lab> = {
+  title: 'labkit/Chrome/Regions',
+  component: Lab,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Lab>;
+
+export const EveryRegion: Story = {
+  args: {
+    instruments: [FullInstrument],
+    defaultInstrument: 'Every Region',
+    title: 'Chrome Regions',
+    storage: null,
+  },
+};
+
+/** A consumer dropping a built-in and adding its own in its place. */
+export const SuppressedAndReplaced: Story = {
+  args: {
+    instruments: [FullInstrument],
+    defaultInstrument: 'Every Region',
+    title: 'Suppress + Replace',
+    storage: null,
+    suppress: ['snapshot'],
+    chrome: [
+      {
+        id: 'export',
+        region: 'toolbar',
+        group: 'trial',
+        end: true,
+        item: {
+          icon: CrosshairIcon,
+          label: 'Export',
+          showLabel: true,
+          onActivate: () => {},
+        },
+      },
+    ],
+  },
+};

package/src/chrome/builtins.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { f } from '../config/builder';
+import { fromConfigFields } from '../config/fromConfigField';
+import { resolveConfigSchema } from '../config/resolve';
+import type { Instrument } from '../instrument/types';
+import { builtinContributions } from './builtins';
+import type { TrialChromeContext } from './types';
+
+const ctx: TrialChromeContext = {
+  trialId: 't1',
+  instrumentName: 'Stub',
+  isLastTrial: false,
+  zoom: 1,
+  setZoom: () => {},
+  canUndo: true,
+  canRedo: false,
+  undo: () => {},
+  redo: () => {},
+  configFields: [],
+  configSchema: fromConfigFields([]),
+  config: {},
+  setConfig: () => {},
+  savedSnapshots: [],
+  saveSnapshot: () => {},
+  loadSnapshot: () => {},
+  clone: () => {},
+  reset: () => {},
+  close: () => {},
+  activeToolId: null,
+  setActiveTool: () => {},
+};
+
+const bare: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+const withCanvas: Instrument = { ...bare, canvas: { layers: [] } };
+
+const ctxWithZoom = (zoom: number | null): TrialChromeContext => ({ ...ctx, zoom });
+
+function ids(instrument: Instrument, c: TrialChromeContext = ctx): string[] {
+  return builtinContributions(instrument, c).map((x) => x.id);
+}
+
+describe('builtinContributions', () => {
+  it('always contributes the trial actions', () => {
+    expect(ids(bare)).toEqual(['snapshot', 'clone', 'reset', 'close']);
+  });
+
+  it('contributes undo and redo only when the instrument declares undo', () => {
+    expect(ids(bare)).not.toContain('undo');
+    expect(ids({ ...bare, undo: {} })).toContain('undo');
+    expect(ids({ ...bare, undo: {} })).toContain('redo');
+  });
+
+  it('puts zoom controls in the viewport region, not the toolbar', () => {
+    const zoomIn = builtinContributions(withCanvas, ctx).find((c) => c.id === 'zoom-in');
+    expect(zoomIn?.region).toBe('viewport');
+  });
+
+  it('contributes no viewport controls when the view is not 2D', () => {
+    expect(ids(withCanvas, ctxWithZoom(null))).not.toContain('zoom-in');
+  });
+
+  it('contributes a settings section only when the schema has fields', () => {
+    expect(ids(bare)).not.toContain('settings');
+    const withFields = {
+      ...ctx,
+      configSchema: fromConfigFields([
+        { key: 'n', label: 'N', type: 'number' as const, default: 1 },
+      ]),
+    };
+    expect(ids(bare, withFields)).toContain('settings');
+  });
+
+  it('contributes a settings section for a builder schema too', () => {
+    const withSchema = {
+      ...ctx,
+      configSchema: resolveConfigSchema(f.schema({ showGrid: f.boolean(true) }), []),
+    };
+    expect(ids(bare, withSchema)).toContain('settings');
+  });
+
+  it('reflects undo availability in the item, not by omitting it', () => {
+    const withUndo: Instrument = { ...bare, undo: {} };
+    const list = builtinContributions(withUndo, { ...ctx, canUndo: false });
+    const undo = list.find((c) => c.id === 'undo');
+    expect(undo?.item).toMatchObject({ disabled: true });
+  });
+
+  it('marks close as danger and disables it on the last trial', () => {
+    const list = builtinContributions(bare, { ...ctx, isLastTrial: true });
+    expect(list.find((c) => c.id === 'close')?.item).toMatchObject({
+      danger: true,
+      disabled: true,
+    });
+  });
+
+  it('offers the snapshot loader only once a snapshot has been taken', () => {
+    expect(ids(bare)).not.toContain('snapshot-load');
+    const withSaves = {
+      ...ctx,
+      savedSnapshots: [
+        {
+          id: 's1',
+          name: 'First',
+          trialId: 't1',
+          instrumentName: 'Stub',
+          config: {},
+          state: {},
+          savedAt: 1,
+        },
+      ],
+    };
+    expect(ids(bare, withSaves)).toContain('snapshot-load');
+  });
+
+  it('produces no duplicate ids for a fully-declared instrument', () => {
+    const full: Instrument = {
+      ...bare,
+      undo: {},
+      canvas: { layers: [] },
+      layers: { ids: ['a'] },
+    };
+    const list = builtinContributions(full, ctx);
+    expect(new Set(list.map((c) => c.id)).size).toBe(list.length);
+  });
+});
+
+describe('view readouts', () => {
+  it('contributes fps and scale to the status bar when the trial has a canvas', () => {
+    const out = builtinContributions(withCanvas, ctxWithZoom(1));
+    const status = out.filter((c) => c.region === 'status').map((c) => c.id);
+    expect(status).toContain('fps');
+    expect(status).toContain('scale');
+  });
+
+  it('contributes the zoom control to the viewport, replacing the readout', () => {
+    const out = builtinContributions(withCanvas, ctxWithZoom(1));
+    const viewport = out.filter((c) => c.region === 'viewport').map((c) => c.id);
+    expect(viewport).toContain('zoom-control');
+    expect(out.map((c) => c.id)).not.toContain('zoom-readout');
+  });
+
+  it('contributes none of them to a trial with no canvas', () => {
+    const out = builtinContributions(bare, ctxWithZoom(null));
+    expect(out.map((c) => c.id)).not.toContain('fps');
+    expect(out.map((c) => c.id)).not.toContain('zoom-control');
+  });
+});