@weasel-js/labkit 1.3.0 → 1.4.0-pre.1

package/src/index.ts

@@ -47,17 +47,103 @@ export {
   TextRow,
   ToggleRow,
 } from '@weasel-js/ui';
-export type { CanvasLayerDescriptor, CanvasStackContextValue, CanvasStackProps } from './canvas';
-export { CanvasStack, CanvasStackContext, screenToWorld, worldToScreen } from './canvas';
-export type { OrbitHandlers, OrbitView, UseOrbitOptions, Vec3 } from './canvas/useOrbit';
+export type {
+  Annotation,
+  AnnotationData,
+  AnnotationInit,
+  AnnotationKind,
+  AnnotationMeaning,
+  AnnotationPatch,
+  AnnotationQuery,
+  AnnotationStatus,
+  AnnotationStoreOptions,
+  AnnotationsApi,
+  AnnotationsCapability,
+  AnnotationTarget,
+  AnnotationTargetInfo,
+  CaptureDeps,
+  CaptureOptions,
+  CaptureResult,
+  CaptureSource,
+  FracPoint,
+  FracRect,
+  MarkScene,
+  SerializedAnnotations,
+  WorldRect,
+} from './annotations';
+export {
+  annotationsFromJSON,
+  createAnnotationScene,
+  createAnnotationStore,
+  fracContains,
+  fracIntersects,
+  fracToWorld,
+  isStale,
+  roundFrac,
+  seenFrom,
+  worldToFrac,
+} from './annotations';
+export type { AnnotationOverlayProps } from './annotations/AnnotationOverlay';
+export { AnnotationOverlay } from './annotations/AnnotationOverlay';
+export {
+  AnnotationsContext,
+  useAnnotations,
+  useAnnotationsOptional,
+} from './annotations/AnnotationsContext';
+export type { AnnotationTargetsProps } from './annotations/AnnotationTargets';
+export { AnnotationTargets } from './annotations/AnnotationTargets';
+export type { CaptureArgs, CapturePlan, ComposeSvgArgs } from './annotations/capture';
+export { capturePlan, captureTarget, composeCaptureSvg } from './annotations/capture';
+export type { MarkDrawOptions } from './annotations/drawOne';
+export { createMarkDrawOne, resolveMarkStyle } from './annotations/drawOne';
+export { ExportMenu } from './annotations/ExportMenu';
+export type { MarkListProps } from './annotations/MarkList';
+export { MarkList } from './annotations/MarkList';
+export type { MarkStyle, PaintableMark } from './annotations/paint';
+export { markCommands } from './annotations/paint';
+export { markSvgNodes } from './annotations/svgNodes';
+export type { AnnotationToolInfo } from './annotations/toolMap';
+export {
+  ANNOTATION_TOOLS,
+  ANNOTATION_WEASEL_TOOLS,
+  annotationToolInfo,
+} from './annotations/toolMap';
+export type { ContentSize, PaneSize } from './annotations/view';
+export { fitView, fromWeaselView, toWeaselView } from './annotations/view';
+export type {
+  CanvasLayerDescriptor,
+  CanvasStackContextValue,
+  CanvasStackProps,
+  CanvasStackSurface,
+  OrbitHandlers,
+  OrbitView,
+  PanZoomHandlers,
+  UseOrbitOptions,
+  UsePanZoomOptions,
+  Vec3,
+  ViewportSize,
+  WorldFrame,
+  WorldSpec,
+  ZoomAtOptions,
+} from './canvas';
 export {
+  applyCamera,
+  CanvasStack,
+  CanvasStackContext,
+  centerOn,
   clampPitch,
+  DEFAULT_FRAME,
   orbitAfterDrag,
   orbitAfterWheel,
   PITCH_LIMIT,
+  resolveFrame,
+  screenToWorld,
   useOrbit,
+  usePanZoom,
+  worldToScreen,
   wrapYaw,
-} from './canvas/useOrbit';
+  zoomAt,
+} from './canvas';
 export * from './chrome';
 export { f } from './config/builder';
 export { fromConfigFields } from './config/fromConfigField';
@@ -118,6 +204,7 @@ export * from './job';
 export * from './lab';
 export type { LayerListProps } from './layers';
 export { LayerList } from './layers';
