@weasel-js/labkit 1.5.0 → 1.5.2

package/dist/surface/index.js

@@ -1,4 +1,4 @@
-export { composeRects, rectsEqual, toDeviceRect, useTiledSurface } from '../chunk-QLSV2N3G.js';
+export { composeRects, rectsEqual, toDeviceRect, useTiledSurface } from '../chunk-IJJUK4FU.js';
 export { SurfaceCanvasContext, SurfaceContext, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId } from '../chunk-WIG6XHJ7.js';
 import '../chunk-2YILQ7Y5.js';
 //# sourceMappingURL=index.js.map

package/dist/ui/layers/index.js

@@ -1,3 +1,3 @@
-export { c3 as LayerStack } from '../../chunk-S2SHZRD7.js';
+export { c4 as LayerStack } from '../../chunk-LASCBWW7.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,8 +1,8 @@
-export { as as UndoCapability } from '../_dts/frac-8R6UmlvN.js';
+export { au as UndoCapability } from '../_dts/frac-B4hFJMiN.js';
 import 'react';
-import '../_dts/types-Ca2LCnPq.js';
+import '../_dts/types-Db-3NNk1.js';
 import '@weasel-js/core';
-import '../_dts/PrefsForm.d-DDHFANkc.js';
+import '../_dts/PrefsForm.d-DPy9I8It.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.5.0",
+  "version": "1.5.2",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -115,17 +115,17 @@
     "dev:3d": "LABKIT_EXAMPLE=3d-lab vite"
   },
   "peerDependencies": {
-    "@weasel-js/core": "1.5.0",
+    "@weasel-js/core": "1.5.2",
+    "@weasel-js/theme": "1.5.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/geom": "1.5.0",
-    "@weasel-js/kernel3d": "1.5.0",
-    "@weasel-js/loupe": "1.5.0",
-    "@weasel-js/svg": "1.5.0",
-    "@weasel-js/theme": "1.5.0",
-    "@weasel-js/ui": "1.5.0",
+    "@weasel-js/geom": "1.5.2",
+    "@weasel-js/kernel3d": "1.5.2",
+    "@weasel-js/loupe": "1.5.2",
+    "@weasel-js/svg": "1.5.2",
+    "@weasel-js/ui": "1.5.2",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -136,7 +136,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.5.0",
+    "@weasel-js/modes": "1.5.2",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationOverlay.tsx

@@ -226,6 +226,9 @@ export function AnnotationOverlay({
         ref={setInput}
         className="lk-annotate__input"
         data-annotation-target={id}
+        // Pass-through while the rail holds a tool that makes no marks, so the
+        // instrument under the overlay stays clickable.
+        data-idle={annotationToolInfo(activeToolId) ? undefined : ''}
         role="application"
         aria-label={`Annotations on ${id}`}
         // biome-ignore lint/a11y/noNoninteractiveTabindex: role="application" IS the interactive case — a region with its own keymap. The rule's allowed-role list stops at the native widget roles and does not include it, and the gesture dispatcher listens on this element, so without focus no tool's keyboard binding ever fires.

package/src/annotations/Annotations.less

@@ -8,6 +8,10 @@
   width: var(--lk-anno-w);
   height: var(--lk-anno-h);
   z-index: 2;
+
+  &[data-idle] {
+    pointer-events: none;
+  }
 }
 
 // The sidebar list of marks. One row per mark: what it is, where it is, what

package/src/annotations/Annotations.overlay.test.tsx

@@ -146,6 +146,26 @@ describe('<AnnotationTargets>', () => {
     expect(boxes[1]?.style.getPropertyValue('--lk-anno-h')).toBe('100px');
   });
 
+  it('takes input while a mark tool is held, and passes it through otherwise', () => {
+    const drawing = render(<Harness toolId="rect" />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(drawing.container.querySelector('.lk-annotate__input')?.hasAttribute('data-idle')).toBe(
+      false,
+    );
+    drawing.unmount();
+
+    // `pointer` is in the rail but not in the tool map: the instrument under the overlay stays clickable.
+    const idle = render(<Harness toolId="pointer" />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(idle.container.querySelector('.lk-annotate__input')?.hasAttribute('data-idle')).toBe(
+      true,
+    );
+  });
+
   it('lands the boxes in the surface container, not among the instrument DOM', () => {
     const { container } = render(<Harness />, { wrapper: StrictMode });
     act(() => {

package/src/annotations/svgNodes.ts

@@ -27,6 +27,7 @@ function toSvgStroke(stroke: Stroke): SvgStroke {
     ...(stroke.join ? { join: stroke.join } : {}),
     ...(stroke.dash ? { dash: [...stroke.dash] } : {}),
     ...(stroke.miterLimit != null ? { miterLimit: stroke.miterLimit } : {}),
+    ...(stroke.align ? { align: stroke.align } : {}),
   };
 }
 

package/src/annotations/toolMap.test.ts

@@ -6,8 +6,12 @@ import type { AnnotationKind } from './types';
 const KINDS: AnnotationKind[] = ['stroke', 'line', 'arrow', 'rect', 'ellipse', 'text'];
 
 describe('the annotation tool table', () => {
-  it('offers one tool per mark kind, plus select', () => {
-    expect(ANNOTATION_TOOLS.map((t) => t.id)).toEqual(['select', ...KINDS]);
+  it('offers one tool per mark kind, plus pointer and select', () => {
+    expect(ANNOTATION_TOOLS.map((t) => t.id)).toEqual(['pointer', 'select', ...KINDS]);
+  });
+
+  it('gives pointer no entry at all, which is what leaves the overlay idle', () => {
+    expect(annotationToolInfo('pointer')).toBeUndefined();
   });
 
   it('only names weasel tools SceneCanvas will mount', () => {
@@ -15,9 +19,9 @@ describe('the annotation tool table', () => {
     // being built in should fail here rather than in a silent no-op palette.
     const mountable = new Set<string>([...KIT_SHAPE_KINDS, 'select']);
     for (const t of ANNOTATION_TOOLS) {
-      expect(mountable, `${t.id} maps to a tool the kit does not mount`).toContain(
-        annotationToolInfo(t.id)?.weaselTool,
-      );
+      const info = annotationToolInfo(t.id);
+      if (!info) continue;
+      expect(mountable, `${t.id} maps to a tool the kit does not mount`).toContain(info.weaselTool);
     }
   });
 

package/src/annotations/toolMap.ts

@@ -2,6 +2,7 @@ import type { BuiltinToolId } from '@weasel-js/core';
 import {
   ArrowIcon,
   EllipseIcon,
+  HandIcon,
   LineIcon,
   PencilIcon,
   RectIcon,
@@ -34,6 +35,8 @@ const TOOLS: Record<string, AnnotationToolInfo> = {
  *  Ids share the lab's contribution namespace with its own `tools`, and the
  *  lab's tool slot holds whichever is active. */
 export const ANNOTATION_TOOLS: readonly TrialTool[] = [
+  // Not in `TOOLS`: an id the map does not carry is what leaves the overlay idle.
+  { id: 'pointer', label: 'Interact', icon: HandIcon, group: 'annotate' },
   { id: 'select', label: 'Select', icon: SelectIcon, group: 'annotate' },
   { id: 'stroke', label: 'Freehand', icon: PencilIcon, group: 'annotate' },
   { id: 'line', label: 'Line', icon: LineIcon, group: 'annotate' },

package/src/canvas/CanvasStack.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { useState } from 'react';
 import { ScaleIndicator } from '../primitives/ScaleIndicator';
 import { CanvasStack } from './CanvasStack';

package/src/canvas/index.ts

@@ -10,15 +10,6 @@ export { screenToWorld, worldToScreen } from './canvasCoords';
 export type { StageProps } from './Stage';
 export { fitStage, Stage } from './Stage';
 export type { CanvasLayerDescriptor } from './useLayerScheduler';
-export type { OrbitHandlers, OrbitView, UseOrbitOptions, Vec3 } from './useOrbit';
-export {
-  clampPitch,
-  orbitAfterDrag,
-  orbitAfterWheel,
-  PITCH_LIMIT,
-  useOrbit,
-  wrapYaw,
-} from './useOrbit';
 export type { PanZoomHandlers, UsePanZoomOptions } from './usePanZoom';
 export { usePanZoom } from './usePanZoom';
 export type { ViewportSize, WorldFrame, WorldSpec } from './worldSpec';

package/src/canvas/usePanZoom.test.ts

@@ -37,6 +37,34 @@ function setup(initialView: ViewTransform, options?: Partial<UsePanZoomOptions>)
 }
 
 describe('usePanZoom', () => {
+  it('stacks two wheel events that land before a re-render', () => {
+    const { wheel } = setup({ zoom: 1, pan: { x: 0, y: 0 } });
+    const once = wheel(-100).zoom;
+
+    const views: ViewTransform[] = [];
+    const { result } = renderHook(() =>
+      usePanZoom({ view: { zoom: 1, pan: { x: 0, y: 0 } }, onViewChange: (v) => views.push(v) }),
+    );
+    act(() => {
+      result.current.onWheel(wheelEvent(-100));
+      result.current.onWheel(wheelEvent(-100));
+    });
+    expect(views[1].zoom).toBeCloseTo(once * once, 10);
+  });
+
+  it('lets the view prop win at the next render', () => {
+    const views: ViewTransform[] = [];
+    const { result, rerender } = renderHook(
+      (props: { view: ViewTransform }) =>
+        usePanZoom({ view: props.view, onViewChange: (v) => views.push(v) }),
+      { initialProps: { view: { zoom: 1, pan: { x: 0, y: 0 } } } },
+    );
+    act(() => result.current.onWheel(wheelEvent(-100)));
+    rerender({ view: { zoom: 2, pan: { x: 0, y: 0 } } });
+    act(() => result.current.onWheel(wheelEvent(0)));
+    expect(views[1].zoom).toBeCloseTo(2, 10);
+  });
+
   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

package/src/canvas/usePanZoom.ts

@@ -70,6 +70,13 @@ export function usePanZoom({
   // view unreachable behind it.
   const initialZoomRef = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
 
+  // Written ahead of the render so a second event inside one commit steps
+  // from this one; the render-time assignment above still lets the prop win.
+  const commit = useCallback((next: ViewTransform) => {
+    viewRef.current = normalize2DView(next);
+    onViewChangeRef.current(next);
+  }, []);
+
   const onWheel = useCallback(
     (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => {
       const el = anchor ?? (e.currentTarget as Element | null);
@@ -77,7 +84,7 @@ export function usePanZoom({
       e.preventDefault();
       const rect = el.getBoundingClientRect();
       const initialZoom = initialZoomRef.current;
-      onViewChange(
+      commit(
         zoomAt(
           viewRef.current,
           Math.exp(-e.deltaY * 0.001),
@@ -90,7 +97,7 @@ export function usePanZoom({
         ),
       );
     },
-    [onViewChange, minZoom, maxZoom, frame],
+    [commit, minZoom, maxZoom, frame],
   );
 
   const clearDrag = useCallback(() => {
@@ -114,7 +121,7 @@ export function usePanZoom({
           const dy = ev.clientY - drag.startScreenY;
           if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
           drag.moved = true;
-          onViewChangeRef.current({
+          commit({
             zoom: viewRef.current.zoom,
             pan: { x: drag.startPan.x + dx, y: drag.startPan.y + dy },
           });
@@ -129,7 +136,7 @@ export function usePanZoom({
         onCancel: clearDrag,
       });
     },
-    [clearDrag],
+    [clearDrag, commit],
   );
 
   useEffect(() => () => sessionRef.current?.cancel(), []);

package/src/chrome/ChromeRegions.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { CrosshairIcon, HandIcon, PencilIcon, SnapshotIcon } from '@weasel-js/ui';
 import type { ConfigField } from '../controls/types';
 import type { Instrument } from '../instrument/types';

package/src/chrome/LabChrome.tsx

@@ -80,12 +80,10 @@ export function LabHeaderRegion({ contributions }: LabRegionProps) {
   );
 }
 
-/** The lab's sidebar sections. Fold state is a lab-scoped persisted value, so it
- *  survives a reload in a stored lab and lasts the session in an unstored one. */
-export function LabSidebarRegion({ contributions }: LabRegionProps) {
+function LabSections({ contributions, region }: LabRegionProps & { region: 'sidebar' | 'aside' }) {
   const lab = useLabChromeContext();
   const [collapsedSections, setFolds] = usePersistedState<Record<string, boolean>>(
-    'lk-lab-sidebar-folds',
+    `lk-lab-${region}-folds`,
     {},
     { scope: 'lab' },
   );
@@ -98,7 +96,25 @@ export function LabSidebarRegion({ contributions }: LabRegionProps) {
     }),
     [lab, collapsedSections, setFolds],
   );
-  return <SidebarRegion contributions={contributionsIn(contributions, 'sidebar')} ctx={ctx} />;
+  return (
+    <SidebarRegion
+      contributions={contributionsIn(contributions, region)}
+      ctx={ctx}
+      region={region}
+    />
+  );
+}
+
+/** The lab's sidebar sections. Fold state is a lab-scoped persisted value, so it
+ *  survives a reload in a stored lab and lasts the session in an unstored one. */
+export function LabSidebarRegion({ contributions }: LabRegionProps) {
+  return <LabSections contributions={contributions} region="sidebar" />;
+}
+
+/** The lab's aside sections, on the far side of the workspace from the sidebar.
+ *  Fold state persists the way the sidebar's does. */
+export function LabAsideRegion({ contributions }: LabRegionProps) {
+  return <LabSections contributions={contributions} region="aside" />;
 }
 
 /** The lab's readouts, in the shell footer below the workspace. */

package/src/chrome/builtins.test.ts

@@ -28,6 +28,7 @@ const ctx: TrialChromeContext = {
   configFields: [],
   configSchema: fromConfigFields([]),
   config: {},
+  auto: new Set<string>(),
   setConfig: () => {},
   savedSnapshots: [],
   saveSnapshot: () => {},

package/src/chrome/builtins.tsx

@@ -189,6 +189,7 @@ export function builtinContributions(
           <ControlPanel
             schema={ctx.configSchema}
             config={ctx.config as Record<string, unknown>}
+            auto={ctx.auto}
             setConfig={(key, value) => ctx.setConfig(String(key), value)}
             renderers={controls}
             collapsed={groupFolds(ctx.collapsedSections, 'settings')}

package/src/chrome/index.ts

@@ -2,6 +2,7 @@ export { builtinContributions } from './builtins';
 export type { LabRegionProps } from './LabChrome';
 export {
   contributionsIn,
+  LabAsideRegion,
   LabFooterRegion,
   LabHeaderRegion,
   LabSidebarRegion,

package/src/chrome/labTypes.ts

@@ -15,7 +15,7 @@ import type {
  * `<LabShell>` names them; `palette` is the tool rail down the side of the
  * workspace; `sidebar` is a column of sections left of the tool rail.
  */
-export type LabRegion = 'header' | 'palette' | 'sidebar' | 'footer';
+export type LabRegion = 'header' | 'palette' | 'sidebar' | 'aside' | 'footer';
 
 /**
  * Everything a lab-level contribution can read and command: the lab's own
@@ -40,8 +40,8 @@ export type LabContribution<TCtx = LabChromeContext> =
       item: ToolbarItem<TCtx>;
       render?: never;
     })
-  | (ContributionBase & { region: 'palette'; item: ToolItem; render?: never })
-  | (ContributionBase & { region: 'sidebar'; item: SidebarSection; render?: never })
+  | (ContributionBase & { region: 'palette'; item: ToolItem<TCtx>; render?: never })
+  | (ContributionBase & { region: 'sidebar' | 'aside'; item: SidebarSection; render?: never })
   | (ContributionBase & { region: 'footer'; item: StatusReadout; render?: never })
   | (ContributionBase & {
       region: LabRegion;

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -36,6 +36,24 @@ describe('PaletteRegion', () => {
     expect(setActiveTool).toHaveBeenCalledWith('brush');
   });
 
+  it('runs a command tool instead of selecting it, and never marks it current', () => {
+    const onActivate = vi.fn();
+    const setActiveTool = vi.fn();
+    const ctx = ctxWith('info', setActiveTool);
+    const info: RegionContribution<ToolSlotContext> = {
+      id: 'info',
+      region: 'palette',
+      item: { icon: Glyph, label: 'Info', onActivate },
+    };
+    render(<PaletteRegion contributions={[info]} ctx={ctx} />);
+    const button = screen.getByRole('button', { name: 'Info' });
+    button.click();
+    expect(onActivate).toHaveBeenCalledWith(ctx);
+    expect(setActiveTool).not.toHaveBeenCalled();
+    // The slot names this id, and a command still must not read as held down.
+    expect(button).not.toHaveAttribute('aria-current');
+  });
+
   it('puts exactly one tool in the tab order', () => {
     render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
     expect(screen.getByRole('button', { name: 'brush' })).toHaveAttribute('tabindex', '0');

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,11 +1,6 @@
 import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
 import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
-import type {
-  RegionContribution,
-  ToolItem,
-  ToolSlotContext,
-  TrialChromeContext,
-} from '../types';
+import type { RegionContribution, ToolItem, ToolSlotContext, TrialChromeContext } from '../types';
 
 /** Props for `<PaletteRegion>`. */
 export interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext> {
@@ -17,7 +12,8 @@ export interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeCo
 }
 
 /** A tool strip: a trial's, or the lab's. Selection lives in whichever tool
- *  slot the context carries; this region only reflects it. */
+ *  slot the context carries; this region only reflects it. An item carrying
+ *  `onActivate` is a command instead — it presses, and never latches. */
 export function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>({
   contributions,
   ctx,
@@ -38,16 +34,16 @@ export function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>
         {contributions.map((c) => {
           if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
           if (c.region !== region || !c.item) return null;
-          const { icon: Icon, label, shortcut, disabled } = c.item as ToolItem;
+          const { icon: Icon, label, shortcut, disabled, onActivate } = c.item as ToolItem<TCtx>;
           return (
             <ToolButton
               key={c.id}
               icon={<Icon size={16} />}
               label={label}
               shortcut={shortcut}
-              active={ctx.activeToolId === c.id}
+              active={onActivate ? false : ctx.activeToolId === c.id}
               disabled={disabled}
-              onClick={() => ctx.setActiveTool(c.id)}
+              onClick={onActivate ? () => onActivate(ctx) : () => ctx.setActiveTool(c.id)}
             />
           );
         })}

package/src/chrome/regions/SidebarRegion.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { expect } from '@weasel-js/forge/play';
+import { LabRoot } from '../../lab/LabRoot';
+import type { SidebarSlotContext } from '../types';
+import { SidebarRegion } from './SidebarRegion';
+
+const meta: Meta<typeof SidebarRegion> = {
+  title: 'labkit/Chrome/SidebarRegion',
+  component: SidebarRegion,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof SidebarRegion>;
+
+const ctx: SidebarSlotContext = { collapsedSections: {}, setSectionCollapsed: () => {} };
+
+// jsdom has no layout, so this runs in the browser story projects.
+export const LastSectionFillsItsPane: Story = {
+  render: () => (
+    <LabRoot>
+      <div className="lk-lab__aside" data-testid="pane" style={{ height: 400 }}>
+        <SidebarRegion
+          ctx={ctx}
+          contributions={[
+            { id: 'first', region: 'sidebar', item: { title: 'First', body: <p>one</p> } },
+            { id: 'last', region: 'sidebar', item: { title: 'Last', body: <p>two</p> } },
+          ]}
+        />
+      </div>
+    </LabRoot>
+  ),
+  play: async ({ canvasElement }) => {
+    const pane = canvasElement.querySelector('[data-testid="pane"]') as HTMLElement;
+    const sections = [...pane.querySelectorAll<HTMLElement>('.lk-sidebar-section')];
+    const first = sections[0] as HTMLElement;
+    const last = sections[sections.length - 1] as HTMLElement;
+    await expect(Math.round(last.getBoundingClientRect().bottom)).toBe(
+      Math.round(pane.getBoundingClientRect().bottom),
+    );
+    await expect(getComputedStyle(last).borderBottomWidth).toBe('0px');
+    await expect(getComputedStyle(first).borderBottomWidth).not.toBe('0px');
+  },
+};

package/src/chrome/regions/TitleBarRegion.tsx

@@ -32,7 +32,7 @@ function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
       onPointerDown={(e) => e.stopPropagation()}
       onMouseDown={(e) => e.stopPropagation()}
     >
-      <Icon size={14} />
+      <Icon size={16} />
     </button>
   );
 }

package/src/chrome/regions/ToolbarRegion.tsx

@@ -39,15 +39,19 @@ function groupsOf<TCtx>(contributions: readonly RegionContribution<TCtx>[]): Gro
   return groups;
 }
 
-function renderEntry<TCtx>(
-  c: RegionContribution<TCtx>,
-  ctx: TCtx,
-  region: string,
-): ReactNode {
+function renderEntry<TCtx>(c: RegionContribution<TCtx>, ctx: TCtx, region: string): ReactNode {
   if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
   if (c.region !== region || !c.item) return null;
-  const { icon: Icon, label, shortcut, disabled, danger, showLabel, pressed, onActivate } =
-    c.item as ToolbarItem<TCtx>;
+  const {
+    icon: Icon,
+    label,
+    shortcut,
+    disabled,
+    danger,
+    showLabel,
+    pressed,
+    onActivate,
+  } = c.item as ToolbarItem<TCtx>;
   return (
     <Toolbar.Button
       key={c.id}

package/src/chrome/types.ts

@@ -31,12 +31,18 @@ export interface ToolbarItem<TCtx = TrialChromeContext> {
   onActivate: (ctx: TCtx) => void;
 }
 
-/** A selectable tool in the palette region. */
-export interface ToolItem {
+/** A tool in the palette region: a mode by default, a command when it carries
+ *  an `onActivate`. `TCtx` is the chrome context that handler is handed — a
+ *  trial's, or the lab's for a lab-level rail. */
+export interface ToolItem<TCtx = TrialChromeContext> {
   icon: IconComponent;
   label: string;
+  /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
   shortcut?: string;
   disabled?: boolean;
+  /** Runs on press instead of selecting. An item with one is a command: it
+   *  never writes the tool slot, and never reads as the current tool. */
+  onActivate?: (ctx: TCtx) => void;
 }
 
 /** A titled block in the sidebar. */
@@ -165,6 +171,9 @@ export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext
    *  `config`, since a builder schema has no `ConfigField[]` form. */
   configFields: ConfigField[];
   config: unknown;
+  /** The trial's unpinned paths. `config` stays raw, so a control drawn from
+   *  it sits at the value un-pinning writes back. */
+  auto: ReadonlySet<string>;
   setConfig: (key: string, value: unknown) => void;
 
   /** Which of this trial's collapsible sections are folded. A sidebar

package/src/config/auto.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { auto, isAuto } from './auto';
+
+describe('auto', () => {
+  it('is a symbol distinct from every ordinary config value', () => {
+    expect(typeof auto).toBe('symbol');
+    expect(isAuto(auto)).toBe(true);
+    for (const v of [undefined, null, 0, '', 'auto', false, Symbol('auto'), {}]) {
+      expect(isAuto(v)).toBe(false);
+    }
+  });
+});

package/src/config/auto.ts

@@ -0,0 +1,15 @@
+/**
+ * Written at a config path to mean "do not pin this — let the instrument
+ * decide". Accepted by `setConfig`, by a trial's `configSeed`, and by
+ * `.initial()` in a schema. It is normalized into the trial's set of unpinned
+ * paths on the way into the store and is never itself stored, so a serialized
+ * trial contains no sentinel and the last pinned value survives.
+ */
+export const auto: unique symbol = Symbol('weasel.auto');
+
+/** The type of the `auto` sentinel, for widening a value parameter. */
+export type Auto = typeof auto;
+
+export function isAuto(value: unknown): value is Auto {
+  return value === auto;
+}