@weasel-js/labkit 1.0.4 → 1.2.0

package/src/lab/LabContext.ts

@@ -1,21 +1,21 @@
 import { createContext, useContext } from 'react';
-import type { Instrument } from '../instrument/types';
-import type { LabMode, SavedSnapshot, WorkspaceRecord } from '../state/types';
+import type { InstrumentList } from '../instrument/types';
+import type { LabMode, SavedSnapshot, TrialRecord } from '../state/types';
 
 /** Lab-wide state and commands: the available instruments, the open
- *  workspaces and the operations over them, saved snapshots, and the color
+ *  trials and the operations over them, saved snapshots, and the color
  *  mode. */
 export interface LabContextValue {
-  instruments: Instrument[];
-  workspaces: WorkspaceRecord[];
-  addWorkspace: (instrumentName: string) => void;
-  cloneWorkspace: (id: string) => void;
-  closeWorkspace: (id: string) => void;
-  resetWorkspace: (id: string) => void;
-  reorderWorkspaces: (ids: readonly string[]) => void;
+  instruments: InstrumentList;
+  trials: TrialRecord[];
+  addTrial: (instrumentName: string) => void;
+  cloneTrial: (id: string) => void;
+  closeTrial: (id: string) => void;
+  resetTrial: (id: string) => void;
+  reorderTrials: (ids: readonly string[]) => void;
   savedSnapshots: SavedSnapshot[];
-  saveSnapshot: (workspaceId: string, name?: string) => void;
-  loadSnapshot: (workspaceId: string, snapshotId: string) => void;
+  saveSnapshot: (trialId: string, name?: string) => void;
+  loadSnapshot: (trialId: string, snapshotId: string) => void;
   deleteSnapshot: (snapshotId: string) => void;
   mode: LabMode;
   setMode: (m: LabMode) => void;

package/src/lab/LabShell.tsx

@@ -18,7 +18,7 @@ export interface LabShellProps {
 
 /** Page frame for a lab: a titled header, a body, and an optional footer,
  *  themed for the resolved color mode. Presentational only — use `<Lab>` when
- *  the workspace runtime is wanted too. */
+ *  the trial runtime is wanted too. */
 export function LabShell({ title, children, header, footer, mode = 'auto' }: LabShellProps) {
   const resolved = useResolvedMode(mode);
   const outer = useThemeOptional();

package/src/lab/{WorkspaceGrid.less → Workspace.less}

@@ -1,13 +1,13 @@
 // Tiles are positioned by windease at strategy-computed rects; `.windease-zone`
 // (from windease/styles.css) supplies the containing block and the 100% box.
 // This class exists for consumers to target.
-.lk-workspace-grid {
+.lk-workspace {
   min-height: 0;
 }
 
 // Only rendered when `reorderable` — a tile is full of controls, so the drag
 // target has to be its own strip rather than the whole pane.
-.lk-workspace-tile {
+.lk-trial-tile {
   display: flex;
   flex-direction: column;
   height: 100%;

package/src/lab/{WorkspaceGrid.stories.tsx → Workspace.stories.tsx}

@@ -1,13 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { WorkspaceGrid } from './WorkspaceGrid';
+import { Workspace } from './Workspace';
 
-const meta: Meta<typeof WorkspaceGrid> = {
-  title: 'labkit/Lab/WorkspaceGrid',
-  component: WorkspaceGrid,
+const meta: Meta<typeof Workspace> = {
+  title: 'labkit/Lab/Workspace',
+  component: Workspace,
 };
 export default meta;
 
-type Story = StoryObj<typeof WorkspaceGrid>;
+type Story = StoryObj<typeof Workspace>;
 
 const Tile = ({ children }: { children: React.ReactNode }) => (
   <div
@@ -28,9 +28,9 @@ const Tile = ({ children }: { children: React.ReactNode }) => (
 export const OneTile: Story = {
   render: () => (
     <div style={{ height: 400 }}>
-      <WorkspaceGrid>
+      <Workspace>
         <Tile>1</Tile>
-      </WorkspaceGrid>
+      </Workspace>
     </div>
   ),
 };
@@ -38,11 +38,11 @@ export const OneTile: Story = {
 export const ThreeTiles: Story = {
   render: () => (
     <div style={{ height: 400 }}>
-      <WorkspaceGrid>
+      <Workspace>
         <Tile>1</Tile>
         <Tile>2</Tile>
         <Tile>3</Tile>
-      </WorkspaceGrid>
+      </Workspace>
     </div>
   ),
 };
@@ -50,12 +50,12 @@ export const ThreeTiles: Story = {
 export const SevenTiles: Story = {
   render: () => (
     <div style={{ height: 600 }}>
-      <WorkspaceGrid>
+      <Workspace>
         {Array.from({ length: 7 }).map((_, i) => (
           // biome-ignore lint/suspicious/noArrayIndexKey: static demo list
           <Tile key={i}>{i + 1}</Tile>
         ))}
-      </WorkspaceGrid>
+      </Workspace>
     </div>
   ),
 };
@@ -65,13 +65,13 @@ export const SevenTiles: Story = {
 export const Resizable: Story = {
   render: () => (
     <div style={{ height: 500 }}>
-      <WorkspaceGrid ids={['a', 'b', 'c', 'd', 'e']} resizable>
+      <Workspace ids={['a', 'b', 'c', 'd', 'e']} resizable>
         <Tile>1</Tile>
         <Tile>2</Tile>
         <Tile>3</Tile>
         <Tile>4</Tile>
         <Tile>5</Tile>
-      </WorkspaceGrid>
+      </Workspace>
     </div>
   ),
 };

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

@@ -0,0 +1,49 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
+import { Workspace } from './Workspace';
+
+function fakeHandle(): SurfaceHandle {
+  return {
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    invalidateRects: vi.fn(),
+    registerTile: vi.fn(),
+    containerRef: vi.fn(),
+  };
+}
+
+describe('Workspace with a surface above it', () => {
+  it('invalidates rects when the tile set changes, because a re-tile moves tiles', () => {
+    const handle = fakeHandle();
+    const { rerender } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+    (handle.invalidateRects as ReturnType<typeof vi.fn>).mockClear();
+
+    rerender(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a', 'b']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+          <div>b</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+
+    expect(handle.invalidateRects).toHaveBeenCalled();
+  });
+
+  it('renders unchanged with no surface above it', () => {
+    const { getByText } = render(
+      <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+        <div>a</div>
+      </Workspace>,
+    );
+    expect(getByText('a')).toBeInTheDocument();
+  });
+});

package/src/lab/{WorkspaceGrid.test.tsx → Workspace.test.tsx}

@@ -1,17 +1,17 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, test, vi } from 'vitest';
-import { WorkspaceGrid } from './WorkspaceGrid';
+import { Workspace } from './Workspace';
 
 const VIEWPORT = { w: 800, h: 600 };
 
-describe('WorkspaceGrid', () => {
+describe('Workspace', () => {
   test('renders all children', () => {
     render(
-      <WorkspaceGrid viewport={VIEWPORT}>
+      <Workspace viewport={VIEWPORT}>
         <div>one</div>
         <div>two</div>
         <div>three</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     expect(screen.getByText('one')).toBeInTheDocument();
     expect(screen.getByText('two')).toBeInTheDocument();
@@ -21,54 +21,54 @@ describe('WorkspaceGrid', () => {
   test('keeps a child with the tile its id names when an earlier one closes', () => {
     const ids = ['a', 'b', 'c'];
     const { rerender, container } = render(
-      <WorkspaceGrid ids={ids} viewport={VIEWPORT}>
+      <Workspace ids={ids} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
         <div>c</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
 
     rerender(
-      <WorkspaceGrid ids={['b', 'c']} viewport={VIEWPORT}>
+      <Workspace ids={['b', 'c']} viewport={VIEWPORT}>
         <div>b</div>
         <div>c</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
     expect(container.querySelector('[data-node="a"]')).toBeNull();
   });
 
-  test('uses lk-workspace-grid class', () => {
+  test('uses lk-workspace class', () => {
     const { container } = render(
-      <WorkspaceGrid viewport={VIEWPORT}>
+      <Workspace viewport={VIEWPORT}>
         <div />
-      </WorkspaceGrid>,
+      </Workspace>,
     );
-    expect((container.firstChild as HTMLElement).className).toContain('lk-workspace-grid');
+    expect((container.firstChild as HTMLElement).className).toContain('lk-workspace');
   });
 
   test('renders resize affordances only when resizable', () => {
     const { container, rerender } = render(
-      <WorkspaceGrid ids={['a', 'b']} viewport={VIEWPORT}>
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     expect(container.querySelectorAll('[role="separator"]')).toHaveLength(0);
 
     rerender(
-      <WorkspaceGrid ids={['a', 'b']} resizable viewport={VIEWPORT}>
+      <Workspace ids={['a', 'b']} resizable viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     expect(container.querySelectorAll('[role="separator"]').length).toBeGreaterThan(0);
   });
 
   test('applies a saved extent to a tile as it registers', () => {
     const { container } = render(
-      <WorkspaceGrid
+      <Workspace
         ids={['a', 'b']}
         resizable
         viewport={VIEWPORT}
@@ -76,7 +76,7 @@ describe('WorkspaceGrid', () => {
       >
         <div>a</div>
         <div>b</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     const a = container.querySelector('[data-node="a"]') as HTMLElement;
     const b = container.querySelector('[data-node="b"]') as HTMLElement;
@@ -87,14 +87,14 @@ describe('WorkspaceGrid', () => {
   test('reports the order a drop would produce instead of applying it', () => {
     const onReorder = vi.fn();
     const { container } = render(
-      <WorkspaceGrid ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
+      <Workspace ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
     // The grid is controlled: it renders a handle per tile and commits nothing
     // itself. Order still comes from `ids`.
-    expect(container.querySelectorAll('.lk-workspace-tile__grip')).toHaveLength(2);
+    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(2);
     expect(onReorder).not.toHaveBeenCalled();
     const nodes = [...container.querySelectorAll('[data-node]')].map((el) =>
       el.getAttribute('data-node'),
@@ -104,11 +104,11 @@ describe('WorkspaceGrid', () => {
 
   test('renders no drag handles unless reorderable', () => {
     const { container } = render(
-      <WorkspaceGrid ids={['a', 'b']} viewport={VIEWPORT}>
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
-      </WorkspaceGrid>,
+      </Workspace>,
     );
-    expect(container.querySelectorAll('.lk-workspace-tile__grip')).toHaveLength(0);
+    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(0);
   });
 });

package/src/lab/{WorkspaceGrid.tsx → Workspace.tsx}

@@ -17,18 +17,20 @@ import {
   StrategyRegistryProvider,
 } from 'windease/react';
 
-const ZONE_ID = asNodeId('lk-workspaces');
+import { useSurfaceOptional } from '../surface/useSurfaceTile';
+
+const ZONE_ID = asNodeId('lk-workspace');
 const STRATEGIES = { grid: gridStrategy as never };
-const KIND = 'workspace';
+const KIND = 'trial';
 
 /** A tile's persisted extent, keyed by the id its caller gave it. Grid resizes
  *  write `span`; `size` is here because a strategy swap would write that. */
-export type WorkspaceLayout = Record<
+export type TrialLayout = Record<
   string,
   { size?: { w?: number; h?: number }; span?: { cols?: number; rows?: number } }
 >;
 
-export interface WorkspaceGridProps {
+export interface WorkspaceProps {
   children: ReactNode;
   /**
    * Stable id per child, positionally matched. Supply these whenever a tile
@@ -48,10 +50,10 @@ export interface WorkspaceGridProps {
   /** The full id list a drop would produce, in its new order. */
   onReorder?: (ids: string[]) => void;
   /** Extents from a previous session, applied to tiles as they register. */
-  layout?: WorkspaceLayout;
+  layout?: TrialLayout;
   /** Fires when a tile's extent changes. Persist it and hand it back as
    *  `layout` to make a resize survive a reload. */
-  onLayoutChange?: (layout: WorkspaceLayout) => void;
+  onLayoutChange?: (layout: TrialLayout) => void;
   gap?: number;
   padding?: number;
   /**
@@ -62,23 +64,23 @@ export interface WorkspaceGridProps {
   viewport?: { w: number; h: number };
 }
 
-function extentOf(store: Store, id: NodeId): WorkspaceLayout[string] | null {
-  const p = store.getNode(id)?.membership?.placement as WorkspaceLayout[string] | undefined;
+function extentOf(store: Store, id: NodeId): TrialLayout[string] | null {
+  const p = store.getNode(id)?.membership?.placement as TrialLayout[string] | undefined;
   if (!p) return null;
-  const out: WorkspaceLayout[string] = {};
+  const out: TrialLayout[string] = {};
   if (p.size) out.size = p.size;
   if (p.span) out.span = p.span;
   return Object.keys(out).length > 0 ? out : null;
 }
 
 /**
- * Auto-balanced tiling of workspaces, `ceil(sqrt(n))` columns wide.
+ * Auto-balanced tiling of trials, `ceil(sqrt(n))` columns wide.
  *
  * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
  * laid out by CSS — `windease/styles.css` (folded into
  * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
  */
-export function WorkspaceGrid({
+export function Workspace({
   children,
   ids,
   resizable = false,
@@ -89,11 +91,11 @@ export function WorkspaceGrid({
   gap = 12,
   padding = 0,
   viewport,
-}: WorkspaceGridProps) {
+}: WorkspaceProps) {
   const items = Children.toArray(children);
   const idKey = ids ? ids.join(',') : `#${items.length}`;
   // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
-  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]);
+  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Held in refs rather than depended on: a fresh object each render would
   // re-run the sync effect, and only a newly registered tile reads `layout`.
@@ -119,6 +121,10 @@ export function WorkspaceGrid({
   }
   const store = storeRef.current;
 
+  // A tile that only moves reports nothing to a ResizeObserver, and only this
+  // component knows the grid moved one. Optional: a lab may own no surface.
+  const surface = useSurfaceOptional();
+
   useLayoutEffect(() => {
     store.updateContainerConfig(ZONE_ID, { resizable, gap, padding });
   }, [store, resizable, gap, padding]);
@@ -139,10 +145,17 @@ export function WorkspaceGrid({
     store.setChildOrder(ZONE_ID, [...nodeIds]);
   }, [store, nodeIds]);
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: nodeIds is the signal that the tile set changed — a re-tile moves tiles without resizing any — not a value this reads
+  useEffect(() => {
+    if (!surface) return;
+    surface.invalidateRects();
+    return store.events.on('node.placementChanged', () => surface.invalidateRects());
+  }, [store, surface, nodeIds]); // eslint-disable-line react-hooks/exhaustive-deps
+
   useEffect(() => {
     if (!onLayoutChange) return;
     return store.events.on('node.placementChanged', () => {
-      const next: WorkspaceLayout = {};
+      const next: TrialLayout = {};
       for (const child of store.getChildren(ZONE_ID)) {
         const extent = extentOf(store, child.id);
         if (extent) next[child.id] = extent;
@@ -164,11 +177,11 @@ export function WorkspaceGrid({
         if (!reorderable) return content;
         // A tile is full of controls, so the whole thing can't be the handle.
         return (
-          <div className="lk-workspace-tile">
-            <DragHandle nodeId={node.id} className="lk-workspace-tile__grip">
-              <span className="lk-workspace-tile__grip-dots" aria-hidden="true" />
+          <div className="lk-trial-tile">
+            <DragHandle nodeId={node.id} className="lk-trial-tile__grip">
+              <span className="lk-trial-tile__grip-dots" aria-hidden="true" />
             </DragHandle>
-            <div className="lk-workspace-tile__body">{content}</div>
+            <div className="lk-trial-tile__body">{content}</div>
           </div>
         );
       },
@@ -179,7 +192,7 @@ export function WorkspaceGrid({
     <Container
       parentId={ZONE_ID}
       chrome={chrome}
-      className="lk-workspace-grid windease-zone"
+      className="lk-workspace windease-zone"
       affordances={resizable}
       viewport={viewport}
       onChildOrderChange={reorderable ? commitOrder : undefined}

package/src/lab/index.ts

@@ -4,5 +4,5 @@ export type { LabContextValue } from './LabContext';
 export { LabContext, useLabContext } from './LabContext';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
-export type { WorkspaceGridProps } from './WorkspaceGrid';
-export { WorkspaceGrid } from './WorkspaceGrid';
+export type { WorkspaceProps } from './Workspace';
+export { Workspace } from './Workspace';

package/src/layers/AGENTS.md

@@ -31,9 +31,9 @@ The instrument declares layer ids:
 layers: { ids: ['grid', 'plants'] }
 ```
 
-`Workspace.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
+`Trial.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
 
-There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the workspace assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
+There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the trial assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
 
 ## `alwaysOn` semantics
 
@@ -52,7 +52,7 @@ Pointer capture is acquired on `pointerdown` and released on `pointerup`, so dra
 
 ## Empty state
 
-If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Workspace already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
+If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Trial already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
 
 ## When to fork
 

package/src/primitives/Toolbar.stories.tsx

@@ -12,7 +12,7 @@ type Story = StoryObj<typeof Toolbar>;
 export const Default: Story = {
   render: () => (
     <Toolbar>
-      <Toolbar.Title>My Workspace</Toolbar.Title>
+      <Toolbar.Title>My Trial</Toolbar.Title>
       <Toolbar.Button onClick={() => {}}>Undo</Toolbar.Button>
       <Toolbar.Button onClick={() => {}}>Redo</Toolbar.Button>
       <Toolbar.Spacer />
@@ -24,7 +24,7 @@ export const Default: Story = {
 export const WithDisabled: Story = {
   render: () => (
     <Toolbar>
-      <Toolbar.Title>Empty workspace</Toolbar.Title>
+      <Toolbar.Title>Empty trial</Toolbar.Title>
       <Toolbar.Button onClick={() => {}} disabled>
         Undo
       </Toolbar.Button>

package/src/state/SingletonExperiment.test.tsx

@@ -1,8 +1,9 @@
 import { act, render, renderHook } from '@testing-library/react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createMemoryAdapter } from './adapters';
+import { labDocumentKey } from './document';
 import { SingletonExperimentProvider } from './SingletonExperiment';
-import { useExperimentState } from './useExperimentState';
+import { useTrialState } from './useTrialState';
 
 interface Config {
   width: number;
@@ -17,7 +18,7 @@ describe('SingletonExperimentProvider', () => {
     vi.useRealTimers();
   });
 
-  it('exposes config and state via useExperimentState', () => {
+  it('exposes config and state via useTrialState', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <SingletonExperimentProvider<State, Config>
         id="test"
@@ -29,7 +30,7 @@ describe('SingletonExperimentProvider', () => {
         {children}
       </SingletonExperimentProvider>
     );
-    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
     expect(result.current.config).toEqual({ width: 100, bg: '#000' });
     expect(result.current.state).toEqual({ zoom: 1 });
   });
@@ -38,7 +39,7 @@ describe('SingletonExperimentProvider', () => {
     vi.useFakeTimers();
     const storage = createMemoryAdapter();
     const Probe = () => {
-      const h = useExperimentState<State, Config>();
+      const h = useTrialState<State, Config>();
       return (
         <button type="button" onClick={() => h.setConfig('width', 200)}>
           go
@@ -62,15 +63,14 @@ describe('SingletonExperimentProvider', () => {
     act(() => {
       vi.advanceTimersByTime(400);
     });
-    // createLabStore uses labStorageKey which prefixes with "lk:"
-    const raw = storage.read('lk:test:workspaces');
+    const raw = storage.read(labDocumentKey('test'));
     expect(raw).toBeTruthy();
     expect(raw).toContain('"width":200');
   });
 
   it('rehydrates from storage on mount', () => {
     const storage = createMemoryAdapter();
-    // createLabStore uses labStorageKey which prefixes with "lk:"
+    // A pre-document lab, which createLabStore folds forward on hydration.
     storage.write(
       'lk:test:workspaces',
       JSON.stringify([
@@ -94,7 +94,7 @@ describe('SingletonExperimentProvider', () => {
         {children}
       </SingletonExperimentProvider>
     );
-    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
     expect(result.current.config).toEqual({ width: 999, bg: '#fff' });
     expect(result.current.state).toEqual({ zoom: 2 });
   });

package/src/state/SingletonExperiment.tsx

@@ -1,5 +1,5 @@
 import { type ReactNode, useRef } from 'react';
-import { LabStoreProvider, WorkspaceIdProvider } from './context';
+import { LabStoreProvider, TrialIdProvider } from './context';
 import { createLabStore, type LabStore } from './store';
 import type { StorageAdapter } from './types';
 
@@ -7,8 +7,8 @@ const SINGLETON_INSTRUMENT = '__singleton__';
 
 /** Props for `<SingletonExperimentProvider>`. */
 export interface SingletonExperimentProviderProps<TS, TC> {
-  /** Stable id for the synthetic workspace; also doubles as the
-   *  WorkspaceIdContext value. */
+  /** Stable id for the synthetic trial; also doubles as the
+   *  TrialIdContext value. */
   id: string;
   initialConfig: TC;
   initialState: TS;
@@ -18,9 +18,9 @@ export interface SingletonExperimentProviderProps<TS, TC> {
 }
 
 /**
- * One-workspace `<Lab>` substitute for single-screen experiments. Mounts
- * a `LabStoreProvider` + `WorkspaceIdProvider` with one synthetic
- * workspace, so `useExperimentState` works without going through the
+ * One-trial `<Lab>` substitute for single-screen experiments. Mounts
+ * a `LabStoreProvider` + `TrialIdProvider` with one synthetic
+ * trial, so `useTrialState` works without going through the
  * full `<Lab instruments={...}>` runtime.
  */
 export function SingletonExperimentProvider<TS, TC>({
@@ -34,8 +34,8 @@ export function SingletonExperimentProvider<TS, TC>({
   const storeRef = useRef<LabStore | null>(null);
   if (storeRef.current === null) {
     const store = createLabStore({ storageKey, storage });
-    if (!store.getState().workspaces.some((w) => w.id === id)) {
-      store.getState().addWorkspace({
+    if (!store.getState().trials.some((w) => w.id === id)) {
+      store.getState().addTrial({
         id,
         instrumentName: SINGLETON_INSTRUMENT,
         config: initialConfig,
@@ -47,7 +47,7 @@ export function SingletonExperimentProvider<TS, TC>({
   }
   return (
     <LabStoreProvider store={storeRef.current}>
-      <WorkspaceIdProvider workspaceId={id}>{children}</WorkspaceIdProvider>
+      <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
     </LabStoreProvider>
   );
 }

package/src/state/context.tsx

@@ -27,25 +27,25 @@ export function useLabStore(): LabStoreState & ReturnType<LabStore['getState']>
   return useStore(ctx.store);
 }
 
-/** Context carrying which workspace the subtree belongs to. */
-export const WorkspaceIdContext = createContext<string | null>(null);
+/** Context carrying which trial the subtree belongs to. */
+export const TrialIdContext = createContext<string | null>(null);
 
-/** Names the workspace its subtree belongs to, so an instrument's hooks can
+/** Names the trial its subtree belongs to, so an instrument's hooks can
  *  find their own record in the store without being passed an id. */
-export function WorkspaceIdProvider({
-  workspaceId,
+export function TrialIdProvider({
+  trialId,
   children,
 }: {
-  workspaceId: string;
+  trialId: string;
   children: ReactNode;
 }): ReactElement {
-  return <WorkspaceIdContext.Provider value={workspaceId}>{children}</WorkspaceIdContext.Provider>;
+  return <TrialIdContext.Provider value={trialId}>{children}</TrialIdContext.Provider>;
 }
 
-/** The id of the workspace this component is inside. Throws outside a
- *  `<WorkspaceIdProvider>`. */
-export function useWorkspaceId(): string {
-  const id = useContext(WorkspaceIdContext);
-  if (!id) throw new Error('[labkit] useWorkspaceId must be used inside <WorkspaceIdProvider>');
+/** The id of the trial this component is inside. Throws outside a
+ *  `<TrialIdProvider>`. */
+export function useTrialId(): string {
+  const id = useContext(TrialIdContext);
+  if (!id) throw new Error('[labkit] useTrialId must be used inside <TrialIdProvider>');
   return id;
 }