@weasel-js/labkit 1.4.4 → 1.5.0

package/src/canvas/CanvasStack.tsx

@@ -1,5 +1,15 @@
-import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type CSSProperties,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import type { Point, ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
+import { CameraWheelContext } from './CameraWheelContext';
 import { CanvasStackContext } from './CanvasStackContext';
 import { screenToWorld } from './canvasCoords';
 import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
@@ -31,7 +41,7 @@ export interface CanvasStackProps {
  *  Handles sizing, device pixel ratio, and pan/zoom. */
 export function CanvasStack({
   layers,
-  view,
+  view: viewProp,
   onViewChange,
   worldSpec,
   minZoom,
@@ -43,6 +53,7 @@ export function CanvasStack({
   onHitTest,
   children,
 }: CanvasStackProps) {
+  const view = normalize2DView(viewProp);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const canvasMap = useRef<Map<string, HTMLCanvasElement>>(new Map());
   const [size, setSize] = useState({ width: 0, height: 0, dpr: 1 });
@@ -88,7 +99,24 @@ export function CanvasStack({
     onHitTest(screenToWorld({ x: e.clientX - rect.left, y: e.clientY - rect.top }, view, frame));
   };
 
-  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, onTap });
+  const handlers = usePanZoom({ view: viewProp, onViewChange, minZoom, maxZoom, frame, onTap });
+  const onWheelRef = useRef(handlers.onWheel);
+  onWheelRef.current = handlers.onWheel;
+  const wheelSlot = useContext(CameraWheelContext);
+
+  // Bound by hand because React registers wheel listeners passive, where
+  // `preventDefault` is refused and the page scrolls under the zoom.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const wheel = (e: WheelEvent): void => onWheelRef.current(e, el);
+    el.addEventListener('wheel', wheel, { passive: false });
+    if (wheelSlot) wheelSlot.current = wheel;
+    return () => {
+      el.removeEventListener('wheel', wheel);
+      if (wheelSlot?.current === wheel) wheelSlot.current = null;
+    };
+  }, [wheelSlot]);
   useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
 
   const ctxValue = useMemo(
@@ -116,7 +144,6 @@ export function CanvasStack({
         ref={containerRef}
         className={className ? `lk-canvas-stack ${className}` : 'lk-canvas-stack'}
         style={containerStyle}
-        onWheel={handlers.onWheel}
         onPointerDown={handlers.onPointerDown}
       >
         {layers.map((layer) => (

package/src/canvas/Stage.less

@@ -0,0 +1,18 @@
+.lk-stage {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: var(--wzl-surface-sunken);
+  touch-action: none;
+}
+
+.lk-stage__content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--lk-stage-w);
+  height: var(--lk-stage-h);
+  transform-origin: 0 0;
+  transform: translate(var(--lk-stage-x), var(--lk-stage-y)) scale(var(--lk-stage-zoom));
+}

package/src/canvas/Stage.test.tsx

@@ -0,0 +1,186 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { ViewTransform } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
+import { CameraWheelContext, type CameraWheelSlot } from './CameraWheelContext';
+import { fitStage, Stage } from './Stage';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function content(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('.lk-stage__content');
+  if (!el) throw new Error('no stage content');
+  return el;
+}
+
+const zoomOf = (el: HTMLElement): number => Number(el.style.getPropertyValue('--lk-stage-zoom'));
+
+describe('fitStage', () => {
+  it('shrinks content that does not fit, and centers it on the short axis', () => {
+    expect(fitStage({ width: 400, height: 200 }, { width: 200, height: 200 })).toEqual({
+      zoom: 0.5,
+      pan: { x: 0, y: 50 },
+    });
+  });
+
+  it('never enlarges content past its own size', () => {
+    expect(fitStage({ width: 100, height: 50 }, { width: 300, height: 150 })).toEqual({
+      zoom: 1,
+      pan: { x: 100, y: 50 },
+    });
+  });
+
+  it('answers the identity for an unmeasured viewport', () => {
+    expect(fitStage({ width: 100, height: 50 }, { width: 0, height: 0 })).toEqual({
+      zoom: 1,
+      pan: { x: 0, y: 0 },
+    });
+  });
+});
+
+describe('<Stage>', () => {
+  it('draws its content through the camera', () => {
+    const { container } = render(
+      <Stage
+        size={{ width: 300, height: 100 }}
+        view={{ zoom: 2, pan: { x: 10, y: 20 } }}
+        onViewChange={() => {}}
+      >
+        <div data-testid="art" />
+      </Stage>,
+    );
+    const el = content(container);
+    expect(el).toContainElement(screen.getByTestId('art'));
+    expect(zoomOf(el)).toBe(2);
+    expect(el.style.getPropertyValue('--lk-stage-x')).toBe('10px');
+    expect(el.style.getPropertyValue('--lk-stage-y')).toBe('20px');
+    expect(el.style.getPropertyValue('--lk-stage-w')).toBe('300px');
+    expect(el.style.getPropertyValue('--lk-stage-h')).toBe('100px');
+  });
+
+  it('zooms on the wheel', () => {
+    function Host() {
+      const [view, setView] = useState<ViewTransform>({ zoom: 1, pan: { x: 0, y: 0 } });
+      return (
+        <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={setView}>
+          <div />
+        </Stage>
+      );
+    }
+    const { container } = render(<Host />);
+    const host = container.querySelector('.lk-stage');
+    if (!host) throw new Error('no stage');
+    fireEvent.wheel(host, { deltaY: -200, clientX: 0, clientY: 0 });
+    expect(zoomOf(content(container))).toBeGreaterThan(1);
+  });
+
+  it('zooms on a wheel handed to its camera from outside the stage', () => {
+    // What an annotation target's input box does: it is portalled out of the
+    // stage, so its wheel never bubbles here.
+    const slot: CameraWheelSlot = { current: null };
+    function Host() {
+      const [view, setView] = useState<ViewTransform>({ zoom: 1, pan: { x: 0, y: 0 } });
+      return (
+        <CameraWheelContext.Provider value={slot}>
+          <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={setView}>
+            <div />
+          </Stage>
+        </CameraWheelContext.Provider>
+      );
+    }
+    const { container } = render(<Host />);
+    act(() => {
+      slot.current?.(new WheelEvent('wheel', { deltaY: -200, cancelable: true }));
+    });
+    expect(zoomOf(content(container))).toBeGreaterThan(1);
+  });
+
+  it('listens for the wheel actively, so it can keep the page from scrolling', () => {
+    // A proxy: jsdom does not enforce passive listeners, so a preventDefault in
+    // a passive one succeeds here and fails in a browser. React registers its
+    // wheel listeners passive; asserting the registration is what can fail.
+    const add = vi.spyOn(HTMLElement.prototype, 'addEventListener');
+    const { container } = render(
+      <Stage
+        size={{ width: 100, height: 100 }}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={() => {}}
+      >
+        <div />
+      </Stage>,
+    );
+    const host = container.querySelector('.lk-stage');
+    const wheel = add.mock.calls.filter(
+      (call, i) => call[0] === 'wheel' && add.mock.contexts[i] === host,
+    );
+    expect(wheel.map((call) => call[2])).toContainEqual(
+      expect.objectContaining({ passive: false }),
+    );
+    add.mockRestore();
+  });
+
+  it('tells the surface its tiles moved when the camera does', () => {
+    // A transform moves a tile without resizing anything, which is the one
+    // kind of move a ResizeObserver never reports.
+    const invalidateRects = vi.fn();
+    const surface = { invalidateRects } as unknown as SurfaceHandle;
+    const at = (view: ViewTransform) => (
+      <SurfaceContext.Provider value={surface}>
+        <Stage size={{ width: 100, height: 100 }} view={view} onViewChange={() => {}}>
+          <div />
+        </Stage>
+      </SurfaceContext.Provider>
+    );
+    const { rerender } = render(at({ zoom: 1, pan: { x: 0, y: 0 } }));
+    invalidateRects.mockClear();
+    rerender(at({ zoom: 1.5, pan: { x: 0, y: 0 } }));
+    expect(invalidateRects).toHaveBeenCalled();
+  });
+});
+
+const staged = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Staged',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="art" />,
+  stage: { size: { width: 240, height: 160 }, initialView: { zoom: 1, pan: { x: 0, y: 0 } } },
+});
+
+const plain = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Plain',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="art" />,
+});
+
+describe('an instrument that declares a stage', () => {
+  it('renders its DOM on the stage', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    expect(content(container)).toContainElement(screen.getByTestId('art'));
+  });
+
+  it('gets the zoom controls, and they move the stage', () => {
+    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }));
+    });
+    expect(zoomOf(content(container))).toBeCloseTo(1.25);
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Actual size' }));
+    });
+    expect(zoomOf(content(container))).toBe(1);
+  });
+
+  it('is what earns them: DOM content without one gets none', () => {
+    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+    expect(screen.queryByRole('button', { name: 'Zoom in' })).toBeNull();
+  });
+});