+export * from './loupe';
 export * from './primitives';
 export {
   createMemoryAdapter,
@@ -147,6 +234,8 @@ export type {
   TrialStateHandle,
   UndoStack,
 } from './state/types';
+export type { UndockedPanel, UndockedPanels } from './state/undock';
+export { dockPanel, panelKey, undockPanel } from './state/undock';
 export { useTrialState } from './state/useTrialState';
 export type { ViewTransform2D } from './state/view';
 export { as2DView, DEFAULT_VIEW } from './state/view';

package/src/instrument/SineWave.smoke.test.tsx

@@ -93,6 +93,7 @@ describe('SineWave instrument smoke test', () => {
         zoom: 1,
         setZoom: vi.fn(),
         activeToolId: null,
+        visibleLayers: [],
       },
       emit: vi.fn(),
     };

package/src/instrument/types.ts

@@ -1,8 +1,11 @@
 import type { ReactNode } from 'react';
+import type { AnnotationsCapability } from '../annotations/types';
+import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
+import type { LoupeDeclaration } from '../loupe/types';
 import type { ToolCapability } from '../tools/types';
 
 /** What an instrument's `render` is handed: its state and config, the setters
@@ -25,6 +28,10 @@ export interface RenderContext<TS = unknown, TC = unknown> {
     /** Resolved active tool: this trial's slot, or the lab's. Null when neither
      *  holds one. */
     activeToolId: string | null;
+    /** The canvas layers currently shown, in declaration order. labkit skips a
+     *  hidden layer's `draw`, so this is the only way to know what was
+     *  painted — a legend listing rows the view did not draw needs it. */
+    visibleLayers: readonly string[];
   };
   emit: (event: string) => void;
   /** Present only when the instrument declares a `job`. */
