@weasel-js/labkit 1.4.4 → 1.5.1

package/src/trial/Trial.annotations.persist.test.tsx

@@ -4,15 +4,16 @@
  * is written on a trailing debounce: a write per scene notification re-renders
  * every trial on every frame of a drag.
  */
-import { act, render } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { useAnnotations } from '../annotations/AnnotationsContext';
 import type { AnnotationsApi, SerializedAnnotations } from '../annotations/types';
 import { defineInstrument } from '../instrument/defineInstrument';
 import type { InstrumentList } from '../instrument/types';
 import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
 import { createMemoryAdapter } from '../state/adapters';
-import type { StorageAdapter } from '../state/types';
+import { labPrefix } from '../state/labRecords';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(
@@ -21,12 +22,24 @@ beforeAll(() => {
 });
 
 let api: AnnotationsApi | null = null;
+let lab: LabContextValue | null = null;
 
 function Pane() {
   api = useAnnotations();
   return <div data-testid="pane" />;
 }
 
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        lab = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
 /** Read through a call, so TypeScript does not narrow the module-level `api`
  *  to `null` across the remounts these tests are about. */
 function marks(): AnnotationsApi {
@@ -46,6 +59,8 @@ const inspector = defineInstrument<Record<string, never>, { angle: number }>({
 
 /** The instrument keeps its own marks, so labkit must not keep them too. */
 let owned: SerializedAnnotations | null = null;
+let loads = 0;
+let gate: Promise<void> = Promise.resolve();
 const selfStoring = defineInstrument<Record<string, never>, Record<string, never>>({
   name: 'SelfStoring',
   defaultConfig: () => ({}),
@@ -54,7 +69,11 @@ const selfStoring = defineInstrument<Record<string, never>, Record<string, never
   annotations: {
     targets: () => [TARGET],
     storage: {
-      load: () => owned,
+      load: async () => {
+        loads++;
+        await gate;
+        return owned;
+      },
       save: (doc) => {
         owned = doc;
       },
@@ -62,42 +81,51 @@ const selfStoring = defineInstrument<Record<string, never>, Record<string, never
   },
 });
 
-function mount(storage: StorageAdapter, which: InstrumentList[number] = inspector) {
-  return render(
+async function mount(backing: Map<string, unknown>, which: InstrumentList[number] = inspector) {
+  api = null;
+  const view = render(
     <Lab
       instruments={[which]}
       defaultInstrument={which.name}
-      storage={storage}
+      storage={createMemoryAdapter(backing)}
       storageKey="persist-test"
-    />,
+    >
+      <CaptureLab />
+    </Lab>,
   );
+  await waitFor(() => expect(api).not.toBeNull());
+  return view;
+}
+
+function storedTrial(backing: Map<string, unknown>): Record<string, unknown> | undefined {
+  const prefix = `${labPrefix('persist-test')}trial:`;
+  return [...backing].find(([key]) => key.startsWith(prefix))?.[1] as
+    | Record<string, unknown>
+    | undefined;
 }
 
 const MARK = { target: 'pane', kind: 'rect' as const, frac: { x: 0.2, y: 0.3, w: 0.1, h: 0.1 } };
 
 describe('a trial that persists its marks', () => {
   beforeEach(() => {
-    vi.useFakeTimers();
     api = null;
+    lab = null;
     owned = null;
+    loads = 0;
+    gate = Promise.resolve();
   });
   afterEach(() => {
     vi.useRealTimers();
   });
 
-  it('brings them back on a remount from the same storage', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('brings them back on a remount from the same storage', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing);
     const id = marks().add(MARK, { angle: 12 });
-
-    // Past both debounces: labkit's write-back, then the document flush.
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
     first.unmount();
+    await waitFor(() => expect(storedTrial(backing)?.annotations).toBeDefined());
 
-    api = null;
-    mount(storage);
+    await mount(backing);
     const back = marks().get(id);
     expect(back).toMatchObject({ id, target: 'pane', kind: 'rect', frac: MARK.frac });
     // The staleness snapshot has to survive too, or every restored mark reads
@@ -107,60 +135,74 @@ describe('a trial that persists its marks', () => {
     expect(marks().isStale(back, { angle: 45 })).toBe(true);
   });
 
-  it('writes nothing before the debounce elapses', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('keeps a mark out of storage until both debounces pass, while the lab stays open', async () => {
+    const backing = new Map<string, unknown>();
+    await mount(backing);
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
     marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(20);
-    });
-    first.unmount();
-
-    api = null;
-    mount(storage);
-    // Not a claim about the debounce interval — a claim that one exists, and
-    // that a store write is not synchronous with a scene notification.
-    //
-    // It is also the no-migration claim: the document this remount reads was
-    // written with trials and no `annotations` field, exactly as every
-    // document from before this arc is, and the trial opens on an empty store
-    // rather than failing to load.
-    expect(marks().query()).toHaveLength(0);
+    await act(() => vi.advanceTimersByTimeAsync(20));
+    // Not a claim about either interval — a claim that a store write is not
+    // synchronous with a scene notification.
+    expect(storedTrial(backing)?.annotations).toBeUndefined();
+    await act(() => vi.advanceTimersByTimeAsync(2000));
+    expect(storedTrial(backing)?.annotations).toBeDefined();
   });
 
-  it('flushes on unmount, so the last mark before a close is not lost', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage);
+  it('flushes on unmount, so the last mark before a close is not lost', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing);
     const id = marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     marks().add({ ...MARK, frac: { x: 0.6, y: 0.6, w: 0.1, h: 0.1 } });
     first.unmount();
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
+    // Nothing was written before the unmount: neither debounce had elapsed.
+    await waitFor(() => expect(storedTrial(backing)?.annotations).toBeDefined());
 
-    api = null;
-    mount(storage);
+    await mount(backing);
     expect(marks().query()).toHaveLength(2);
     expect(marks().get(id)).toBeDefined();
   });
 
-  it('leaves the slot alone when the instrument owns the storage', () => {
-    const storage = createMemoryAdapter();
-    const first = mount(storage, selfStoring);
+  it('leaves the slot alone when the instrument owns the storage', async () => {
+    const backing = new Map<string, unknown>();
+    const first = await mount(backing, selfStoring);
     marks().add(MARK);
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
     first.unmount();
+    await waitFor(() => expect(owned?.version).toBe(1));
+    await waitFor(() => expect(storedTrial(backing)).toBeDefined());
+    expect(storedTrial(backing)).not.toHaveProperty('annotations');
 
-    expect(owned?.version).toBe(1);
-    expect(storage.read('lk:persist-test:doc')).not.toContain('"annotations"');
-
-    api = null;
-    mount(storage, selfStoring);
+    await mount(backing, selfStoring);
     expect(marks().query()).toHaveLength(1);
   });
+
+  it('loads instrument-owned marks before the lab shows, and a later trial before its body', async () => {
+    const backing = new Map<string, unknown>();
+    let release = (): void => {};
+    gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    render(
+      <Lab
+        instruments={[selfStoring]}
+        defaultInstrument="SelfStoring"
+        storage={createMemoryAdapter(backing)}
+        storageKey="persist-test"
+      >
+        <CaptureLab />
+      </Lab>,
+    );
+    await waitFor(() => expect(loads).toBe(1));
+    expect(screen.queryByTestId('pane')).toBeNull();
+    await act(async () => release());
+    expect(await screen.findByTestId('pane')).toBeInTheDocument();
+
+    gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    act(() => lab?.addTrial('SelfStoring'));
+    expect(document.querySelectorAll('.lk-trial--loading')).toHaveLength(1);
+    await act(async () => release());
+    await waitFor(() => expect(screen.getAllByTestId('pane')).toHaveLength(2));
+    expect(loads).toBe(2);
+  });
 });

package/src/trial/Trial.annotations.test.tsx

@@ -4,12 +4,13 @@
  * follow. The overlay's own geometry is covered in
  * `annotations/Annotations.overlay.test.tsx`.
  */
-import { act, fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen, within } from '@testing-library/react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { useAnnotations, useAnnotationsOptional } from '../annotations/AnnotationsContext';
 import type { AnnotationsApi } from '../annotations/types';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(
@@ -19,9 +20,9 @@ beforeAll(() => {
 
 let api: AnnotationsApi | null = null;
 
-function Pane() {
+function Pane({ tool }: { tool: string | null }) {
   api = useAnnotations();
-  return <div data-testid="pane" data-marks={api.query().length} />;
+  return <div data-testid="pane" data-marks={api.query().length} data-tool={tool ?? ''} />;
 }
 
 function marks(): AnnotationsApi {
@@ -33,7 +34,7 @@ const annotating = defineInstrument<Record<string, never>, Record<string, never>
   name: 'Annotating',
   defaultConfig: () => ({}),
   initialState: () => ({}),
-  render: () => <Pane />,
+  render: (ctx) => <Pane tool={ctx.trial.activeToolId} />,
   annotations: {
     targets: () => [{ id: 'pane', ref: { current: null }, content: { w: 200, h: 100 } }],
   },
@@ -54,7 +55,16 @@ const plain = defineInstrument<Record<string, never>, Record<string, never>>({
 describe('an instrument that declares annotations', () => {
   it('gets a drawing palette', () => {
     render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
-    for (const label of ['Select', 'Freehand', 'Line', 'Arrow', 'Rectangle', 'Ellipse', 'Text']) {
+    for (const label of [
+      'Interact',
+      'Select',
+      'Freehand',
+      'Line',
+      'Arrow',
+      'Rectangle',
+      'Ellipse',
+      'Text',
+    ]) {
       expect(screen.getByRole('button', { name: label })).toBeTruthy();
     }
   });
@@ -64,14 +74,56 @@ describe('an instrument that declares annotations', () => {
     expect(screen.getByTestId('pane').dataset.marks).toBe('0');
   });
 
-  it('starts in select, so a first click does not draw', () => {
+  it('starts in interact, so a first click reaches the instrument', () => {
     render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
-    expect(screen.getByRole('button', { name: 'Select' }).getAttribute('aria-current')).toBe(
+    expect(screen.getByRole('button', { name: 'Interact' }).getAttribute('aria-current')).toBe(
       'true',
     );
   });
 });
 
+let labRef: LabContextValue | null = null;
+
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        if (value) labRef = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+describe('the annotation tool', () => {
+  it("is offered in the lab's rail, not in a trial's", () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getAllByRole('button', { name: 'Rectangle' })).toHaveLength(1);
+    const trial = screen.getByRole('region', { name: /trial/i });
+    expect(within(trial).queryByRole('button', { name: 'Rectangle' })).toBeNull();
+  });
+
+  it('is one tool across every trial', () => {
+    // A tool is what the hand is holding, not a property of a picture: picking
+    // Rectangle once has to arm it wherever the next mark is drawn.
+    labRef = null;
+    render(
+      <Lab instruments={[annotating]} defaultInstrument="Annotating">
+        <CaptureLab />
+      </Lab>,
+    );
+    act(() => labRef?.addTrial('Annotating'));
+    const panes = screen.getAllByTestId('pane');
+    expect(panes).toHaveLength(2);
+    for (const p of panes) expect(p.dataset.tool).toBe('pointer');
+
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Rectangle' }));
+    });
+    for (const p of screen.getAllByTestId('pane')) expect(p.dataset.tool).toBe('rect');
+  });
+});
+
 describe('the trial undo chrome over marks', () => {
   it('gets undo and redo without the instrument declaring `undo`', () => {
     // Weasel history is the authority for marks, so the capability that

package/src/trial/Trial.canvas.test.tsx

@@ -1,7 +1,10 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { auto } from '../config/auto';
+import { f } from '../config/builder';
 import { defineInstrument } from '../instrument/defineInstrument';
+import type { Instrument } from '../instrument/types';
 import { Lab } from '../lab/Lab';
 
 interface St {
@@ -74,6 +77,35 @@ describe('an instrument that draws', () => {
   });
 });
 
+describe('an auto config path', () => {
+  it('draws with the resolved value, which is what the panel shows too', async () => {
+    const draw = vi.fn();
+    const instrument = defineInstrument({
+      name: 'Auto',
+      config: f.schema({
+        gap: f
+          .number(12)
+          .auto(() => 18)
+          .range(0, 48)
+          .initial(auto),
+      }),
+      initialState: () => ({ n: 0 }),
+      render: () => null,
+      canvas: { layers: [{ id: 'main', draw }] },
+    });
+    render(<Lab instruments={[instrument as Instrument]} defaultInstrument="Auto" />);
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    expect(draw).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ config: { gap: 18 } }),
+    );
+    // The panel is handed the raw config, but a ghosted control draws what the
+    // resolver decided — a handle at 12 under a readout saying 18 reads as a bug.
+    expect(screen.getByRole('slider', { name: 'Gap' })).toHaveValue('18');
+  });
+});
+
 describe('LabProps.instruments', () => {
   it('accepts a typed instrument with no cast', () => {
     // The assignment is the assertion: this file fails to compile if

package/src/trial/Trial.config.test.tsx

@@ -1,5 +1,6 @@
 import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it } from 'vitest';
+import { auto } from '../config/auto';
 import { f } from '../config/builder';
 import type { ConfigRule, ControlRenderer } from '../config/types';
 import { defineInstrument } from '../instrument/defineInstrument';
@@ -132,14 +133,18 @@ describe('a nested config value, end to end', () => {
     const { instrument } = nestedInstrument();
     render(<Lab instruments={[instrument]} defaultInstrument="Nested" />);
     expect(screen.getByText('20')).toBeInTheDocument();
-    fireEvent.change(screen.getByLabelText('Cell size'), { target: { value: '40' } });
+    fireEvent.change(screen.getByLabelText('Cell size'), {
+      target: { value: '40' },
+    });
     expect(screen.getByText('40')).toBeInTheDocument();
   });
 
   it('hands onConfigChange the whole tree, with the sibling branch intact', () => {
     const { instrument, seen } = nestedInstrument();
     render(<Lab instruments={[instrument]} defaultInstrument="Nested" />);
-    fireEvent.change(screen.getByLabelText('Cell size'), { target: { value: '40' } });
+    fireEvent.change(screen.getByLabelText('Cell size'), {
+      target: { value: '40' },
+    });
     expect(seen.at(-1)?.config).toEqual({
       showGrid: true,
       grid: { size: 40, color: '#ffffff' },
@@ -150,3 +155,71 @@ describe('a nested config value, end to end', () => {
     });
   });
 });
+
+describe('a config written as auto', () => {
+  const unpinnable = () => {
+    const seen: { config: unknown; prev: unknown }[] = [];
+    const instrument = defineInstrument({
+      name: 'Unpinnable',
+      config: f.schema({
+        width: f.number(432),
+        gap: f.number(12).auto((c) => (c.width as number) / 24),
+      }),
+      initialState: () => ({ gap: 12 }),
+      onConfigChange: (config, prev, state) => {
+        seen.push({ config, prev });
+        return { ...state, gap: (config as { gap: number }).gap };
+      },
+      chrome: [
+        {
+          id: 'unpin-gap',
+          region: 'toolbar' as const,
+          render: (ctx) => (
+            <button type="button" onClick={() => ctx.setConfig('gap', auto)}>
+              unpin gap
+            </button>
+          ),
+        },
+      ],
+      render: (ctx) => <output>{String((ctx.state as { gap: number }).gap)}</output>,
+    });
+    return { instrument, seen };
+  };
+
+  it('hands onConfigChange the resolved config, never the sentinel', () => {
+    const { instrument, seen } = unpinnable();
+    render(<Lab instruments={[instrument]} defaultInstrument="Unpinnable" />);
+    fireEvent.click(screen.getByText('unpin gap'));
+    expect(seen.at(-1)?.config).toEqual({ width: 432, gap: 18 });
+    expect(seen.at(-1)?.prev).toEqual({ width: 432, gap: 12 });
+  });
+
+  it('keeps the state that write derived free of the sentinel', () => {
+    const { instrument } = unpinnable();
+    render(<Lab instruments={[instrument]} defaultInstrument="Unpinnable" />);
+    fireEvent.click(screen.getByText('unpin gap'));
+    expect(screen.getByText('18')).toBeInTheDocument();
+  });
+
+  it("shows the trial's unpinned path in the settings panel", () => {
+    const instrument = defineInstrument({
+      name: 'Ghosted',
+      config: f.schema({
+        width: f.number(432),
+        gap: f
+          .number(12)
+          .initial(auto)
+          .auto((c) => (c.width as number) / 24)
+          .range(0, 48),
+      }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    const { container } = render(<Lab instruments={[instrument]} defaultInstrument="Ghosted" />);
+    expect(screen.getByRole('button', { name: /Gap/ })).toHaveAttribute('aria-pressed', 'false');
+    expect(screen.getByRole('button', { name: /Width/ })).toHaveAttribute('aria-pressed', 'true');
+    // 432 / 24. A ghosted control draws what the resolver decided rather than
+    // the pinned 12 underneath it, and un-pinning writes back what it drew.
+    expect((container.querySelector('input[type=range]') as HTMLInputElement).value).toBe('18');
+  });
+});

package/src/trial/Trial.job.test.tsx

@@ -36,7 +36,7 @@ function makeInstrument(name: string, n: number, delay: number) {
 describe('a trial whose instrument declares a job', () => {
   it('shows progress in the trial chrome', async () => {
     const fast = makeInstrument('fast', 3, 1);
-    render(<Lab instruments={[fast]} defaultInstrument="fast" storage={null} />);
+    render(<Lab instruments={[fast]} defaultInstrument="fast" />);
     const bar = await waitFor(() => screen.getByRole('progressbar', { name: /job progress/i }));
     await waitFor(() => {
       // A job that reported a total drives a determinate bar, so the count and
@@ -49,7 +49,7 @@ describe('a trial whose instrument declares a job', () => {
 
   it('offers a cancel control while running, and drops it once cancelled', async () => {
     const slow = makeInstrument('slow', 40, 20);
-    render(<Lab instruments={[slow]} defaultInstrument="slow" storage={null} />);
+    render(<Lab instruments={[slow]} defaultInstrument="slow" />);
     const cancel = await waitFor(() => screen.getByRole('button', { name: /cancel/i }));
     await userEvent.click(cancel);
     await waitFor(() => {
@@ -64,7 +64,7 @@ describe('a trial whose instrument declares a job', () => {
       initialState: () => ({ items: [] }),
       render: () => null,
     });
-    render(<Lab instruments={[plain]} defaultInstrument="plain" storage={null} />);
+    render(<Lab instruments={[plain]} defaultInstrument="plain" />);
     await waitFor(() => {
       expect(document.querySelector('.lk-trial')).toBeInTheDocument();
     });

package/src/trial/Trial.less

@@ -9,11 +9,15 @@
   // from its own workspace by nothing but a hairline. Raised reads as a panel,
   // and in dark it is translucent, so the backdrop still shows through.
   background: var(--wzl-surface-raised);
-  border: var(--wzl-border-w) solid var(--wzl-border-raised);
+  border: var(--wzl-border-w) solid var(--wzl-border-strong);
   border-radius: var(--wzl-radius-md);
   box-shadow: 0 1px 3px var(--wzl-shadow);
   overflow: hidden;
 
+  &[data-focused='true'] {
+    border-color: var(--wzl-accent);
+  }
+
   &__body {
     display: flex;
     flex: 1;
@@ -96,21 +100,6 @@
     flex-shrink: 0;
   }
 
-  // The strip's own seam. windease positions and sizes it; this is only what
-  // it looks like.
-  &__panes [data-affordance-kind='resize-x'] {
-    background: var(--wzl-border);
-  }
-
-  &__panes .windease-affordance-hit:hover [data-affordance-kind='resize-x'],
-  &__panes .windease-affordance-hit:focus-visible [data-affordance-kind='resize-x'] {
-    background: var(--wzl-accent);
-  }
-
-  &__panes .windease-affordance-hit:focus-visible {
-    outline: none;
-  }
-
   &--unknown {
     display: flex;
     align-items: center;
@@ -126,16 +115,6 @@
   padding: 0 var(--wzl-space-sm);
 }
 
-.lk-toolbar__load-select {
-  font-size: var(--wzl-font-size-sm);
-}
-
-// Same `width: 100%` default as the header's Select — pinned so it cannot
-// absorb the toolbar's slack. Placeholder-only, so it need only fit "Load…".
-.lk-root .lk-toolbar__load-select {
-  width: 88px;
-}
-
 .lk-sidebar__placeholder {
   padding: var(--wzl-space-sm);
   color: var(--wzl-fg-muted);

package/src/trial/Trial.stories.tsx

@@ -1,7 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { Instrument } from '../instrument/types';
 import { LabContext, type LabContextValue } from '../lab/LabContext';
-import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore } from '../state/store';
 import type { TrialRecord } from '../state/types';
@@ -27,7 +26,7 @@ const record: TrialRecord = {
 };
 
 function Harness() {
-  const store = createLabStore({ storageKey: 'sb', storage: noneAdapter });
+  const store = createLabStore();
   const lab: LabContextValue = {
     instruments: [stub],
     trials: [record],
@@ -36,6 +35,9 @@ function Harness() {
     closeTrial: noop,
     resetTrial: noop,
     reorderTrials: noop,
+    swapTrial: noop,
+    focusedTrialId: record.id,
+    focusTrial: noop,
     savedSnapshots: [],
     saveSnapshot: noop,
     loadSnapshot: noop,

package/src/trial/Trial.test.tsx

@@ -35,10 +35,7 @@ type ChromeProps = Parameters<typeof TrialChrome>[0];
  *  and section folds live on the record, so a test that outlives one mount
  *  keeps its own store and hands it to both. */
 function makeChromeStore() {
-  const store = createLabStore({
-    storageKey: 'test',
-    storage: { read: () => null, write: () => {} },
-  });
+  const store = createLabStore();
   const { undoStack: _undo, ...seed } = stubRecord;
   store.getState().addTrial(seed);
   return store;
@@ -65,6 +62,9 @@ function ChromeHarness({
     closeTrial: vi.fn(),
     resetTrial: vi.fn(),
     reorderTrials: vi.fn(),
+    swapTrial: vi.fn(),
+    focusedTrialId: stubRecord.id,
+    focusTrial: vi.fn(),
     savedSnapshots: [],
     saveSnapshot: vi.fn(),
     loadSnapshot: vi.fn(),
@@ -205,6 +205,33 @@ describe('<TrialChrome>', () => {
     expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
   });
 
+  it("reads the instrument's title over its name, and returns to it on setTitle(null)", () => {
+    const titled: Instrument = { ...stubInstrument, title: 'Stub / Default' };
+    render(
+      <ChromeHarness
+        instrument={titled}
+        chrome={[
+          {
+            id: 'rename',
+            region: 'titlebar',
+            item: { icon: Glyph, label: 'Rename', onActivate: (ctx) => ctx.setTitle('Sprocket 7') },
+          },
+          {
+            id: 'untitle',
+            region: 'titlebar',
+            item: { icon: Glyph, label: 'Untitle', onActivate: (ctx) => ctx.setTitle(null) },
+          },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('region', { name: 'Trial Stub / Default' })).toBeInTheDocument();
+    expect(screen.getByText('Stub / Default')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Rename' }));
+    expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Untitle' }));
+    expect(screen.getByRole('region', { name: 'Trial Stub / Default' })).toBeInTheDocument();
+  });
+
   it('Cmd+S triggers saveSnapshot', () => {
     const saveSnapshot = vi.fn();
     render(<ChromeHarness labOverrides={{ saveSnapshot }} />);