package/src/canvas/Stage.tsx

@@ -0,0 +1,134 @@
+import { type CSSProperties, type ReactNode, useContext, useEffect, useRef } from 'react';
+import type { ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
+import { useSurfaceOptional } from '../surface/useSurfaceTile';
+import { CameraWheelContext } from './CameraWheelContext';
+import { usePanZoom } from './usePanZoom';
+import type { ViewportSize } from './worldSpec';
+
+/** Props for `<Stage>`. */
+export interface StageProps {
+  /** The content's own size in CSS pixels, at zoom 1. */
+  size: ViewportSize;
+  view: ViewTransform;
+  onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;
+  maxZoom?: number;
+  /** Fired whenever the stage's viewport is measured at a non-zero size. */
+  onResize?: (viewport: ViewportSize) => void;
+  /** Handed the viewport element, for a consumer tracking the pointer over it. */
+  hostRef?: { current: HTMLDivElement | null };
+  /** Drawn over the content in viewport pixels, outside the camera. */
+  overlay?: ReactNode;
+  children?: ReactNode;
+}
+
+/**
+ * The camera a stage opens at: the content centered in its viewport, shrunk to
+ * fit if it has to be and never enlarged past its own size.
+ */
+export function fitStage(size: ViewportSize, viewport: ViewportSize): ViewTransform {
+  if (!(size.width > 0 && size.height > 0 && viewport.width > 0 && viewport.height > 0)) {
+    return { zoom: 1, pan: { x: 0, y: 0 } };
+  }
+  const zoom = Math.min(1, viewport.width / size.width, viewport.height / size.height);
+  return {
+    zoom,
+    pan: {
+      x: (viewport.width - size.width * zoom) / 2,
+      y: (viewport.height - size.height * zoom) / 2,
+    },
+  };
+}
+
+/**
+ * DOM content of a fixed size, panned and zoomed by a camera — what
+ * `<CanvasStack>` is for layers drawn to a canvas. The content is laid out at
+ * its own size and transformed, so everything inside keeps its layout and a
+ * measurement of any element in it reports where it is actually drawn.
+ */
+export function Stage({
+  size,
+  view: viewProp,
+  onViewChange,
+  minZoom,
+  maxZoom,
+  onResize,
+  hostRef,
+  overlay,
+  children,
+}: StageProps) {
+  const view = normalize2DView(viewProp);
+  const host = useRef<HTMLDivElement | null>(null);
+  const surface = useSurfaceOptional();
+  const handlers = usePanZoom({ view: viewProp, onViewChange, minZoom, maxZoom });
+  const onWheelRef = useRef(handlers.onWheel);
+  onWheelRef.current = handlers.onWheel;
+  const wheelSlot = useContext(CameraWheelContext);
+
+  // Bound by hand because React registers wheel listeners passive, where
+  // `preventDefault` is refused and the page scrolls under the zoom.
+  useEffect(() => {
+    const el = host.current;
+    if (!el) return;
+    const wheel = (e: WheelEvent): void => onWheelRef.current(e, el);
+    el.addEventListener('wheel', wheel, { passive: false });
+    if (wheelSlot) wheelSlot.current = wheel;
+    return () => {
+      el.removeEventListener('wheel', wheel);
+      if (wheelSlot?.current === wheel) wheelSlot.current = null;
+    };
+  }, [wheelSlot]);
+
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  useEffect(() => {
+    const el = host.current;
+    if (!el) return;
+    const measure = () => {
+      const rect = el.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        onResizeRef.current?.({ width: rect.width, height: rect.height });
+      }
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // A transform moves every tile inside the content without resizing anything,
+  // and a ResizeObserver reports only resizes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the camera is the trigger, not an input — the effect re-measures whenever it moves.
+  useEffect(() => {
+    surface?.invalidateRects();
+  }, [surface, view.zoom, view.pan.x, view.pan.y]);
+
+  // The camera changes every frame of a pan, and a transform has nowhere to
+  // live but the element's own style: set as custom properties the stylesheet
+  // reads.
+  const camera = {
+    ['--lk-stage-x' as string]: `${view.pan.x}px`,
+    ['--lk-stage-y' as string]: `${view.pan.y}px`,
+    ['--lk-stage-zoom' as string]: String(view.zoom),
+    ['--lk-stage-w' as string]: `${size.width}px`,
+    ['--lk-stage-h' as string]: `${size.height}px`,
+  } as CSSProperties;
+
+  return (
+    <div
+      ref={(el) => {
+        host.current = el;
+        if (hostRef) hostRef.current = el;
+      }}
+      className="lk-stage"
+      onPointerDown={handlers.onPointerDown}
+    >
+      <div className="lk-stage__content" style={camera}>
+        {children}
+      </div>
+      {overlay}
+    </div>
+  );
+}

package/src/canvas/camera.test.ts

@@ -41,11 +41,18 @@ describe('zoomAt', () => {
     expect(screenToWorld(at, next).x).toBeCloseTo(before.x, 10);
   });
 
-  it('treats a non-finite zoom as 1 rather than propagating NaN', () => {
+  it('keeps a view that arrived with a non-finite zoom finite', () => {
     const next = zoomAt({ zoom: Number.NaN, pan: { x: 0, y: 0 } }, 2, { x: 10, y: 10 });
-    expect(next.zoom).toBe(2);
+    expect(next.zoom > 0 && Number.isFinite(next.zoom)).toBe(true);
     expect(Number.isFinite(next.pan.x)).toBe(true);
   });
+
+  it('keeps the zoom positive when a factor and bound would drive it to 0', () => {
+    const at = { x: 10, y: 10 };
+    const next = zoomAt(view, 0, at, { min: 0 });
+    expect(next.zoom > 0 && Number.isFinite(next.zoom)).toBe(true);
+    expect(Number.isFinite(screenToWorld(at, next).x)).toBe(true);
+  });
 });
 
 describe('centerOn', () => {
@@ -76,3 +83,11 @@ describe('centerOn', () => {
     expect(centerOn({ x: 0, y: 0 }, 6, { width: 10, height: 10 }, DEFAULT_FRAME).zoom).toBe(6);
   });
 });
+
+describe('centerOn zoom invariant', () => {
+  it('builds a camera with a positive zoom from a zoom of 0', () => {
+    const v = centerOn({ x: 1, y: 1 }, 0, { width: 100, height: 100 });
+    expect(v.zoom > 0 && Number.isFinite(v.zoom)).toBe(true);
+    expect(Number.isFinite(screenToWorld({ x: 5, y: 5 }, v).x)).toBe(true);
+  });
+});

package/src/canvas/camera.ts

@@ -1,3 +1,4 @@
+import { normalizeZoom } from '@weasel-js/core';
 import type { Point, ViewTransform } from '../instrument/types';
 import { DEFAULT_FRAME, type ViewportSize, type WorldFrame } from './worldSpec';
 
@@ -10,10 +11,6 @@ export interface ZoomAtOptions {
   max?: number;
 }
 
-function usableZoom(zoom: number): number {
-  return Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
-}
-
 /**
  * Zoom a view by `factor` about a fixed point, so whatever world coordinate
  * `at` was over stays under it.
@@ -32,8 +29,10 @@ export function zoomAt(
   // drifts by `(1 - ratio) * originPx` per step on any frame that moves it.
   const anchorX = at.x - frame.originPx.x;
   const anchorY = at.y - frame.originPx.y;
-  const current = usableZoom(view.zoom);
-  const zoom = Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? 0, current * factor));
+  const current = normalizeZoom(view.zoom);
+  const zoom = normalizeZoom(
+    Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? 0, current * factor)),
+  );
   const ratio = zoom / current;
   return {
     zoom,
@@ -52,11 +51,12 @@ export function centerOn(
   size: ViewportSize,
   frame: WorldFrame = DEFAULT_FRAME,
 ): ViewTransform {
+  const z = normalizeZoom(zoom);
   return {
-    zoom,
+    zoom: z,
     pan: {
-      x: size.width / 2 - frame.originPx.x - world.x * zoom,
-      y: size.height / 2 - frame.originPx.y - world.y * zoom * frame.yDir,
+      x: size.width / 2 - frame.originPx.x - world.x * z,
+      y: size.height / 2 - frame.originPx.y - world.y * z * frame.yDir,
     },
   };
 }

package/src/canvas/index.ts

@@ -1,3 +1,5 @@
+export type { CameraWheelSlot } from './CameraWheelContext';
+export { CameraWheelContext } from './CameraWheelContext';
 export type { CanvasStackProps } from './CanvasStack';
 export { CanvasStack } from './CanvasStack';
 export type { CanvasStackContextValue, CanvasStackSurface } from './CanvasStackContext';
@@ -5,6 +7,8 @@ export { CanvasStackContext } from './CanvasStackContext';
 export type { ZoomAtOptions } from './camera';
 export { centerOn, zoomAt } from './camera';
 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 {

package/src/canvas/usePanZoom.ts

@@ -7,6 +7,7 @@ import {
   type WheelEvent,
 } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
 import { zoomAt } from './camera';
 import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 
@@ -28,7 +29,9 @@ export interface UsePanZoomOptions {
 }
 
 export interface PanZoomHandlers {
-  onWheel: (e: WheelEvent<HTMLElement>) => void;
+  /** Zoom about the pointer. `anchor` is the element the pointer position is
+   *  measured against, for an event whose `currentTarget` is some other box. */
+  onWheel: (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => void;
   onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
   isDragging: () => boolean;
 }
@@ -56,8 +59,8 @@ export function usePanZoom({
 }: UsePanZoomOptions): PanZoomHandlers {
   const dragRef = useRef<DragState | null>(null);
   const sessionRef = useRef<PointerSession | null>(null);
-  const viewRef = useRef(view);
-  viewRef.current = view;
+  const viewRef = useRef(normalize2DView(view));
+  viewRef.current = normalize2DView(view);
   const onViewChangeRef = useRef(onViewChange);
   onViewChangeRef.current = onViewChange;
   const onTapRef = useRef(onTap);
@@ -68,9 +71,11 @@ export function usePanZoom({
   const initialZoomRef = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
 
   const onWheel = useCallback(
-    (e: WheelEvent<HTMLElement>) => {
+    (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => {
+      const el = anchor ?? (e.currentTarget as Element | null);
+      if (!el) return;
       e.preventDefault();
-      const rect = e.currentTarget.getBoundingClientRect();
+      const rect = el.getBoundingClientRect();
       const initialZoom = initialZoomRef.current;
       onViewChange(
         zoomAt(

package/src/chrome/ChromeRegions.stories.tsx

@@ -76,7 +76,6 @@ export const EveryRegion: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Chrome Regions',
-    storage: null,
   },
 };
 
@@ -86,7 +85,6 @@ export const SuppressedAndReplaced: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Suppress + Replace',
-    storage: null,
     suppress: ['snapshot'],
     chrome: [
       {
@@ -116,7 +114,6 @@ export const SubjectTitleAndLead: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Title Bar Lead',
-    storage: null,
     suppress: ['snapshot'],
     chrome: [
       {

package/src/chrome/LabChrome.tsx

@@ -0,0 +1,114 @@
+import { useContext, useMemo } from 'react';
+import { useStore } from 'zustand/react';
+import { useLabContext } from '../lab/LabContext';
+import { LabStoreContext } from '../state/context';
+import { usePersistedState } from '../state/usePersistedState';
+import { resolveLabTool } from '../tools/labTool';
+import type { TrialTool } from '../tools/types';
+import type { LabChromeContext, LabContribution, LabRegion } from './labTypes';
+import { mergeContributions } from './merge';
+import { SidebarRegion } from './regions/SidebarRegion';
+import { StatusRegion } from './regions/StatusRegion';
+import { ToolbarRegion } from './regions/ToolbarRegion';
+
+/** The lab's chrome context: the lab itself, plus the lab's tool slot. Throws
+ *  outside a `<Lab>`. */
+export function useLabChromeContext(): LabChromeContext {
+  const lab = useLabContext();
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] lab chrome requires <LabStoreProvider>');
+  const slot = useStore(storeCtx.store, (s) => s.activeToolId);
+  const storeInstruments = useStore(storeCtx.store, (s) => s.instruments);
+  const activeToolId = resolveLabTool(slot, storeInstruments ?? lab.instruments);
+  const setLabTool = useStore(storeCtx.store, (s) => s.setLabTool);
+  return useMemo(
+    () => ({ ...lab, activeToolId, setActiveTool: setLabTool }),
+    [lab, activeToolId, setLabTool],
+  );
+}
+
+/** The lab's contributions for one region, in declaration order. */
+export function contributionsIn<TCtx = LabChromeContext>(
+  contributions: readonly LabContribution<TCtx>[],
+  region: LabRegion,
+): LabContribution<TCtx>[] {
+  return contributions.filter((c) => c.region === region);
+}
+
+/** The palette contributions a lab's `tools` stand for. Declaring a tool is
+ *  shorthand for contributing a palette item that writes the lab's tool
+ *  slot. */
+export function toolContributions(tools: readonly TrialTool[]): LabContribution[] {
+  return tools.map((t) => ({
+    id: t.id,
+    region: 'palette' as const,
+    ...(t.group === undefined ? {} : { group: t.group }),
+    item: {
+      icon: t.icon,
+      label: t.label,
+      ...(t.shortcut === undefined ? {} : { shortcut: t.shortcut }),
+    },
+  }));
+}
+
+/** Everything the lab's chrome renders, from both of the ways a lab declares
+ *  it. Tools and contributions share one id namespace, so a tool colliding
+ *  with a contribution throws here rather than one of them silently losing. */
+export function labContributions(
+  tools: readonly TrialTool[] | undefined,
+  chrome: readonly LabContribution[] | undefined,
+): LabContribution[] {
+  return mergeContributions<LabContribution>(toolContributions(tools ?? []), [...(chrome ?? [])]);
+}
+
+/** Props shared by the lab's region mounts. Each takes the lab's whole
+ *  contribution list and lays out the part addressed to it. */
+export interface LabRegionProps {
+  contributions: readonly LabContribution[];
+}
+
+/** The lab's action bar, in the shell header beside the title. */
+export function LabHeaderRegion({ contributions }: LabRegionProps) {
+  const ctx = useLabChromeContext();
+  return (
+    <ToolbarRegion
+      region="header"
+      label="Lab actions"
+      contributions={contributionsIn(contributions, 'header')}
+      ctx={ctx}
+    />
+  );
+}
+
+/** 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) {
+  const lab = useLabChromeContext();
+  const [collapsedSections, setFolds] = usePersistedState<Record<string, boolean>>(
+    'lk-lab-sidebar-folds',
+    {},
+    { scope: 'lab' },
+  );
+  const ctx = useMemo(
+    () => ({
+      ...lab,
+      collapsedSections,
+      setSectionCollapsed: (key: string, collapsed: boolean) =>
+        setFolds((f) => ({ ...f, [key]: collapsed })),
+    }),
+    [lab, collapsedSections, setFolds],
+  );
+  return <SidebarRegion contributions={contributionsIn(contributions, 'sidebar')} ctx={ctx} />;
+}
+
+/** The lab's readouts, in the shell footer below the workspace. */
+export function LabFooterRegion({ contributions }: LabRegionProps) {
+  const ctx = useLabChromeContext();
+  return (
+    <StatusRegion
+      region="footer"
+      contributions={contributionsIn(contributions, 'footer')}
+      ctx={ctx}
+    />
+  );
+}