@weasel-js/labkit 1.5.0 → 1.5.1

package/src/lab/LabShell.less

@@ -39,12 +39,24 @@
 .lk-shell-header-actions {
   margin-left: auto;
   display: flex;
-  // A flex container reports its first item's baseline, so this is what
-  // carries the row's baseline up to the header.
-  align-items: baseline;
+  // Every control here runs at the one control height and shares a middle.
+  // The row still hands the header its first item's baseline, which is what
+  // lines the controls' labels up with the title.
+  align-items: center;
   gap: var(--wzl-space-sm);
 }
 
+// A toolbar dropped into the header is a run of header controls, not a strip of
+// its own: it takes the header's control height rather than the compact one
+// trial toolbars use, and none of the strip's box.
+.lk-shell-header-actions .lk-toolbar {
+  --wzl-control-h: inherit;
+  min-height: 0;
+  padding: 0;
+  background: none;
+  border: 0;
+}
+
 .lk-shell-body {
   display: flex;
   flex-direction: column;
@@ -81,6 +93,15 @@
   border-right: 1px solid var(--wzl-border);
 }
 
+.lk-lab__aside {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow-y: auto;
+  background: var(--wzl-surface);
+  border-left: 1px solid var(--wzl-border);
+}
+
 .lk-lab__main {
   display: flex;
   min-width: 0;

package/src/lab/LabShell.stories.tsx

@@ -1,4 +1,7 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { expect, within } from '@weasel-js/forge/play';
+import { Select, ToggleBar } from '../passthrough/weasel-ui';
+import { Toolbar } from '../primitives/Toolbar';
 import { LabShell } from './LabShell';
 
 const meta: Meta<typeof LabShell> = {
@@ -37,3 +40,49 @@ export const WithFooter: Story = {
     footer: <span>Status: ready</span>,
   },
 };
+
+// jsdom has no layout, so this runs in the browser story projects.
+export const HeaderControlsLineUp: Story = {
+  args: {
+    title: 'My Lab',
+    header: (
+      <>
+        <button type="button">Add</button>
+        <ToggleBar
+          ariaLabel="Mode"
+          items={[
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B' },
+          ]}
+          value="a"
+          onChange={() => {}}
+        />
+        <Select
+          aria-label="Font"
+          width="fit"
+          selectedKey="oswald"
+          options={[{ value: 'oswald', label: 'Oswald' }]}
+        />
+        <Toolbar aria-label="Actions">
+          <Toolbar.Group>
+            <Toolbar.Button onClick={() => {}}>Undo</Toolbar.Button>
+          </Toolbar.Group>
+        </Toolbar>
+      </>
+    ),
+    children: <p>Body content.</p>,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const boxes = [
+      canvas.getByRole('button', { name: 'Add' }),
+      canvas.getByRole('radiogroup', { name: 'Mode' }),
+      canvas.getByRole('button', { name: /Font/ }),
+      canvas.getByRole('button', { name: 'Undo' }),
+    ].map((el) => el.getBoundingClientRect());
+    const heights = boxes.map((box) => Math.round(box.height * 2) / 2);
+    const middles = boxes.map((box) => Math.round((box.top + box.height / 2) * 2) / 2);
+    await expect(heights).toEqual(heights.map(() => heights[0]));
+    await expect(middles).toEqual(middles.map(() => middles[0]));
+  },
+};

package/src/lab/LabShell.tsx

@@ -1,10 +1,8 @@
-import { ThemeProvider, useThemeOptional } from '@weasel-js/theme/react';
 import type { ReactNode } from 'react';
 import type { LabMode } from '../state/types';
-import { interstellarTheme } from '../theme/interstellar';
+import { LabRoot } from './LabRoot';
 import type { LabPage } from './LabSwitcher';
 import { LabSwitcher } from './LabSwitcher';
-import { useResolvedMode } from './useSystemMode';
 
 /** Props for `<LabShell>`. */
 export interface LabShellProps {
@@ -27,34 +25,27 @@ export interface LabShellProps {
 /** Page frame for a lab: a titled header, a body, and an optional footer,
  *  themed for the resolved color mode. Presentational only — use `<Lab>` when
  *  the trial runtime is wanted too. */
-export function LabShell({ title, children, header, footer, mode = 'auto',
-                          pages, path }: LabShellProps) {
-  const resolved = useResolvedMode(mode);
-  const outer = useThemeOptional();
-
-  const shell = (
-    // Overlays portal here rather than to the themed wrapper above: `.lk-root`
-    // carries the element defaults a lab's bare markup is styled by.
-    <div className="lk-root lk-shell" data-wzl-portal-host="">
+export function LabShell({
+  title,
+  children,
+  header,
+  footer,
+  mode = 'auto',
+  pages,
+  path,
+}: LabShellProps) {
+  return (
+    <LabRoot mode={mode} className="lk-shell">
       <header className="lk-shell-header">
-        {pages && pages.length > 0
-          ? <LabSwitcher title={title} pages={pages} path={path}
-                         className="lk-shell-title" />
-          : <h1 className="lk-shell-title">{title}</h1>}
+        {pages && pages.length > 0 ? (
+          <LabSwitcher title={title} pages={pages} path={path} className="lk-shell-title" />
+        ) : (
+          <h1 className="lk-shell-title">{title}</h1>
+        )}
         {header && <div className="lk-shell-header-actions">{header}</div>}
       </header>
       <main className="lk-shell-body">{children}</main>
       {footer && <footer className="lk-shell-footer">{footer}</footer>}
-    </div>
-  );
-
-  // Inside <Lab> the theme is already applied on `.lk-lab`; wrapping again
-  // would only add a div.
-  return outer ? (
-    shell
-  ) : (
-    <ThemeProvider theme={interstellarTheme} mode={resolved}>
-      {shell}
-    </ThemeProvider>
+    </LabRoot>
   );
 }

package/src/lab/LabSwitcher.less

@@ -6,7 +6,7 @@
 .lk-switcher-title {
   margin: 0;
   font-size: var(--wzl-font-size-xl);
-  line-height: var(--wzl-line-height-tight, 1.2);
+  line-height: var(--wzl-leading-snug);
 }
 
 .lk-switcher-trigger {
@@ -26,12 +26,12 @@
   // hyphen and the control becomes three ragged lines with a caret adrift.
   white-space: nowrap;
 
-  &:hover { color: var(--wzl-text-accent, var(--wzl-text)); }
+  &:hover { color: var(--wzl-accent); }
 
   &:focus-visible {
     outline: 2px solid var(--wzl-focus-ring, currentColor);
     outline-offset: 2px;
-    border-radius: var(--wzl-radius-sm, 2px);
+    border-radius: var(--wzl-radius-sm, 3px);
   }
 }
 
@@ -54,7 +54,7 @@
   position: absolute;
   top: calc(100% + var(--wzl-space-xs));
   left: 0;
-  z-index: var(--wzl-z-popover, 60);
+  z-index: var(--wzl-z-overlay);
   min-width: max(100%, 11rem);
   display: flex;
   flex-direction: column;
@@ -64,15 +64,15 @@
   // surface, the way `FloatingPanel` does.
   background: var(--wzl-surface);
   border: 1px solid var(--wzl-border);
-  border-radius: var(--wzl-radius-md, 6px);
-  box-shadow: var(--wzl-shadow-md, 0 6px 20px rgb(0 0 0 / 35%));
+  border-radius: var(--wzl-radius-md, 5px);
+  box-shadow: 0 6px 20px var(--wzl-shadow);
 }
 
 .lk-switcher-item {
   padding: var(--wzl-space-xs) var(--wzl-space-sm);
   border-radius: var(--wzl-radius-sm, 3px);
-  color: var(--wzl-text);
-  font-size: var(--wzl-font-size-md);
+  color: var(--wzl-fg);
+  font-size: var(--wzl-font-size);
   text-decoration: none;
   white-space: nowrap;
 
@@ -87,6 +87,6 @@
 // The open page stays in the list rather than being filtered out: a menu that
 // drops its current entry shifts every other one as you move between pages.
 .lk-switcher-item[aria-current='page'] {
-  color: var(--wzl-text-strong, var(--wzl-text));
-  font-weight: var(--wzl-font-weight-semibold, 600);
+  color: var(--wzl-fg);
+  font-weight: var(--wzl-font-weight-bold);
 }

package/src/lab/LabSwitcher.test.tsx

@@ -1,7 +1,7 @@
 import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it } from 'vitest';
-import { currentPage, LabSwitcher } from './LabSwitcher';
 import { LabShell } from './LabShell';
+import { currentPage, LabSwitcher } from './LabSwitcher';
 
 const PAGES = [
   { href: '/corpus', label: 'Wall' },
@@ -19,8 +19,7 @@ describe('currentPage', () => {
   it('survives a query string, a trailing slash and a leftover extension', () => {
     // A dev server maps `/stats` to `stats.html` and serves both spellings, so
     // an old bookmark must still resolve to the same page.
-    for (const path of ['/stats?kind=base', '/stats/', '/stats.html',
-                        '/lab/stats.html#top']) {
+    for (const path of ['/stats?kind=base', '/stats/', '/stats.html', '/lab/stats.html#top']) {
       expect(currentPage(path, PAGES)).toBe(1);
     }
   });
@@ -34,7 +33,9 @@ describe('<LabSwitcher>', () => {
   it('shows the title and nothing else until it is opened', () => {
     render(<LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />);
     expect(screen.getByRole('button', { name: /corpus stats/ })).toHaveAttribute(
-      'aria-expanded', 'false');
+      'aria-expanded',
+      'false',
+    );
     expect(screen.queryByRole('menu')).toBeNull();
   });
 
@@ -54,8 +55,7 @@ describe('<LabSwitcher>', () => {
     render(<LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />);
     open();
     expect(screen.getByRole('menuitem', { name: 'Wall' }).tagName).toBe('A');
-    expect(screen.getByRole('menuitem', { name: 'Wall' })).toHaveAttribute(
-      'href', '/corpus');
+    expect(screen.getByRole('menuitem', { name: 'Wall' })).toHaveAttribute('href', '/corpus');
   });
 
   it('closes on Escape and on a press outside it', () => {
@@ -63,7 +63,8 @@ describe('<LabSwitcher>', () => {
       <div>
         <LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />
         <button type="button">elsewhere</button>
-      </div>);
+      </div>,
+    );
     open();
     fireEvent.keyDown(document, { key: 'Escape' });
     expect(screen.queryByRole('menu')).toBeNull();
@@ -76,7 +77,7 @@ describe('<LabSwitcher>', () => {
   it('stays a plain heading when there is nowhere to switch to', () => {
     // A disclosure arrow promising a menu of the page you are already on is
     // worse than no control.
-    render(<LabSwitcher title="corpus stats" pages={[PAGES[1]!]} path="/stats" />);
+    render(<LabSwitcher title="corpus stats" pages={PAGES.slice(1, 2)} path="/stats" />);
     expect(screen.getByRole('heading', { name: 'corpus stats' })).toBeInTheDocument();
     expect(screen.queryByRole('button')).toBeNull();
   });
@@ -84,7 +85,11 @@ describe('<LabSwitcher>', () => {
 
 describe('<LabShell> with pages', () => {
   it('turns its title into the switcher', () => {
-    render(<LabShell title="corpus stats" pages={PAGES} path="/stats">body</LabShell>);
+    render(
+      <LabShell title="corpus stats" pages={PAGES} path="/stats">
+        body
+      </LabShell>,
+    );
     expect(screen.getByRole('button', { name: /corpus stats/ })).toBeInTheDocument();
   });
 

package/src/lab/LabSwitcher.tsx

@@ -25,8 +25,10 @@ export interface LabSwitcherProps {
  *  to `stats.html` serves both spellings, and a bookmark from before the URLs
  *  lost their extension still resolves to the same page. */
 export function currentPage(path: string, pages: readonly LabPage[]): number {
-  const here = path.split('?')[0]!.split('#')[0]!
-    .replace(/\/$/, '').replace(/\.html$/, '');
+  const here = path
+    .replace(/[?#].*$/, '')
+    .replace(/\/$/, '')
+    .replace(/\.html$/, '');
   return pages.findIndex((p) => here.endsWith(p.href.replace(/\.html$/, '')));
 }
 
@@ -44,8 +46,10 @@ export function LabSwitcher({ title, pages, path, className }: LabSwitcherProps)
   const [open, setOpen] = useState(false);
   const root = useRef<HTMLDivElement>(null);
   const menuId = useId();
-  const here = currentPage(path ?? (typeof window === 'undefined'
-    ? '' : window.location.pathname), pages);
+  const here = currentPage(
+    path ?? (typeof window === 'undefined' ? '' : window.location.pathname),
+    pages,
+  );
 
   const close = useCallback(() => setOpen(false), []);
 

package/src/lab/Workspace.less

@@ -80,5 +80,5 @@
   width: 260px;
   height: auto;
   max-height: 60%;
-  box-shadow: var(--wzl-shadow-panel, 0 2px 8px rgb(0 0 0 / 0.3));
+  box-shadow: 0 2px 8px var(--wzl-shadow);
 }

package/src/lab/Workspace.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { Workspace } from './Workspace';
 
 const meta: Meta<typeof Workspace> = {

package/src/lab/Workspace.surface.test.tsx

@@ -11,7 +11,7 @@ function fakeHandle(): SurfaceHandle {
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
     registerClear: vi.fn(() => () => {}),
-  registerPainter: vi.fn(() => () => {}),
+    registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),
   };

package/src/lab/index.ts

@@ -4,6 +4,8 @@ export type { LabContextValue } from './LabContext';
 export { LabContext, useLabContext } from './LabContext';
 export type { LabPaletteProps } from './LabPalette';
 export { LabPalette } from './LabPalette';
+export type { LabRootProps } from './LabRoot';
+export { LabRoot } from './LabRoot';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
 export type { LabPage, LabSwitcherProps } from './LabSwitcher';

package/src/layers/LayerList.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 { LayerList, type LayerTreeNode } from './LayerList';
 

package/src/loupe/AGENTS.md

@@ -12,7 +12,9 @@ This directory binds that model to a labkit trial and draws it.
 | File | Role |
 |---|---|
 | `types.ts` | `LoupeCapability`, and `resolveLoupe` filling in every default |
-| `useLoupe.ts` | The model over a host element, plus all of the input |
+| `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 the dispatcher on the host |
 | `TrialLoupe.tsx` | Picks the painter and mounts the lens |
 | `LoupeBubble.tsx` | The circular clip, positioned on the aim |
 | `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
@@ -44,6 +46,16 @@ StrictMode mounts / unmounts / mounts every effect — so disposing in the
 cleanup leaves a magnifier that draws but silently ignores every aim. It owns
 no resources; unmounting only reports the lens gone.
 
-**The wheel has to be taken from pan/zoom by hand.** `usePanZoom` is a React
-handler on the same element, so the lens listens in the capture phase and stops
-propagation. See the loupe entry in `docs/TODO.md` for what replaces this.
+**The wheel is taken from pan/zoom by declining it, not by capturing it.**
+`loupe.magnify`'s `enabled` returns a disabled reason while the lens is down, so
+the dispatcher leaves the event unhandled and `usePanZoom` — a React handler on
+the same element — sees it as usual. While the lens is up the action fires, the
+dispatcher stops propagation, and React's root listener never runs.
+
+**Aiming is a plain listener because a hover is not a gesture.**
+`GESTURE_DESCRIPTORS` names no continuous-motion gesture, so `pointermove` /
+`pointerleave` stay hand-attached in `useLoupe`. Everything else routes.
+
+**`<LoupeGestures>` mounts outside the visibility gate.** Hold-to-peek is what
+raises a lens that is down; gate its registration on `loupe.visible` and the
+peek key stops working entirely.

package/src/loupe/LoupeGestures.tsx

@@ -0,0 +1,67 @@
+/**
+ * Mounts the gesture dispatcher on a loupe's host and registers the loupe's
+ * actions on it, so the peek key and the wheel route the way every other
+ * weasel binding does.
+ *
+ * Three of the dispatcher's four element channels are off. Only `wheel` is
+ * wanted here; `contextMenu` suppresses the native menu unconditionally and
+ * `ingest` makes the host a file-drop target, neither of which a lab asked
+ * for by turning a magnifier on.
+ */
+import {
+  type ActionsRegistry,
+  type Tool,
+  useActionsRegistry,
+  useGestureDispatcher,
+} from '@weasel-js/core';
+import { type RefObject, useEffect, useMemo } from 'react';
+import { createLoupeActions, type LoupeInputApi } from './loupeActions';
+
+/** Props for `<LoupeGestures>`. */
+export interface LoupeGesturesProps {
+  /** The element the dispatcher listens on — the same one the lens tracks. */
+  hostRef: RefObject<HTMLElement | null>;
+  input: LoupeInputApi;
+  /** `KeyboardEvent.key` for hold-to-peek, or `null` for no peek binding. */
+  peekKey: string | null;
+}
+
+const NO_TOOLS: ReadonlyMap<string, Tool> = new Map();
+
+const CHANNELS = { pointer: false, contextMenu: false, ingest: false } as const;
+
+function LoupeDispatch({
+  hostRef,
+  input,
+  peekKey,
+  registry,
+}: LoupeGesturesProps & { registry: ActionsRegistry }) {
+  const actions = useMemo(() => createLoupeActions(input, peekKey), [input, peekKey]);
+
+  useEffect(() => {
+    const offs = actions.map((a) => registry.register(a));
+    return () => {
+      for (const off of offs) off();
+    };
+  }, [registry, actions]);
+
+  useGestureDispatcher({
+    canvasRef: hostRef,
+    actions: registry,
+    toolsById: NO_TOOLS,
+    channels: CHANNELS,
+  });
+
+  return null;
+}
+
+/**
+ * The loupe's input, routed. Render it inside a `<WeaselProvider isolate>` —
+ * with no registry in scope it renders nothing rather than registering
+ * actions that could never fire.
+ */
+export function LoupeGestures(props: LoupeGesturesProps) {
+  const registry = useActionsRegistry();
+  if (!registry) return null;
+  return <LoupeDispatch {...props} registry={registry} />;
+}

package/src/loupe/TrialLoupe.tsx

@@ -1,3 +1,4 @@
+import { WeaselProvider } from '@weasel-js/core';
 import { type RefObject, useContext, useMemo } from 'react';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 import type { WorldSpec } from '../canvas/worldSpec';
@@ -6,6 +7,7 @@ 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 { useHostSize } from './useHostSize';
 import { useLoupe } from './useLoupe';
@@ -59,35 +61,48 @@ export function TrialLoupe({
   const measured = useHostSize(host);
   const size = surface?.size ?? measured;
 
-  if (!loupe.visible) return null;
+  // The gestures mount outside the visibility gate: hold-to-peek is what
+  // raises a lens that is down, so its binding has to be live while it is.
+  // One isolated scope per loupe, for the reason `<AnnotationOverlay>` gives
+  // — an actions registry holds one dispatcher.
+  const gestures = (
+    <WeaselProvider isolate>
+      <LoupeGestures hostRef={host} input={loupe.input} peekKey={capability.peekKey ?? null} />
+    </WeaselProvider>
+  );
+
+  if (!loupe.visible) return gestures;
 
   return (
-    <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>
+    <>
+      {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>
+    </>
   );
 }

package/src/loupe/index.ts

@@ -6,6 +6,10 @@ export type { DomLoupeProps } from './DomLoupe';
 export { DomLoupe } from './DomLoupe';
 export type { LoupeBubbleProps } from './LoupeBubble';
 export { LoupeBubble } from './LoupeBubble';
+export type { LoupeGesturesProps } from './LoupeGestures';
+export { LoupeGestures } from './LoupeGestures';
+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 {

package/src/loupe/loupeActions.ts

@@ -0,0 +1,98 @@
+/**
+ * The loupe's two bindable interactions, as `Action` descriptors the gesture
+ * dispatcher routes: hold a key to peek, and walk the magnification with the
+ * wheel.
+ *
+ * Free of React so the routing can be tested without a DOM.
+ */
+import type { Action } from '@weasel-js/core';
+
+/** Canonical id of the hold-to-peek action. */
+export const LOUPE_PEEK_ID = 'loupe.peek';
+/** Canonical id of the wheel-magnify action. */
+export const LOUPE_MAGNIFY_ID = 'loupe.magnify';
+
+/** How fast the wheel walks the magnification. Gentler than the pan-zoom
+ *  wheel: the lens' whole range is one order of magnitude. */
+export const WHEEL_RATE = 0.002;
+
+/** What the actions do to a live loupe. Every member is read through the
+ *  object on each invocation, so one stable instance serves the life of the
+ *  registration. */
+export interface LoupeInputApi {
+  /** Whether the lens is up. The wheel belongs to the loupe only while it is;
+   *  otherwise `loupe.magnify` declines and the dispatcher leaves the event
+   *  unhandled, which is what hands it back to the lab's own pan/zoom. */
+  shown: () => boolean;
+  /** Raise or drop the hold-to-peek flag. */
+  setPeeking: (on: boolean) => void;
+  /** Multiply the magnification by one wheel notch of `deltaY`. */
+  magnifyBy: (deltaY: number) => void;
+}
+
+/**
+ * Build the loupe's actions. `peekKey` is a `KeyboardEvent.key`; passing
+ * `null` omits `loupe.peek` entirely rather than registering a binding no key
+ * can match.
+ */
+export function createLoupeActions(
+  input: LoupeInputApi,
+  peekKey: string | null,
+): readonly Action[] {
+  const magnify: Action = {
+    id: LOUPE_MAGNIFY_ID,
+    label: 'Magnify (loupe)',
+    group: 'loupe',
+    // Every modifier optional: the lens claims the wheel whenever it is up,
+    // which is what the hand-rolled capture-phase listener did. A bare spec
+    // would forbid modifiers and hand Cmd+wheel back to the lab mid-peek.
+    defaultBinding: [
+      {
+        spec: {
+          kind: 'wheel',
+          mods: { alt: 'optional', ctrl: 'optional', meta: 'optional', shift: 'optional' },
+        },
+        opts: {},
+      },
+    ],
+    enabled: () => (input.shown() ? true : 'not-applicable'),
+    invoker: {
+      timing: 'immediate',
+      run(_deps, params) {
+        input.magnifyBy((params?.deltaY as number | undefined) ?? 0);
+      },
+    },
+  };
+
+  if (peekKey === null) return [magnify];
+
+  const peek: Action = {
+    id: LOUPE_PEEK_ID,
+    label: 'Peek (loupe)',
+    group: 'loupe',
+    // Hotkey scope: peeking must beat whatever the lab's active tool binds to
+    // the same key, the way every other held-key trigger does.
+    scope: 'hotkey',
+    // Every modifier optional because the peek key may BE one: the keydown
+    // that carries `Alt` — the default — also reports `altKey: true`, and the
+    // matcher forbids any modifier a spec does not name.
+    defaultBinding: [
+      {
+        spec: {
+          kind: 'key-held',
+          key: peekKey,
+          mods: { alt: 'optional', ctrl: 'optional', meta: 'optional', shift: 'optional' },
+        },
+        opts: {},
+      },
+    ],
+    invoker: {
+      timing: 'ongoing',
+      start() {
+        input.setPeeking(true);
+        return { onEnd: () => input.setPeeking(false) };
+      },
+    },
+  };
+  return [peek, magnify];
+}