@weasel-js/labkit 1.7.3 → 1.8.1

package/dist/surface/index.d.ts

@@ -53,6 +53,9 @@ interface SurfaceHandle {
     invalidate: (id: string) => void;
     /** Mark every tile — what a resize or a tile-set change means. */
     invalidateAll: () => void;
+    /** Mark every tile overlapping `box`, in viewport px as `getBoundingClientRect`
+     *  gives them: what something drawn over the tiles leaves behind when it moves. */
+    invalidateBox: (box: Box) => void;
     /** Re-measure before the next frame. The escape hatch for a host that knows it
      *  moved something a ResizeObserver cannot see. */
     invalidateRects: () => void;
@@ -71,6 +74,15 @@ interface SurfaceHandle {
     /** The element tile rects are measured against, and so the one a tile's own
      *  chrome positions itself inside. Null before the owner attaches it. */
     getContainer: () => HTMLElement | null;
+    /** Narrow the surface to the tiles inside `el`, or widen it back with
+     *  `null`. A tile outside drops out of the frame's `rects` and is not
+     *  painted, and the frame is retiled so the buffer is cleared of it — what
+     *  an expanded tile needs, with the buffers lifted over the rest. */
+    scope: (el: HTMLElement | null) => void;
+    /** Whether the tile is inside the current scope. Everything is, unscoped. */
+    inScope: (id: string) => boolean;
+    /** Called whenever the scope changes. Returns the unsubscribe. */
+    subscribeScope: (listener: () => void) => () => void;
 }
 /** What a tile's painter is handed: where it sits on the surface now, and the
  *  frame that dirtied it. */
@@ -148,6 +160,13 @@ declare function useTileId(id: string): string;
  * The frame reports it under `useTileId(id)`, not under `id`.
  */
 declare function useSurfaceTile(id: string): (el: HTMLElement | null) => void;
+/**
+ * Whether the tile registered under `tileId` — the key `useTileId` returns —
+ * is inside the surface's scope. A tenant with chrome of its own on the
+ * surface hides it while this is false, since nothing paints that tile then.
+ * True with no surface above.
+ */
+declare function useTileInScope(tileId: string): boolean;
 
-export { SurfaceCanvasContext, SurfaceContext, composeRects, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTiledSurface };
+export { SurfaceCanvasContext, SurfaceContext, composeRects, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTileInScope, useTiledSurface };
 export type { Box, Rect, SurfaceCanvases, SurfaceClear, SurfaceFrame, SurfaceHandle, SurfaceLayer, TilePainter, UseTiledSurfaceOptions };

package/dist/surface/index.js

@@ -1,5 +1,5 @@
-export { composeRects, toDeviceRect, useTiledSurface } from '../chunk-EESJUSYR.js';
-export { SurfaceCanvasContext, SurfaceContext, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId } from '../chunk-WIG6XHJ7.js';
+export { composeRects, toDeviceRect, useTiledSurface } from '../chunk-QMAY74TP.js';
+export { SurfaceCanvasContext, SurfaceContext, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTileInScope } from '../chunk-6IIKLXBZ.js';
 import '../chunk-2YILQ7Y5.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,9 +1,9 @@
-export { at as UndoCapability } from '../_dts/index-DCMA4Fy1.js';
+export { au as UndoCapability } from '../_dts/index-8geQNQet.js';
 import '@weasel-js/ui';
 import '@weasel-js/core';
 import 'react';
 import '@weasel-js/theme';
-import '../_dts/types-BUBSIZuV.js';
+import '../_dts/types-DUfQ0isU.js';
 import '@weasel-js/quantity';
 import '@weasel-js/geom';
 import '../_dts/types-DJ79Tg5J.js';
@@ -20,31 +20,42 @@ interface EventBus {
 /** Build an empty event bus. */
 declare function createEventBus(): EventBus;
 
+/**
+ * @deprecated The whole module. A trial's undo runs on weasel-history
+ * (`TrialRecord.history`); for an undo of your own, `createHistory` from
+ * `@weasel-js/core`. Kept until sherpa's studio, its last user, moves off it.
+ */
 /** Undo history as two stacks of state snapshots: what has been done, and
- *  what has been undone. The present state is held elsewhere, not here. */
+ *  what has been undone. The present state is held elsewhere, not here.
+ *  @deprecated See the module comment. */
 interface UndoStack {
     past: unknown[];
     future: unknown[];
 }
-/** A fresh, empty history. */
+/** A fresh, empty history.
+ *  @deprecated See the module comment. */
 declare function emptyStack(): UndoStack;
 /** Record a new snapshot, discarding the redo branch and the oldest entry
- *  once `maxDepth` is reached. */
+ *  once `maxDepth` is reached.
+ *  @deprecated See the module comment. */
 declare function pushSnapshot(stack: UndoStack, snapshot: unknown, maxDepth: number): UndoStack;
 /** Step back one snapshot, returning the new history and the state to restore.
  *  `null` when there is nothing to undo. The caller supplies `current` so it
- *  can be redone. */
+ *  can be redone.
+ *  @deprecated See the module comment. */
 declare function undo(stack: UndoStack, current: unknown): {
     stack: UndoStack;
     snapshot: unknown;
 } | null;
 /** Step forward one snapshot, returning the new history and the state to
- *  restore. `null` when there is nothing to redo. */
+ *  restore. `null` when there is nothing to redo.
+ *  @deprecated See the module comment. */
 declare function redo(stack: UndoStack, current: unknown): {
     stack: UndoStack;
     snapshot: unknown;
 } | null;
-/** Discard the whole history. */
+/** Discard the whole history.
+ *  @deprecated See the module comment. */
 declare function clearUndo(_stack: UndoStack): UndoStack;
 
 export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo };

package/dist/undo/index.js

@@ -1,3 +1,3 @@
-export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from '../chunk-RL2LOLNI.js';
+export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from '../chunk-UX66USTN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.7.3",
+  "version": "1.8.1",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -115,18 +115,18 @@
     "dev:3d": "LABKIT_EXAMPLE=3d-lab vite"
   },
   "peerDependencies": {
-    "@weasel-js/core": "1.7.3",
-    "@weasel-js/theme": "1.7.3",
+    "@weasel-js/core": "1.8.1",
+    "@weasel-js/theme": "1.8.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/geom": "1.7.3",
-    "@weasel-js/kernel3d": "1.7.3",
-    "@weasel-js/loupe": "1.7.3",
-    "@weasel-js/quantity": "1.7.3",
-    "@weasel-js/svg": "1.7.3",
-    "@weasel-js/ui": "1.7.3",
+    "@weasel-js/geom": "1.8.1",
+    "@weasel-js/kernel3d": "1.8.1",
+    "@weasel-js/loupe": "1.8.1",
+    "@weasel-js/quantity": "1.8.1",
+    "@weasel-js/svg": "1.8.1",
+    "@weasel-js/ui": "1.8.1",
     "earcut": "3.2.3",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -136,8 +136,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@testing-library/jest-dom": "^7.0.1",
-    "@weasel-js/guides": "1.7.3",
-    "@weasel-js/modes": "1.7.3",
+    "@weasel-js/guides": "1.8.1",
+    "@weasel-js/modes": "1.8.1",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationOverlay.abandon.test.tsx

@@ -65,6 +65,7 @@ function surfaceFor(clears: SurfaceClear[]): SurfaceHandle {
     invalidate: () => {},
     invalidateAll: () => {},
     invalidateRects: () => {},
+    invalidateBox: () => {},
     registerTile: () => {},
     registerClear: (_id, clear) => {
       clears.push(clear);
@@ -76,6 +77,9 @@ function surfaceFor(clears: SurfaceClear[]): SurfaceHandle {
     },
     containerRef: () => {},
     getContainer: () => container,
+    scope: () => {},
+    inScope: () => true,
+    subscribeScope: () => () => {},
   } as SurfaceHandle;
 }
 

package/src/annotations/AnnotationOverlay.tsx

@@ -20,7 +20,12 @@ import {
 import { createPortal, flushSync } from 'react-dom';
 import { CameraWheelContext } from '../canvas/CameraWheelContext';
 import type { Rect } from '../surface/rect';
-import { useSurfaceCanvas, useSurfaceOptional, useTileId } from '../surface/useSurfaceTile';
+import {
+  useSurfaceCanvas,
+  useSurfaceOptional,
+  useTileId,
+  useTileInScope,
+} from '../surface/useSurfaceTile';
 import { createMarkDrawOne } from './drawOne';
 import { boundsOf, roundPoints, toShape, type WorldRect } from './frac';
 import { POINT_MARK_SHAPE } from './paint';
@@ -124,6 +129,9 @@ export function AnnotationOverlay({
   // instrument declares the same target ids — so the tile is registered under
   // the trial-scoped key, not under `id`.
   const tileId = useTileId(id);
+  // Out of scope while another trial is expanded: nothing paints this tile
+  // then, and its box would sit over the expanded one.
+  const inScope = useTileInScope(tileId);
   const lastTile = useRef<HTMLElement | null>(null);
   useEffect(() => {
     const el = target.ref.current ?? null;
@@ -248,6 +256,7 @@ export function AnnotationOverlay({
         // 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 : ''}
+        hidden={!inScope}
         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,8 @@
   width: var(--lk-anno-w);
   height: var(--lk-anno-h);
   z-index: 2;
+  // The container is a layer over the whole lab that takes no input itself.
+  pointer-events: auto;
 
   &[data-idle] {
     pointer-events: none;

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

@@ -44,12 +44,15 @@ function Harness({
   toolId = 'rect',
   onRegisterClear,
   canvas = null,
+  onSurface,
 }: {
   toolId?: string;
   /** Told each tile a clear is registered for, and handed the clear. */
   onRegisterClear?: (id: string, clear: SurfaceClear) => void;
   /** The shared buffer the overlays paint into. */
   canvas?: HTMLCanvasElement | null;
+  /** Handed the surface, for a test that drives it. */
+  onSurface?: (surface: SurfaceHandle) => void;
 }) {
   const a = useRef<HTMLDivElement | null>(null);
   const b = useRef<HTMLDivElement | null>(null);
@@ -68,6 +71,7 @@ function Harness({
     [tiled, onRegisterClear],
   );
   const annotations = useRef(createAnnotationStore({ targets: () => [] })).current;
+  onSurface?.(surface);
 
   const capability: AnnotationsCapability = {
     targets: (): AnnotationTarget[] => [
@@ -178,6 +182,31 @@ describe('<AnnotationTargets>', () => {
     }
   });
 
+  it('hides the box of a target the surface is scoped away from', () => {
+    let surface: SurfaceHandle | null = null;
+    const { container, getByTestId } = render(
+      <Harness
+        onSurface={(s) => {
+          surface = s;
+        }}
+      />,
+      { wrapper: StrictMode },
+    );
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    const box = (id: string) =>
+      container.querySelector<HTMLElement>(`.lk-annotate__input[data-annotation-target="${id}"]`);
+    act(() => surface?.scope(getByTestId('a')));
+    expect(box('pane:a')?.hidden).toBe(false);
+    expect(box('pane:b')?.hidden).toBe(true);
+    act(() => surface?.scope(null));
+    expect(box('pane:b')?.hidden).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+  });
+
   it('hands a wheel over a target to the trial camera', () => {
     // The input box is portalled into the surface container, so the wheel
     // would otherwise bubble past the stage the picture sits on.

package/src/canvas/CanvasStack.test.tsx

@@ -131,3 +131,38 @@ describe('<CanvasStack> zoom invariant', () => {
     vi.restoreAllMocks();
   });
 });
+
+describe('<CanvasStack ticks>', () => {
+  it('repaints only the timed layers on a tick', async () => {
+    const still: CanvasLayerDescriptor = { id: 'still', visible: true, render: vi.fn() };
+    const moving: CanvasLayerDescriptor = {
+      id: 'moving',
+      visible: true,
+      timed: true,
+      render: vi.fn(),
+    };
+    const listeners = new Set<() => void>();
+    const ticks = (fn: () => void) => {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    };
+    const nextFrame = () => new Promise((r) => requestAnimationFrame(() => r(null)));
+    render(
+      <CanvasStack
+        layers={[still, moving]}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+        ticks={ticks}
+      />,
+    );
+    await nextFrame();
+    vi.mocked(still.render).mockClear();
+    vi.mocked(moving.render).mockClear();
+    for (const fn of listeners) fn();
+    await nextFrame();
+    expect(moving.render).toHaveBeenCalledTimes(1);
+    expect(still.render).not.toHaveBeenCalled();
+  });
+});

package/src/canvas/CanvasStack.tsx

@@ -30,6 +30,8 @@ export interface CanvasStackProps {
   /** A yoke to join, from `useYoke()`: cameras on one yoke share their tool
    *  and gesture in flight. Omitted, this one keeps its own. */
   yoke?: Yoke;
+  /** Frames after each of which every `timed` layer repaints — a trial clock's. */
+  ticks?: (fn: () => void) => () => void;
 }
 
 /** Stacks one `<canvas>` per layer and drives them from a shared view, so a
@@ -50,6 +52,7 @@ export function CanvasStack({
   onHitTest,
   children,
   yoke,
+  ticks,
 }: CanvasStackProps) {
   const view = normalize2DView(viewProp);
   const containerRef = useRef<HTMLDivElement | null>(null);
@@ -101,7 +104,15 @@ export function CanvasStack({
     () => ({ view: camera, frame, element: () => containerRef.current }),
     [camera, frame],
   );
-  useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
+  useLayerScheduler({
+    layers,
+    view,
+    frame,
+    canvasRefs: canvasMap,
+    size,
+    host: containerRef,
+    ticks,
+  });
 
   const ctxValue = useMemo(
     () => ({

package/src/canvas/useLayerScheduler.ts

@@ -8,6 +8,8 @@ import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 export interface CanvasLayerDescriptor {
   id: string;
   visible: boolean;
+  /** Repaint on every `ticks` frame, not only when `render` or the view change. */
+  timed?: boolean;
   render: (ctx: CanvasRenderingContext2D, view: ViewTransform, frame: WorldFrame) => void;
 }
 
@@ -21,6 +23,9 @@ interface SchedulerOptions {
   /** The element the stack occupies. Given one, the scheduler also stops while
    *  the stack sits outside the viewport. */
   host?: RefObject<Element | null>;
+  /** Subscribes to frames — a trial clock's — after each of which every timed
+   *  layer repaints. Returns the unsubscribe. */
+  ticks?: (fn: () => void) => () => void;
 }
 
 export function useLayerScheduler({
@@ -30,6 +35,7 @@ export function useLayerScheduler({
   canvasRefs,
   size,
   host,
+  ticks,
 }: SchedulerOptions): void {
   const dirty = useRef<Set<string>>(new Set());
   const lastRenderRef = useRef<Map<string, CanvasLayerDescriptor['render']>>(new Map());
@@ -82,4 +88,12 @@ export function useLayerScheduler({
   useEffect(() => {
     if (dirty.current.size > 0) frameLoop.request();
   });
+
+  useEffect(() => {
+    if (!ticks || !layers.some((l) => l.timed)) return;
+    return ticks(() => {
+      for (const layer of layers) if (layer.timed) dirty.current.add(layer.id);
+      frameLoop.request();
+    });
+  }, [ticks, layers, frameLoop]);
 }

package/src/chrome/builtins.test.ts

@@ -26,6 +26,9 @@ const ctx: TrialChromeContext = {
   hasLoupe: false,
   loupeOn: false,
   toggleLoupe: () => {},
+  canExpand: false,
+  expanded: false,
+  toggleExpanded: () => {},
   configFields: [],
   configSchema: fromConfigFields([]),
   config: {},
@@ -73,6 +76,17 @@ describe('builtinContributions', () => {
     expect(ids({ ...bare, undo: {} })).toContain('redo');
   });
 
+  it('contributes the expand toggle only inside a lightbox, ahead of the trial actions', () => {
+    expect(ids(bare)).not.toContain('expand');
+    expect(ids(bare, { ...ctx, canExpand: true })).toEqual([
+      'expand',
+      'clone',
+      'reset',
+      'snapshot',
+      'close',
+    ]);
+  });
+
   it('contributes the loupe toggle only while a lens is mounted', () => {
     expect(ids(bare)).not.toContain('loupe');
     const mounted = builtinContributions(bare, { ...ctx, hasLoupe: true });

package/src/chrome/builtins.tsx

@@ -1,7 +1,9 @@
 import {
   CloneIcon,
   CloseIcon,
+  CollapseIcon,
   FitIcon,
+  FullscreenIcon,
   LoupeIcon,
   RedoIcon,
   ResetIcon,
@@ -40,8 +42,9 @@ function groupFolds(
 }
 
 /** Built-in ids contributed only while runtime state says so — the loupe
- *  toggle appears once a lens mounts, after the trial's first render. */
-export const TRANSIENT_BUILTINS: ReadonlySet<string> = new Set(['loupe']);
+ *  toggle appears once a lens mounts, after the trial's first render, and the
+ *  expand toggle only inside a lightbox. */
+export const TRANSIENT_BUILTINS: ReadonlySet<string> = new Set(['loupe', 'expand']);
 
 /**
  * The contributions a trial gets from what its instrument declared. This is
@@ -221,6 +224,18 @@ export function builtinContributions(
       ),
     });
   }
+  if (ctx.canExpand) {
+    out.push({
+      id: 'expand',
+      region: 'titlebar',
+      end: true,
+      item: {
+        icon: ctx.expanded ? CollapseIcon : FullscreenIcon,
+        label: ctx.expanded ? 'Close expanded view' : 'Expand trial',
+        onActivate: ctx.toggleExpanded,
+      },
+    });
+  }
   out.push({
     id: 'clone',
     region: 'titlebar',

package/src/chrome/regions/StatusRegion.tsx

@@ -1,4 +1,5 @@
-import { StatusBar } from '../../primitives/StatusBar';
+import { StatusBar, StatusBarItem, StatusBarSpacer } from '@weasel-js/ui';
+import { Fragment, type ReactNode } from 'react';
 import type { RegionContribution, StatusReadout, TrialChromeContext } from '../types';
 
 /** Props for `<StatusRegion>`. */
@@ -9,28 +10,33 @@ export interface StatusRegionProps<TCtx = TrialChromeContext> {
   region?: string;
 }
 
-/** Lays a bar's readouts out. */
+/** Lays a bar's readouts out. The first one marked `end`, and every one after
+ *  it, sits at the far end. */
 export function StatusRegion<TCtx = TrialChromeContext>({
   contributions,
   ctx,
   region = 'status',
 }: StatusRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
+  let spaced = false;
   return (
-    <StatusBar>
+    <StatusBar divided>
       {contributions.map((c) => {
-        if (c.render)
-          return (
-            <StatusBar.Section key={c.id} end={c.end}>
-              {c.render(ctx)}
-            </StatusBar.Section>
-          );
-        if (c.region !== region || !c.item) return null;
-        const item = c.item as StatusReadout;
+        let body: ReactNode;
+        let title: string | undefined;
+        if (c.render) body = c.render(ctx);
+        else if (c.region === region && c.item) {
+          const item = c.item as StatusReadout;
+          body = item.text;
+          title = item.title;
+        } else return null;
+        const spacer = c.end && !spaced;
+        if (spacer) spaced = true;
         return (
-          <StatusBar.Section key={c.id} end={c.end}>
-            <span title={item.title}>{item.text}</span>
-          </StatusBar.Section>
+          <Fragment key={c.id}>
+            {spacer && <StatusBarSpacer />}
+            <StatusBarItem title={title}>{body}</StatusBarItem>
+          </Fragment>
         );
       })}
     </StatusBar>

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

@@ -92,6 +92,34 @@ describe('StatusRegion', () => {
     );
     expect(screen.getByText('150%')).toBeInTheDocument();
   });
+
+  it('pushes the first readout marked end, and the ones after it, past one spacer', () => {
+    const { container } = render(
+      <StatusRegion
+        contributions={[
+          { id: 'a', region: 'status', item: { text: 'A' } },
+          { id: 'b', region: 'status', end: true, item: { text: 'B' } },
+          { id: 'c', region: 'status', end: true, item: { text: 'C' } },
+        ]}
+        ctx={ctx}
+      />,
+    );
+    const bar = container.querySelector('footer') as HTMLElement;
+    const kids = [...bar.children].map((el) =>
+      el.getAttribute('aria-hidden') === 'true' ? '|' : el.textContent,
+    );
+    expect(kids).toEqual(['A', '|', 'B', 'C']);
+  });
+
+  it('keeps a readout title as its hover text', () => {
+    render(
+      <StatusRegion
+        contributions={[{ id: 'z', region: 'status', item: { text: '150%', title: 'zoom' } }]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.getByText('150%').closest('[title]')?.getAttribute('title')).toBe('zoom');
+  });
 });
 
 describe('ViewportRegion', () => {

package/src/chrome/types.ts

@@ -169,6 +169,14 @@ export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext
   loupeOn: boolean;
   toggleLoupe: () => void;
 
+  /** Whether the trial sits in a `<Lightbox>` — every `<Workspace>` tile does
+   *  unless the workspace turned it off. The expand toggle is offered only
+   *  while it does. */
+  canExpand: boolean;
+  /** Whether the trial is showing in its lightbox. */
+  expanded: boolean;
+  toggleExpanded: () => void;
+
   /** The instrument's controls, resolved against the lab's rules. Always
    *  populated: a legacy `configSchema()` is adapted into the same shape. */
   configSchema: ResolvedConfig;

package/src/clock/clock.browser.test.less

@@ -0,0 +1,5 @@
+// Host page for clock.browser.test: a lab with room for its canvas to lay out.
+.lk-clock-frame {
+  height: 480px;
+  width: 640px;
+}

package/src/clock/clock.browser.test.tsx

@@ -0,0 +1,77 @@
+import '@weasel-js/theme/tokens.css';
+import 'windease/styles.css';
+import '../styles.less';
+import './clock.browser.test.less';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+
+// The lab's frame loop syncing a trial clock and a timed layer repainting from
+// it: real frames and real pixels, which only a browser has.
+
+afterEach(cleanup);
+
+/** Fills the view with a red that steps with the clock, 1 a frame-ish. */
+const Ticking: Instrument = {
+  name: 'Ticking',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  clock: { rate: 1 },
+  canvas: {
+    layers: [
+      {
+        id: 'tick',
+        timed: true,
+        draw: (ctx, { elapsed }) => {
+          ctx.fillStyle = `rgb(${Math.floor(elapsed / 16) % 256}, 0, 0)`;
+          ctx.fillRect(-1e5, -1e5, 2e5, 2e5);
+        },
+      },
+    ],
+  },
+  render: (ctx) => (
+    <button
+      type="button"
+      onClick={() => {
+        if (ctx.trial.clock) ctx.trial.clock.rate = 0;
+      }}
+    >
+      pause
+    </button>
+  ),
+};
+
+/** The red channel at the middle of the layer's canvas. */
+function red(): number {
+  const canvas = document.querySelector(
+    '.lk-clock-frame .lk-canvas-stack__canvas',
+  ) as HTMLCanvasElement;
+  const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
+  return ctx.getImageData(canvas.width >> 1, canvas.height >> 1, 1, 1).data[0] ?? -1;
+}
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+test('a timed layer repaints as the clock plays, and holds once it pauses', async () => {
+  render(
+    <div className="lk-clock-frame">
+      <Lab title="T" instruments={[Ticking]} defaultInstrument="Ticking" />
+    </div>,
+  );
+  // Layout settles first — the first measurement places the view and repaints
+  // every layer — so only the clock can repaint after it.
+  await wait(500);
+  const a = red();
+  await wait(150);
+  const b = red();
+  await wait(150);
+  expect(b).not.toBe(a);
+  expect(red()).not.toBe(b);
+
+  fireEvent.click(screen.getByRole('button', { name: 'pause' }));
+  await wait(100);
+  const held = red();
+  await wait(300);
+  expect(red()).toBe(held);
+});