@@ -45,7 +52,14 @@ export interface CanvasLayer<TS = unknown, TC = unknown> {
  *  view starts. */
 export interface CanvasCapability<TS = unknown, TC = unknown> {
   layers: CanvasLayer<TS, TC>[];
-  initialView?: { zoom: number; pan: { x: number; y: number } };
+  /** The coordinate system this instrument's world is in. Omitted, world (0,0)
+   *  sits at the canvas top-left with y running down — what labkit assumed
+   *  before an instrument could say otherwise. */
+  worldSpec?: WorldSpec;
+  /** Where the view starts. A function is called once the canvas knows its
+   *  size, so an instrument can frame content it can only place in terms of
+   *  the viewport; until then the trial's view is `null`. */
+  initialView?: ViewTransform | ((size: ViewportSize) => ViewTransform);
   /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
    *  regardless of these. */
   minZoom?: number;
@@ -127,6 +141,15 @@ export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
   /** Tools this instrument offers. Declaring them gives the trial a palette
    *  region and its own tool slot. */
   tools?: ToolCapability;
+  /** Regions of this instrument that accept marks, and optionally what a mark
+   *  is allowed to mean. Declaring it is what makes the trial provide the
+   *  annotation overlay and its chrome. */
+  annotations?: AnnotationsCapability<TS, TC>;
+  /** Magnification. `true` takes every default and re-draws the instrument's
+   *  canvas layers through a zoomed camera; an instrument whose content is DOM
+   *  gives a `render` that draws it again at a camera it is handed. A function
+   *  is re-read as the config changes, so a setting can drive the lens. */
+  loupe?: LoupeDeclaration<TS, TC> | ((config: TC) => LoupeDeclaration<TS, TC>);
   /** Chrome this instrument contributes beyond what its capabilities imply. */
   chrome?: TrialContribution[];
   /** Work too slow to do during a render. The runtime starts it, aborts it on

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

@@ -0,0 +1,162 @@
+/**
+ * `useTiledSurface` was built, exported and tested, but nothing mounted a
+ * `SurfaceContext` in production — so `useSurfaceOptional()` always answered
+ * null and a tile registered from inside a trial reached nothing.
+ *
+ * The surface is anchored to `.lk-lab__body` rather than wrapped around the
+ * workspace: `.lk-lab__body > .lk-workspace { min-width: 0 }` is a direct-child
+ * selector, so an extra element between them silently drops that rule.
+ */
+import { act, render } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import { useSurfaceOptional, useSurfaceTile } from '../surface/useSurfaceTile';
+import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
+import { useTiledSurface } from '../surface/useTiledSurface';
+import { Lab } from './Lab';
+
+/** jsdom measures everything as zero, so each element is given a box by hand. */
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+let seen: SurfaceHandle | null | 'not-rendered' = 'not-rendered';
+
+function Probe() {
+  seen = useSurfaceOptional();
+  const tile = useSurfaceTile('pane');
+  return <div data-testid="pane" ref={tile} />;
+}
+
+const probeInstrument = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Probe',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <Probe />,
+});
+
+describe('<Lab> surface provider', () => {
+  it('puts a surface handle in reach of an instrument', () => {
+    seen = 'not-rendered';
+    render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    expect(seen).not.toBe('not-rendered');
+    expect(seen).not.toBeNull();
+    expect(typeof (seen as unknown as SurfaceHandle).registerTile).toBe('function');
+  });
+
+  it('mounts one inert buffer inside the lab body', () => {
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const canvases = container.querySelectorAll('.lk-lab__body > canvas.lk-lab__surface');
+    expect(canvases).toHaveLength(1);
+  });
+
+  it('mounts no buffer of its own when a host already owns the surface', () => {
+    function Host({ children }: { children: ReactNode }) {
+      const surface = useTiledSurface({ onFrame: () => {} });
+      return (
+        <SurfaceContext.Provider value={surface}>
+          <div ref={surface.containerRef}>{children}</div>
+        </SurfaceContext.Provider>
+      );
+    }
+    const { container } = render(
+      <Host>
+        <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
+      </Host>,
+    );
+    expect(container.querySelectorAll('canvas.lk-lab__surface')).toHaveLength(0);
+  });
+
+  it('keeps the workspace a direct child of the lab body', () => {
+    // The min-width:0 rule that keeps the flex row from overflowing is
+    // `.lk-lab__body > .lk-workspace`. An element inserted between them drops
+    // it, and jsdom cannot see the overflow that follows.
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const body = container.querySelector('.lk-lab__body');
+    expect(body).not.toBeNull();
+    expect(body?.querySelector(':scope > .lk-workspace')).not.toBeNull();
+  });
+});
+
+describe('<Lab> tile round trip', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('publishes a rect for a tile an instrument registered', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+
+    function Host({ children }: { children: ReactNode }) {
+      const surface = useTiledSurface({ onFrame: (f) => frames.push(f) });
+      handle = surface;
+      return (
+        <SurfaceContext.Provider value={surface}>
+          <div
+            ref={(el) => {
+              if (!el) return;
+              stubBox(el, 0, 0, 800, 600);
+              surface.containerRef(el);
+            }}
+          >
+            {children}
+          </div>
+        </SurfaceContext.Provider>
+      );
+    }
+
+    render(
+      <Host>
+        <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
+      </Host>,
+    );
+
+    // The instrument's own div is the tile. Give it a box the container did
+    // not have, so a rect composed against the wrong origin is visible.
+    const pane = document.querySelector('[data-testid="pane"]') as HTMLElement;
+    expect(pane).not.toBeNull();
+    stubBox(pane, 240, 100, 320, 200);
+
+    act(() => {
+      handle?.invalidateRects();
+      handle?.invalidate('pane');
+    });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+
+    // Assert the frame fired at all before asserting its contents — a test
+    // that passes because nothing ran is the failure mode this arc keeps
+    // hitting.
+    expect(frames.length).toBeGreaterThan(0);
+    const rect = frames[frames.length - 1]?.rects.get('pane');
+    expect(rect).toEqual({ x: 240, y: 100, w: 320, h: 200 });
+  });
+});

package/src/lab/Lab.tsx

@@ -1,5 +1,13 @@
 import { ThemeProvider } from '@weasel-js/theme/react';
-import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
+import {
+  type CSSProperties,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { useStore } from 'zustand/react';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
@@ -8,6 +16,9 @@ import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore, type LabStore } from '../state/store';
 import type { LabMode, StorageAdapter, TrialRecord } from '../state/types';
+import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
+import { useTiledSurface } from '../surface/useTiledSurface';
 import { interstellarTheme } from '../theme/interstellar';
 import type { TrialTool } from '../tools/types';
 import { Trial } from '../trial/Trial';
@@ -22,8 +33,9 @@ import { LabContext, type LabContextValue } from './LabContext';
 import { LabHeader } from './LabHeader';
 import { LabPalette } from './LabPalette';
 import { LabShell } from './LabShell';
+import { createPanelHostRegistry, PanelHostContext } from './panelHost';
 import { useResolvedMode } from './useSystemMode';
