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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.4.0-pre.1",
+  "version": "1.4.0",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -93,7 +93,7 @@
     "dev:drag": "LABKIT_EXAMPLE=drag-lab vite",
     "dev:weasel": "LABKIT_EXAMPLE=weasel-lab vite",
     "build": "tsup && npm run build:dts && npm run build:css && npm run build:fonts",
-    "build:dts": "tsx scripts/build-dts.mts",
+    "build:dts": "NODE_OPTIONS=--max-old-space-size=8192 tsx scripts/build-dts.mts",
     "prepublishOnly": "npm run build",
     "build:css": "node scripts/build-css.mjs",
     "build:fonts": "mkdir -p dist/fonts && cp ../theme/fonts/*.woff2 dist/fonts/",
@@ -114,11 +114,11 @@
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/core": "1.4.0-pre.1",
-    "@weasel-js/loupe": "1.4.0-pre.1",
-    "@weasel-js/svg": "1.4.0-pre.1",
-    "@weasel-js/theme": "1.4.0-pre.1",
-    "@weasel-js/ui": "1.4.0-pre.1",
+    "@weasel-js/core": "1.4.0",
+    "@weasel-js/loupe": "1.4.0",
+    "@weasel-js/svg": "1.4.0",
+    "@weasel-js/theme": "1.4.0",
+    "@weasel-js/ui": "1.4.0",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -129,7 +129,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.4.0-pre.1",
+    "@weasel-js/modes": "1.4.0",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationOverlay.tsx