-import { type TrialLayout, Workspace } from './Workspace';
+import { type PanelDescriptor, type TrialLayout, Workspace } from './Workspace';
 
 /** Props for `<Lab>`. */
 export interface LabProps {
@@ -137,6 +149,57 @@ export function Lab({
   const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
   const modeValue = useStore(store, (s) => s.mode);
   const layout = useStore(store, (s) => s.layout);
+  const undockedPanels = useStore(store, (s) => s.undockedPanels);
+
+  // One registry for the lab's lifetime: a panel host is a DOM node the
+  // workspace owns and the trial portals into, so it must outlive both ends of
+  // a dock/undock without being rebuilt.
+  const panelHostsRef = useRef<ReturnType<typeof createPanelHostRegistry> | null>(null);
+  if (panelHostsRef.current === null) panelHostsRef.current = createPanelHostRegistry();
+
+  // One shared drawing surface for the whole lab, anchored to the body — tile
+  // rects compose against it, and every tile paints into the one buffer.
+  // `Workspace` invalidates rects when the grid moves something a
+  // ResizeObserver cannot see. A host that already owns a surface keeps it: a
+  // lab embedded in a larger shared-surface app must not open a second GL
+  // tenancy, and mounts no buffer of its own.
+  const outerSurface = useSurfaceOptional();
+  const outerCanvas = useSurfaceCanvas();
+  const [ownCanvas, setOwnCanvas] = useState<HTMLCanvasElement | null>(null);
+  const ownCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const bufferRef = useRef({ w: 0, h: 0 });
+  const surfaceRef = useRef<ReturnType<typeof useTiledSurface> | null>(null);
+
+  // Sizing the buffer clears all of it, so every tile has to repaint — not
+  // only the one whose move triggered the measurement.
+  const onFrame = useCallback((frame: { size: { width: number; height: number }; dpr: number }) => {
+    const c = ownCanvasRef.current;
+    if (!c) return;
+    const w = Math.round(frame.size.width * frame.dpr);
+    const h = Math.round(frame.size.height * frame.dpr);
+    if (bufferRef.current.w === w && bufferRef.current.h === h) return;
+    bufferRef.current = { w, h };
+    c.width = w;
+    c.height = h;
+    c.style.width = `${frame.size.width}px`;
+    c.style.height = `${frame.size.height}px`;
+    surfaceRef.current?.invalidateAll();
+  }, []);
+
+  const ownSurface = useTiledSurface({ onFrame });
+  surfaceRef.current = ownSurface;
+  const surface = outerSurface ?? ownSurface;
+  const surfaceCanvas = outerSurface ? outerCanvas : ownCanvas;
+
+  const workspacePanels = useMemo<PanelDescriptor[]>(
+    () =>
+      Object.entries(undockedPanels).map(([key, panel]) => ({
+        key,
+        title: panel.sectionId,
+        as: panel.as,
+      })),
+    [undockedPanels],
+  );
   const resolvedMode = useResolvedMode(modeValue);
 
   useEffect(() => {
@@ -232,21 +295,43 @@ export function Lab({
               </>
             }
           >
-            <div className="lk-lab__body">
-              {tools ? <LabPalette tools={tools} /> : null}
-              <Workspace
-                ids={trials.map((w) => w.id)}
-                resizable
-                reorderable
-                onReorder={(ids) => contextValue.reorderTrials(ids)}
-                layout={layout as TrialLayout}
-                onLayoutChange={(next) => store.getState().setLayout(next)}
-              >
-                {trials.map((w) => (
-                  <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
-                ))}
-              </Workspace>
-            </div>
+            <PanelHostContext.Provider value={panelHostsRef.current}>
+              <SurfaceContext.Provider value={surface}>
+                <SurfaceCanvasContext.Provider value={surfaceCanvas}>
+                  <div
+                    className="lk-lab__body"
+                    ref={outerSurface ? undefined : ownSurface.containerRef}
+                  >
+                    {outerSurface ? null : (
+                      // Above the trials and inert: the marks a tile paints have
+                      // to sit over the instrument's own DOM, and nothing on this
+                      // buffer takes input — each tile has its own input box.
+                      <canvas
+                        className="lk-lab__surface"
+                        ref={(el) => {
+                          ownCanvasRef.current = el;
+                          setOwnCanvas(el);
+                        }}
+                      />
+                    )}
+                    {tools ? <LabPalette tools={tools} /> : null}
+                    <Workspace
+                      panels={workspacePanels}
+                      ids={trials.map((w) => w.id)}
+                      resizable
+                      reorderable
+                      onReorder={(ids) => contextValue.reorderTrials(ids)}
+                      layout={layout as TrialLayout}
+                      onLayoutChange={(next) => store.getState().setLayout(next)}
+                    >
+                      {trials.map((w) => (
+                        <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
+                      ))}
+                    </Workspace>
+                  </div>
+                </SurfaceCanvasContext.Provider>
+              </SurfaceContext.Provider>
+            </PanelHostContext.Provider>
           </LabShell>
         </ThemeProvider>
       </LabContext.Provider>

package/src/lab/Lab.undock.test.tsx

@@ -0,0 +1,85 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import type { TrialContribution } from '../chrome/types';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+
+const bare: Instrument = {
+  name: 'Bare',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+const notes: TrialContribution = {
+  id: 'notes',
+  region: 'sidebar',
+  item: { title: 'Notes', body: <p data-testid="notes-body">jot</p> },
+};
+
+const floater: TrialContribution = {
+  id: 'floater',
+  region: 'sidebar',
+  item: {
+    title: 'Floater',
+    undockAs: 'floating',
+    body: <p data-testid="floater-body">hover</p>,
+  },
+};
+
+const pinned: TrialContribution = {
+  id: 'pinned',
+  region: 'sidebar',
+  item: { title: 'Pinned', undockable: false, body: <p>stay</p> },
+};
+
+function renderLab() {
+  return render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[notes]} />);
+}
+
+describe('undocking a sidebar section', () => {
+  it('starts docked inside the trial sidebar', () => {
+    const { container } = renderLab();
+    const sidebar = container.querySelector('.lk-trial__sidebar');
+    expect(sidebar).toContainElement(screen.getByTestId('notes-body'));
+  });
+
+  it('moves the section out of the sidebar and into a workspace panel', async () => {
+    const { container } = renderLab();
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Notes' }));
+
+    expect(container.querySelector('.lk-trial__sidebar')).not.toContainElement(
+      screen.queryByTestId('notes-body'),
+    );
+    const panel = container.querySelector('.lk-panel-tile');
+    expect(panel).toContainElement(screen.getByTestId('notes-body'));
+  });
+
+  it('docks it back', async () => {
+    const { container } = renderLab();
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Notes' }));
+    await userEvent.click(screen.getByRole('button', { name: 'Dock Notes' }));
+
+    expect(container.querySelector('.lk-panel-tile')).toBeNull();
+    expect(container.querySelector('.lk-trial__sidebar')).toContainElement(
+      screen.getByTestId('notes-body'),
+    );
+  });
+
+  it('sends a section declaring undockAs floating to the floating layer', async () => {
+    const { container } = render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[floater]} />,
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Floater' }));
+
+    const floating = container.querySelector('.lk-workspace__floating');
+    expect(floating).toContainElement(screen.getByTestId('floater-body'));
+    expect(container.querySelector('.lk-panel-tile--floating')).not.toBeNull();
+  });
+
+  it('offers no tear-out control on a section that opts out', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[pinned]} />);
+    expect(screen.queryByRole('button', { name: 'Undock Pinned' })).toBeNull();
+  });
+});

package/src/lab/LabFullChrome.stories.tsx

@@ -280,6 +280,26 @@ export const AllChrome: Story = {
   },
 };
 
+/** Undocking, in both targets. `Notes` declares `undockAs: 'floating'`, so its
+ *  tear-out control sends it to the layer above the grid; every other section
+ *  defaults to a tile and joins the tiling as a peer of the trials. */
+export const UndockablePanels: Story = {
+  args: {
+    ...AllChrome.args,
+    chrome: [
+      {
+        id: 'notes',
+        region: 'sidebar',
+        item: {
+          title: 'Notes',
+          undockAs: 'floating',
+          body: <p className="lk-run-tag">Undock me — I float.</p>,
+        },
+      },
+    ],
+  },
+};
+
 /** The chrome the other story cannot show at the same time: one instrument, so
  *  the header is an Add trial button; one trial, so Close is disabled; no
  *  config schema, canvas, undo or job, so the sidebar falls back to its

package/src/lab/LabShell.less

@@ -48,12 +48,23 @@
   display: flex;
   height: 100%;
   min-height: 0;
+  position: relative;
 
   > .lk-workspace {
     min-width: 0;
   }
 }
 
+// The lab's one shared drawing buffer. Over the trials, because a tile's marks
+// annotate the instrument's own DOM; under the viewport chrome, whose z-overlay
+// outranks it; and inert, because every tile takes input from its own box.
+.lk-lab__surface {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+}
+
 .lk-shell-footer {
   border-top: 1px solid var(--wzl-border);
   padding: var(--wzl-space-xs) var(--wzl-space-md);