@@ -9,7 +9,7 @@ import {
 import { type CSSProperties, useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import type { Rect } from '../surface/rect';
-import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
+import { useSurfaceCanvas, useSurfaceOptional, useTileId } from '../surface/useSurfaceTile';
 import { createMarkDrawOne } from './drawOne';
 import type { WorldRect } from './frac';
 import { seenFrom } from './staleness';
@@ -101,12 +101,16 @@ export function AnnotationOverlay({
   configRef.current = config;
 
   const id = target.id;
+  // The surface's tile namespace is the whole lab's, and every trial of an
+  // instrument declares the same target ids — so the tile is registered under
+  // the trial-scoped key, not under `id`.
+  const tileId = useTileId(id);
   const lastTile = useRef<HTMLElement | null>(null);
   useEffect(() => {
     const el = target.ref.current ?? null;
     if (el === lastTile.current) return;
     lastTile.current = el;
-    surface?.registerTile(id, el);
+    surface?.registerTile(tileId, el);
   });
   useEffect(
     () => () => {
@@ -114,20 +118,20 @@ export function AnnotationOverlay({
       // commit. StrictMode's mount / unmount / mount would otherwise take the
       // tile out and never put it back, and the surface would measure nothing.
       lastTile.current = null;
-      surface?.registerTile(id, null);
+      surface?.registerTile(tileId, null);
     },
-    [surface, id],
+    [surface, tileId],
   );
 
   useEffect(
     () =>
-      surface?.registerPainter(id, (next) => {
+      surface?.registerPainter(tileId, (next) => {
         setRect((prev) => (sameRect(prev, next) ? prev : next));
         // The shared buffer was cleared if it resized this frame; this pane's
         // own loop has no way to know that.
         sceneCanvas.current?.requestRedraw();
       }),
-    [surface, id],
+    [surface, tileId],
   );
 
   const container = surface?.getContainer() ?? null;

package/src/annotations/Annotations.less

@@ -61,6 +61,12 @@
   cursor: pointer;
 }
 
+// Box and typography come from <Input>. This only says how the field shares
+// the row.
+.lk-mark-list__title {
+  width: 100%;
+}
+
 // The export panel: a target to export, how, and at what resolution. Held in
 // a popover because a mark belongs to a target — with more than one pane,
 // "export" on its own does not say what.

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

@@ -10,7 +10,9 @@
 import { act, render } from '@testing-library/react';
 import { StrictMode, useRef } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TrialIdProvider } from '../state/context';
 import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { AnnotationTargets } from './AnnotationTargets';
 import { createAnnotationStore } from './store';
@@ -140,3 +142,114 @@ describe('<AnnotationTargets>', () => {
     expect(document.querySelectorAll('.lk-annotate__input')).toHaveLength(0);
   });
 });
+
+/** One trial's worth of the harness above: its own pane element, its own
+ *  overlay, and the target id every trial of an instrument shares. */
+function OneTrial({
+  trialId,
+  box,
+}: {
+  trialId: string;
+  box: { left: number; top: number; width: number; height: number };
+}) {
+  const pane = useRef<HTMLDivElement | null>(null);
+  const annotations = useRef(createAnnotationStore({ targets: () => [] })).current;
+  const capability: AnnotationsCapability = {
+    targets: (): AnnotationTarget[] => [{ id: 'pane:a', ref: pane, content: { w: 200, h: 100 } }],
+  };
+  return (
+    <TrialIdProvider trialId={trialId}>
+      <div
+        data-testid={trialId}
+        ref={(el) => {
+          pane.current = el;
+          if (el) stubBox(el, box.left, box.top, box.width, box.height);
+        }}
+      />
+      <AnnotationTargets
+        capability={capability}
+        state={{}}
+        config={{}}
+        annotations={annotations}
+        activeToolId="rect"
+      />
+    </TrialIdProvider>
+  );
+}
+
+describe('two trials of one instrument', () => {
+  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();
+  });
+
+  // An instrument names its regions once, so every trial of it declares the
+  // same target id. Sharing the surface's tile namespace, the trial that opens
+  // second takes the first one's rect, its observer registration and its
+  // painter — and the first is never told it moved again, so it keeps the box
+  // it was measured at while it was the only trial open.
+  it('re-measures a trial that was alone when a second one opens beside it', () => {
+    let handle: SurfaceHandle | null = null;
+
+    function Trials({ second }: { second: boolean }) {
+      const surface = useTiledSurface({ onFrame: () => {} });
+      handle = surface;
+      return (
+        <SurfaceContext.Provider value={surface}>
+          <SurfaceCanvasContext.Provider value={null}>
+            <div
+              ref={(el) => {
+                if (!el) return;
+                stubBox(el, 0, 0, 1200, 700);
+                surface.containerRef(el);
+              }}
+            >
+              <OneTrial
+                trialId="t1"
+                box={{ left: 0, top: 0, width: second ? 476 : 666, height: 639 }}
+              />
+              {second ? (
+                <OneTrial trialId="t2" box={{ left: 500, top: 0, width: 476, height: 639 }} />
+              ) : null}
+            </div>
+          </SurfaceCanvasContext.Provider>
+        </SurfaceContext.Provider>
+      );
+    }
+
+    const boxes = (root: HTMLElement) => [
+      ...root.querySelectorAll<HTMLElement>('.lk-annotate__input'),
+    ];
+    const widths = (root: HTMLElement) =>
+      boxes(root).map((el) => el.style.getPropertyValue('--lk-anno-w'));
+
+    const { container, rerender } = render(<Trials second={false} />, { wrapper: StrictMode });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+    expect(widths(container)).toEqual(['666px']);
+
+    // The grid halves the open trial to make room. jsdom's ResizeObserver never
+    // fires, so this takes `Workspace`'s path — the one it takes anyway for a
+    // tile that moves without resizing, which no observer would have seen.
+    rerender(<Trials second={true} />);
+    act(() => {
+      handle?.invalidateRects();
+      vi.advanceTimersByTime(64);
+    });
+
+    expect(widths(container)).toEqual(['476px', '476px']);
+    expect(boxes(container).map((el) => el.style.getPropertyValue('--lk-anno-x'))).toEqual([
+      '0px',
+      '500px',
+    ]);
+  });
+});

package/src/annotations/MarkList.tsx

@@ -1,3 +1,4 @@
+import { Input } from '../passthrough/weasel-ui';
 import { useAnnotations } from './AnnotationsContext';
 import type { AnnotationMeaning } from './types';
 
@@ -43,12 +44,12 @@ export function MarkList({ meaning, config }: MarkListProps) {
                 ×
               </button>
             </div>
-            <input
+            <Input
               className="lk-mark-list__title"
               aria-label={`Title of ${a.kind} on ${a.target}`}
               value={a.title ?? ''}
               placeholder="Untitled"
-              onChange={(e) => marks.update(a.id, { title: e.target.value })}
+              onChange={(next) => marks.update(a.id, { title: next })}
             />
             {statuses.length > 0 ? (
               // A native select: it carries role, name and keyboard operability

package/src/config/builder.test.ts

@@ -29,6 +29,11 @@ describe('builder', () => {
     });
   });
 
+  it('annotates a number with a display suffix', () => {
+    const n = f.number(20).suffix('px');
+    expect(n.annotations.suffix).toBe('px');
+  });
+
   it('keeps a custom node kind across a chain', () => {
     const n = f.custom('vector2', { x: 0 }).label('Offset');
     expect(n.kind).toBe('vector2');

package/src/config/builder.ts

@@ -90,6 +90,12 @@ class NumberNode extends BaseNode<number> {
     return this.ann({ step });
   }
 
+  /** A display suffix for the value — `'px'`, `'ms'`, `'°'`. Presentation only:
+   *  it is never parsed, and the stored value stays a plain number. */
+  suffix(suffix: string): this {
+    return this.ann({ suffix });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });

package/src/config/types.ts

@@ -24,6 +24,7 @@ export interface Annotations {
   min?: number;
   max?: number;
   step?: number;
+  suffix?: string;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;

package/src/controls/ControlPanel.test.tsx

@@ -420,3 +420,26 @@ describe('<ControlPanel> packing', () => {
     expect(rowOf('Width')?.className).toMatch(/rowInline/);
   });
 });
+
+describe('<ControlPanel> suffix', () => {
+  const panel = (node: ReturnType<typeof f.number>) =>
+    render(
+      <ControlPanel
+        schema={resolveConfigSchema(f.schema({ width: node.label('Width') }), [])}
+        config={{ width: 20 }}
+        setConfig={vi.fn()}
+      />,
+    );
+
+  it('suffixes a slider readout with the suffix the leaf declares', () => {
+    const { container } = panel(f.number(20).range(0, 100).slider().suffix('px'));
+    expect(container.querySelector('input[type="range"]')).not.toBeNull();
+    expect(container.textContent).toContain('px');
+  });
+
+  it('suffixes a typed number with the suffix the leaf declares', () => {
+    const { container } = panel(f.number(20).input().suffix('px'));
+    expect(container.querySelector('input[type="number"]')).not.toBeNull();
+    expect(container.textContent).toContain('px');
+  });
+});

package/src/controls/ControlPanel.tsx

@@ -159,6 +159,7 @@ function ControlRow<TC extends Record<string, unknown>>({
       const min = extra<number>(leaf, 'min');
       const max = extra<number>(leaf, 'max');
       const step = extra<number>(leaf, 'step');
+      const suffix = extra<string>(leaf, 'suffix');
       if (extra<string>(leaf, 'control') === 'slider' && min !== undefined && max !== undefined) {
         return (
           <SliderRow
@@ -167,6 +168,7 @@ function ControlRow<TC extends Record<string, unknown>>({
             min={min}
             max={max}
             step={step}
+            unit={suffix}
             onChange={write}
             layout={layout}
             span={wide}
@@ -186,6 +188,7 @@ function ControlRow<TC extends Record<string, unknown>>({
           min={min}
           max={max}
           step={step}
+          unit={suffix}
           onChange={(n) => write(Math.min(hi, Math.max(lo, n)))}
           layout={layout}
           description={description}

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

@@ -12,7 +12,7 @@ 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 { useSurfaceOptional, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
 import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { Lab } from './Lab';
@@ -39,9 +39,13 @@ beforeAll(() => {
 });
 
 let seen: SurfaceHandle | null | 'not-rendered' = 'not-rendered';
+/** The key the probe's tile is actually registered under: a tile inside a
+ *  trial is scoped by it, and the trial's id is minted by the store. */
+let paneTileId = 'pane';
 
 function Probe() {
   seen = useSurfaceOptional();
+  paneTileId = useTileId('pane');
   const tile = useSurfaceTile('pane');
   return <div data-testid="pane" ref={tile} />;
 }
@@ -146,7 +150,7 @@ describe('<Lab> tile round trip', () => {
 
     act(() => {
       handle?.invalidateRects();
-      handle?.invalidate('pane');
+      handle?.invalidate(paneTileId);
     });
     act(() => {
       vi.advanceTimersByTime(64);
@@ -156,7 +160,8 @@ describe('<Lab> tile round trip', () => {
     // 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(paneTileId).not.toBe('pane');
+    const rect = frames[frames.length - 1]?.rects.get(paneTileId);
     expect(rect).toEqual({ x: 240, y: 100, w: 320, h: 200 });
   });
 });

package/src/lab/LabHeader.test.tsx

@@ -39,4 +39,16 @@ describe('<LabHeader>', () => {
       expect(screen.getByRole('radio', { name: label })).toBeInTheDocument();
     }
   });
+
+  it('draws each color mode as a glyph, with the word only as its name', () => {
+    // The assertion above passes whether the segment holds text or an icon,
+    // because both routes produce the same accessible name. This is the one
+    // that can tell them apart.
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    for (const label of ['Auto', 'Light', 'Dark']) {
+      const segment = screen.getByRole('radio', { name: label });
+      expect(segment.querySelector('svg')).not.toBeNull();
+      expect(segment).toHaveTextContent('');
+    }
+  });
 });

package/src/lab/LabHeader.tsx

@@ -1,14 +1,22 @@
-import { AddIcon } from '@weasel-js/ui';
+import { AddIcon, ModeAutoIcon, ModeDarkIcon, ModeLightIcon } from '@weasel-js/ui';
 import { Select, ToggleBar } from '../passthrough/weasel-ui';
 import type { LabMode } from '../state/types';
 import { useLabContext } from './LabContext';
 
-const MODES: { value: LabMode; label: string }[] = [
-  { value: 'auto', label: 'Auto' },
-  { value: 'light', label: 'Light' },
-  { value: 'dark', label: 'Dark' },
+// The glyph is the segment's content and the word is its accessible name, so
+// the bar stays a three-way radiogroup announcing Auto / Light / Dark.
+const MODES = [
+  { value: 'auto' as LabMode, label: 'Auto', glyph: <ModeAutoIcon size={14} /> },
+  { value: 'light' as LabMode, label: 'Light', glyph: <ModeLightIcon size={14} /> },
+  { value: 'dark' as LabMode, label: 'Dark', glyph: <ModeDarkIcon size={14} /> },
 ];
 
+const MODE_ITEMS = MODES.map(({ value, label, glyph }) => ({
+  value,
+  label: glyph,
+  ariaLabel: label,
+}));
+
 /** The controls `<Lab>` puts in its header: add a trial, and choose the color
  *  mode. Both drive `LabContext`, which carried them with no UI at all — so
  *  every consumer rebuilt these two. Rendered before a consumer's own header
@@ -46,7 +54,9 @@ export function LabHeader() {
       <ToggleBar
         className="lk-lab-header__mode"
         ariaLabel="Color mode"
-        items={MODES}
+        size="sm"
+        variant="flat"
+        items={MODE_ITEMS}
         value={lab.mode}
         onChange={(next) => {
           if (next) lab.setMode(next);

package/src/passthrough/weasel-ui.test.ts

@@ -8,6 +8,8 @@ import {
   Dialog,
   Field,
   formatNumber,
+  ICON_PATHS,
+  Icon,
   Input,
   KeyCap,
   MINUS_SIGN,
@@ -69,6 +71,13 @@ describe('weasel-ui passthrough', () => {
     }
   });
 
+  it('re-exports the icon set, so a lab need not depend on weasel-ui itself', () => {
+    expect(['function', 'object']).toContain(typeof Icon);
+    expect(ICON_PATHS.layoutRows).toContain('<rect');
+    expect(ICON_PATHS.layoutColumns).toContain('<rect');
+    expect(ICON_PATHS.layoutGrid).toContain('<rect');
+  });
+
   it('re-exports app-chrome primitives as React components', () => {
     for (const C of [Sidebar, ToolPalette, KeyCap]) {
       expect(C).toBeDefined();

package/src/passthrough/weasel-ui.ts

@@ -69,6 +69,10 @@ export {
   formatShortcutParts,
   type GradientTrackOpts,
   type GridSettings,
+  ICON_PATHS,
+  Icon,
+  type IconName,
+  type IconProps,
   Input,
   type InputProps,
   type InterpolationMode,

package/src/primitives/ZoomControl.tsx

@@ -45,6 +45,7 @@ export function ZoomControl({
       <Slider
         className="lk-zoom__slider"
         ariaLabel="Zoom"
+        density="slim"
         min={toTrack(min)}
         max={toTrack(max)}
         // Detents at the octaves plus actual size, so 25/50/100/200/400% are
@@ -65,6 +66,7 @@ export function ZoomControl({
         maxValue={max}
         step={0.01}
         hideSteppers
+        ghost
         formatOptions={{ style: 'percent', maximumFractionDigits: 0 }}
         onChange={(next) => {
           if (!Number.isFinite(next)) return;

package/src/state/store.ts

@@ -34,6 +34,7 @@ export interface LabStoreActions {
   updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
   updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
   updateTrialView: (id: string, view: unknown) => void;
+  updateTrialSidebarWidth: (id: string, width: number) => void;
   updateTrialAnnotations: (id: string, doc: unknown) => void;
   updateTrialUndoStack: (
     id: string,
@@ -136,6 +137,15 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
+    updateTrialSidebarWidth: (id, width) => {
+      set((s) => ({
+        trials: s.trials.map((w) =>
+          w.id === id && w.sidebarWidth !== width ? { ...w, sidebarWidth: width } : w,
+        ),
+      }));
+      scheduleFlush();
+    },
+
     updateTrialAnnotations: (id, doc) => {
       set((s) => ({
         trials: s.trials.map((w) =>

package/src/state/types.ts

@@ -18,6 +18,9 @@ export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
   view: TV;
   /** This trial's own tool slot. Undefined means it reads the lab's. */
   activeToolId?: string | null;
+  /** The extent the trial's sidebar was last dragged to, in pixels. Undefined
+   *  until someone moves the seam. */
+  sidebarWidth?: number;
   /** The marks on this trial's annotation targets, as `AnnotationsApi.toJSON`
    *  wrote them. Opaque here, and absent for a trial whose instrument declares
    *  no `annotations` — or declares its own `storage`. Not in `state`, which

package/src/surface/AGENTS.md

@@ -17,7 +17,7 @@ than a few 3D tiles have to share one surface.
 | `deviceRect.ts` | `toDeviceRect` — y-flip and device-grid snapping for a GL viewport |
 | `useTiledSurface.ts` | ResizeObserver, dirty set, rAF coalescing, DPR |
 | `SurfaceContext.ts` | Carries the handle down |
-| `useSurfaceTile.ts` | `useSurfaceTile(id)`, `useSurface()`, `useSurfaceOptional()` |
+| `useSurfaceTile.ts` | `useSurfaceTile(id)`, `useTileId(id)`, `useSurface()`, `useSurfaceOptional()` |
 
 ## Shape of a consumer
 
@@ -40,6 +40,16 @@ const surface = useTiledSurface({
 draw has to know where it is drawing relative to a surface that may have resized
 under it.
 
+## A tile id is scoped to its trial
+
+The tile namespace is one lab-wide map, but an instrument names its regions once
+and every trial of it declares those same names. `useSurfaceTile` registers under
+`useTileId(id)` — `<trial>/<id>` inside a trial — and a frame's `rects` are keyed
+the same way, so a host looking a tile up calls `useTileId` for the key. Unscoped,
+the second trial to mount takes the first one's rect *and* its painter, and the
+first is never told it moved again: it keeps the box it was measured at while it
+was the only trial open.
+
 ## The unit is a rect, not a trial
 
 `useSurfaceTile(id)` attaches to whatever element the surface should draw into. A

package/src/surface/index.ts

@@ -2,7 +2,13 @@ export { composeRects, rectsEqual } from './composeRects';
 export { toDeviceRect } from './deviceRect';
 export type { Box, Rect } from './rect';
 export { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
-export { useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+export {
+  useSurface,
+  useSurfaceCanvas,
+  useSurfaceOptional,
+  useSurfaceTile,
+  useTileId,
+} from './useSurfaceTile';
 export type {
   SurfaceFrame,
   SurfaceHandle,

package/src/surface/useSurfaceTile.ts

@@ -1,4 +1,5 @@
 import { useCallback, useContext } from 'react';
+import { TrialIdContext } from '../state/context';
 import { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
 import type { SurfaceHandle } from './useTiledSurface';
 
@@ -20,19 +21,36 @@ export function useSurface(): SurfaceHandle {
   return surface;
 }
 
+/**
+ * The key `id` is registered under, and so the key it comes back on in a
+ * frame's `rects`: `<trial>/<id>` inside a trial, and `id` alone outside one.
+ *
+ * A surface's tile namespace is flat and shared by the whole lab, but an
+ * instrument names its regions once and every trial of it declares those same
+ * names. Unscoped, the second trial to mount takes the first one's rect and its
+ * painter, and the first is never told it moved again.
+ */
+export function useTileId(id: string): string {
+  const trial = useContext(TrialIdContext);
+  return trial ? `${trial}/${id}` : id;
+}
+
 /**
  * A ref callback that publishes this element's rect to the surface under `id`.
  *
  * Attach it to whichever element the surface should draw into — that is not
  * necessarily the trial's own element, since a trial may hold a drawn pane beside
  * an undrawn one, or none at all.
+ *
+ * The frame reports it under `useTileId(id)`, not under `id`.
  */
 export function useSurfaceTile(id: string): (el: HTMLElement | null) => void {
   const surface = useSurfaceOptional();
+  const tileId = useTileId(id);
   return useCallback(
     (el: HTMLElement | null) => {
-      surface?.registerTile(id, el);
+      surface?.registerTile(tileId, el);
     },
-    [surface, id],
+    [surface, tileId],
   );
 }

package/src/surface/useTiledSurface.ts

@@ -5,7 +5,10 @@ import type { Box, Rect } from './rect';
 
 /** What a surface owner is handed once per animation frame. `rects` carries every
  *  tile, not only the dirty ones: a scissored draw has to know where it is drawing
- *  relative to a surface that may have resized under it. */
+ *  relative to a surface that may have resized under it.
+ *
+ *  Its keys are what `useTileId` returns — `<trial>/<id>` for a tile registered
+ *  inside a trial — not the bare id the tile was named with. */
 export interface SurfaceFrame {
   dirty: ReadonlySet<string>;
   rects: ReadonlyMap<string, Rect>;

package/src/theme/Interstellar.stories.tsx

@@ -91,11 +91,12 @@ function SwatchGrid({ tokens, title }: { tokens: readonly Swatch[]; title: strin
 function NebulaPreview() {
   return (
     <div>
-      <h3 className="lk-theme-doc__heading">Cosmic backdrop (`--wzl-backdrop`)</h3>
+      <h3 className="lk-theme-doc__heading">Cosmic backdrop</h3>
       <div className="lk-theme-doc__nebula" style={{ background: 'var(--wzl-backdrop)' }} />
       <p className="lk-theme-doc__note">
-        Default: four radial gradients (purple, pink, blue, then a dark void base). Override per-Lab
-        by passing <code>nebula={'{[colors]}'}</code> to the <code>&lt;Lab&gt;</code> component.
+        <code>--wzl-backdrop</code> — four radial gradients (purple, pink, blue) over a dark void
+        base. Override per-Lab by passing <code>nebula={'{[colors]}'}</code> to the{' '}
+        <code>&lt;Lab&gt;</code> component.
       </p>
     </div>
   );