@weasel-js/labkit 1.4.1 → 1.4.3

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

@@ -0,0 +1,96 @@
+/**
+ * `annotations.targets` is declared once per instrument and called once per
+ * trial, so everything here runs two trials of one instrument: with a single
+ * trial open, a `targets` that ignored the trial it was asked about would look
+ * identical.
+ */
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { AnnotationTarget } from '../annotations/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
+import type { TrialInfo } from '../state/types';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+const asked: TrialInfo[] = [];
+
+/** The last thing `targets` was told about `id`. */
+function lastAsk(id: string): TrialInfo {
+  const found = [...asked].reverse().find((t) => t.id === id);
+  if (!found) throw new Error(`targets was never called for ${id}`);
+  return found;
+}
+
+const pane: AnnotationTarget = { id: 'pane', ref: { current: null }, content: { w: 200, h: 100 } };
+
+const subject = defineInstrument<Record<string, never>, { subject: string }>({
+  name: 'Subject',
+  defaultConfig: () => ({ subject: 'none' }),
+  initialState: () => ({}),
+  render: (ctx) => (
+    <button
+      type="button"
+      data-testid={`zoom-${ctx.trial.id}`}
+      onClick={() => ctx.trial.setView({ zoom: 3, pan: { x: 0, y: 0 } })}
+    >
+      zoom
+    </button>
+  ),
+  annotations: {
+    targets: (_state, _config, trial) => {
+      asked.push({ id: trial.id, view: trial.view });
+      return [pane];
+    },
+  },
+});
+
+let labRef: LabContextValue | null = null;
+
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        if (value) labRef = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+function mountTwoTrials(): [string, string] {
+  render(
+    <Lab instruments={[subject]} defaultInstrument="Subject">
+      <CaptureLab />
+    </Lab>,
+  );
+  act(() => labRef?.addTrial('Subject'));
+  const ids = labRef?.trials.map((t) => t.id) ?? [];
+  const [a, b] = ids;
+  if (!a || !b) throw new Error('expected two trials');
+  return [a, b];
+}
+
+describe('annotations.targets', () => {
+  beforeEach(() => {
+    asked.length = 0;
+    labRef = null;
+  });
+
+  it('is told which trial is asking', () => {
+    const [a, b] = mountTwoTrials();
+    expect(new Set(asked.map((t) => t.id))).toEqual(new Set([a, b]));
+  });
+
+  it("is told that trial's own view, not the other's", () => {
+    const [a, b] = mountTwoTrials();
+    fireEvent.click(screen.getByTestId(`zoom-${a}`));
+    expect(lastAsk(a).view).toEqual({ zoom: 3, pan: { x: 0, y: 0 } });
+    expect(lastAsk(b).view).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });
+  });
+});

package/src/trial/Trial.test.tsx

@@ -1,6 +1,8 @@
 import { fireEvent, render, screen, within } from '@testing-library/react';
-import type { ReactNode } from 'react';
+import { type ReactNode, useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
+import { useStore } from 'zustand/react';
+import { f } from '../config/builder';
 import type { Instrument } from '../instrument/types';
 import { Lab } from '../lab/Lab';
 import { LabContext, type LabContextValue } from '../lab/LabContext';
@@ -9,6 +11,8 @@ import { createLabStore } from '../state/store';
 import type { SavedSnapshot, TrialRecord } from '../state/types';
 import { TrialChrome } from './TrialChrome';
 
+const Glyph = () => <svg />;
+
 const stubInstrument: Instrument = {
   name: 'Stub',
   defaultConfig: () => ({}),
@@ -27,16 +31,32 @@ const stubRecord: TrialRecord = {
 
 type ChromeProps = Parameters<typeof TrialChrome>[0];
 
+/** A store holding the stub trial, as `Trial` would have put it there. Title
+ *  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 { undoStack: _undo, ...seed } = stubRecord;
+  store.getState().addTrial(seed);
+  return store;
+}
+
 function ChromeHarness({
   children,
   labOverrides,
   instrument = stubInstrument,
+  store: storeProp,
   ...props
-}: { children?: ReactNode; labOverrides?: Partial<LabContextValue> } & Partial<ChromeProps>) {
-  const store = createLabStore({
-    storageKey: 'test',
-    storage: { read: () => null, write: () => {} },
-  });
+}: {
+  children?: ReactNode;
+  labOverrides?: Partial<LabContextValue>;
+  store?: ReturnType<typeof createLabStore>;
+} & Partial<ChromeProps>) {
+  const [ownStore] = useState(makeChromeStore);
+  const store = storeProp ?? ownStore;
   const labCtx: LabContextValue = {
     instruments: [instrument],
     trials: [stubRecord],
@@ -56,20 +76,31 @@ function ChromeHarness({
   return (
     <LabStoreContext.Provider value={{ store }}>
       <LabContext.Provider value={labCtx}>
-        <TrialChrome
-          trialId="ws-1"
-          record={stubRecord}
-          instrument={instrument}
-          isLastTrial={false}
-          {...props}
-        >
+        <ChromeFromStore store={store} instrument={instrument} {...props}>
           {children ?? <div data-testid="content">content</div>}
-        </TrialChrome>
+        </ChromeFromStore>
       </LabContext.Provider>
     </LabStoreContext.Provider>
   );
 }
 
+/** Reads the record out of the store the way `Trial` does, so a mutation the
+ *  chrome writes comes back to it. */
+function ChromeFromStore({
+  store,
+  children,
+  ...props
+}: { store: ReturnType<typeof createLabStore>; children: ReactNode } & Partial<ChromeProps> &
+  Pick<ChromeProps, 'instrument'>) {
+  const record = useStore(store, (s) => s.trials.find((t) => t.id === 'ws-1'));
+  if (!record) throw new Error('no stub trial in the store');
+  return (
+    <TrialChrome trialId="ws-1" record={record} isLastTrial={false} {...props}>
+      {children}
+    </TrialChrome>
+  );
+}
+
 describe('<TrialChrome>', () => {
   it('renders children in the content area', () => {
     render(<ChromeHarness />);
@@ -131,6 +162,49 @@ describe('<TrialChrome>', () => {
     expect(screen.getByText('ready')).toBeInTheDocument();
   });
 
+  it('leads the title bar with a contribution that does not set `end`', () => {
+    const { container } = render(
+      <ChromeHarness
+        chrome={[
+          {
+            id: 'subject',
+            region: 'titlebar',
+            item: { icon: Glyph, label: 'Pick subject', onActivate: () => {} },
+          },
+        ]}
+      />,
+    );
+    const titlebar = container.querySelector('.lk-trial__titlebar');
+    if (!titlebar) throw new Error('no title bar');
+    const lead = screen.getByRole('button', { name: 'Pick subject' });
+    const heading = titlebar.querySelector('.lk-trial__title');
+    if (!heading) throw new Error('no title');
+    expect(titlebar.querySelector('.lk-trial__titlebar-lead')).toContainElement(lead);
+    expect(lead.compareDocumentPosition(heading) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it('reads the instrument name until a contribution calls setTitle', () => {
+    render(
+      <ChromeHarness
+        chrome={[
+          {
+            id: 'rename',
+            region: 'titlebar',
+            item: {
+              icon: Glyph,
+              label: 'Rename',
+              onActivate: (ctx) => ctx.setTitle('Sprocket 7'),
+            },
+          },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('region', { name: 'Trial Stub' })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Rename' }));
+    expect(screen.getByText('Sprocket 7')).toBeInTheDocument();
+    expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
+  });
+
   it('Cmd+S triggers saveSnapshot', () => {
     const saveSnapshot = vi.fn();
     render(<ChromeHarness labOverrides={{ saveSnapshot }} />);
@@ -168,3 +242,86 @@ describe('chrome regions in a mounted lab', () => {
     expect(document.querySelector('.lk-lab')).toBeTruthy();
   });
 });
+
+describe('<TrialChrome> — state that outlives a mount', () => {
+  const renameChrome: ChromeProps['chrome'] = [
+    {
+      id: 'rename',
+      region: 'titlebar',
+      item: {
+        icon: Glyph,
+        label: 'Rename',
+        onActivate: (ctx) => ctx.setTitle('Sprocket 7'),
+      },
+    },
+  ];
+
+  const sectionChrome: ChromeProps['chrome'] = [
+    {
+      id: 'notes',
+      region: 'sidebar',
+      item: { title: 'Notes', body: <p data-testid="notes-body">notes</p> },
+    },
+  ];
+
+  it('keeps a title across a remount', () => {
+    const store = makeChromeStore();
+    const first = render(<ChromeHarness store={store} chrome={renameChrome} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Rename' }));
+    first.unmount();
+
+    render(<ChromeHarness store={store} chrome={renameChrome} />);
+    expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
+  });
+
+  it('keeps a folded sidebar section across a remount', () => {
+    const store = makeChromeStore();
+    const first = render(<ChromeHarness store={store} chrome={sectionChrome} />);
+    expect(screen.getByTestId('notes-body')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Notes' }));
+    expect(screen.queryByTestId('notes-body')).toBeNull();
+    first.unmount();
+
+    render(<ChromeHarness store={store} chrome={sectionChrome} />);
+    expect(screen.getByRole('button', { name: 'Notes' })).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.queryByTestId('notes-body')).toBeNull();
+  });
+
+  it('keeps a folded settings group across a remount', () => {
+    const sectioned: Instrument = {
+      ...stubInstrument,
+      config: f.schema({ size: f.number(1).section('Shape') }),
+    };
+    const store = makeChromeStore();
+    const first = render(<ChromeHarness store={store} instrument={sectioned} />);
+    const twisty = screen.getByRole('button', { name: 'Shape' });
+    expect(twisty).toHaveAttribute('aria-expanded', 'true');
+    fireEvent.click(twisty);
+    first.unmount();
+
+    render(<ChromeHarness store={store} instrument={sectioned} />);
+    expect(screen.getByRole('button', { name: 'Shape' })).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('reopens a section that starts collapsed, and keeps it open across a remount', () => {
+    const collapsedChrome: ChromeProps['chrome'] = [
+      {
+        id: 'notes',
+        region: 'sidebar',
+        item: {
+          title: 'Notes',
+          defaultCollapsed: true,
+          body: <p data-testid="notes-body">notes</p>,
+        },
+      },
+    ];
+    const store = makeChromeStore();
+    const first = render(<ChromeHarness store={store} chrome={collapsedChrome} />);
+    expect(screen.queryByTestId('notes-body')).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Notes' }));
+    first.unmount();
+
+    render(<ChromeHarness store={store} chrome={collapsedChrome} />);
+    expect(screen.getByTestId('notes-body')).toBeInTheDocument();
+  });
+});

package/src/trial/Trial.tsx

@@ -130,7 +130,9 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
   const annotationsCap = instrument.annotations;
   const targetsRef = useRef<() => readonly AnnotationTargetInfo[]>(() => []);
   targetsRef.current = () =>
-    annotationsCap ? annotationsCap.targets(record.state, record.config) : [];
+    annotationsCap
+      ? annotationsCap.targets(record.state, record.config, { id: record.id, view: record.view })
+      : [];
 
   // One store for the trial's lifetime. Marks do not survive a reload yet —
   // the storage slot is 3d.
@@ -237,11 +239,11 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
       updateTrialState(record.id, next);
       bus.emit('state.change');
     },
-    setConfig: (key, value) => {
-      const evt = `config.change:${String(key)}`;
+    setConfig: (path, value) => {
+      const evt = `config.change:${path}`;
       snapshotIfNeeded('config.change');
       snapshotIfNeeded(evt);
-      updateTrialConfig(record.id, key as never, value as never);
+      updateTrialConfig(record.id, path, value);
       bus.emit('config.change');
       bus.emit(evt);
     },
@@ -474,6 +476,7 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
       capability={annotationsCap}
       state={record.state}
       config={record.config}
+      trial={{ id: record.id, view: record.view }}
       annotations={annotations}
       activeToolId={resolvedToolId}
     />

package/src/trial/TrialChrome.tsx

@@ -9,6 +9,7 @@ import { TitleBarRegion } from '../chrome/regions/TitleBarRegion';
 import { ToolbarRegion } from '../chrome/regions/ToolbarRegion';
 import { ViewportRegion } from '../chrome/regions/ViewportRegion';
 import type { TrialChromeContext, TrialContribution, TrialRegion } from '../chrome/types';
+import { hasConfigPath, schemaNodeAtPath, withValueAtPath } from '../config/path';
 import { useConfigSchema } from '../config/useConfigSchema';
 import type { Instrument } from '../instrument/types';
 import type { JobHandle } from '../job/types';
@@ -62,6 +63,10 @@ export interface TrialChromeProps {
 
 const NO_OP = (): void => {};
 
+/** One frozen empty map, so a trial that has folded nothing keeps a stable
+ *  context identity across renders. */
+const NO_SECTIONS: Readonly<Record<string, boolean>> = Object.freeze({});
+
 /** The frame around a running instrument. Builds one chrome context, assembles
  *  the contributions the instrument, the runtime and the lab declare, and hands
  *  each region its slice. */
@@ -85,6 +90,8 @@ export function TrialChrome({
   if (!storeCtx) throw new Error('[labkit] TrialChrome requires <LabStoreProvider>');
   const updateTrialView = useStore(storeCtx.store, (s) => s.updateTrialView);
   const updateTrialSidebarWidth = useStore(storeCtx.store, (s) => s.updateTrialSidebarWidth);
+  const setTrialTitle = useStore(storeCtx.store, (s) => s.setTrialTitle);
+  const setTrialSectionCollapsed = useStore(storeCtx.store, (s) => s.setTrialSectionCollapsed);
   const updateTrialConfig = useStore(storeCtx.store, (s) => s.updateTrialConfig);
   const updateTrialState = useStore(storeCtx.store, (s) => s.updateTrialState);
   const undockPanelAction = useStore(storeCtx.store, (s) => s.undockPanel);
@@ -104,6 +111,9 @@ export function TrialChrome({
 
   const configSchema = useConfigSchema(instrument);
 
+  const title = record.title ?? record.instrumentName;
+  const collapsedSections = record.collapsedSections ?? NO_SECTIONS;
+
   const ctx = useMemo<TrialChromeContext>(() => {
     const setZoom = (z: number): void => {
       if (!view2d) return;
@@ -112,6 +122,8 @@ export function TrialChrome({
     return {
       trialId,
       instrumentName: record.instrumentName,
+      title,
+      setTitle: (next) => setTrialTitle(trialId, next),
       isLastTrial,
       zoom: view2d ? view2d.zoom : null,
       setZoom,
@@ -124,20 +136,26 @@ export function TrialChrome({
       configSchema,
       configFields: instrument.config ? [] : (instrument.configSchema?.() ?? []),
       config: record.config,
-      setConfig: (key, value) => {
+      setConfig: (path, value) => {
         const prevConfig = record.config as Record<string, unknown>;
-        if (process.env.NODE_ENV !== 'production' && !(key in prevConfig)) {
+        if (
+          process.env.NODE_ENV !== 'production' &&
+          !hasConfigPath(prevConfig, path) &&
+          schemaNodeAtPath(configSchema.group, path) === undefined
+        ) {
           console.warn(
-            `[labkit] setConfig: unknown key "${key}" for instrument "${record.instrumentName}"`,
+            `[labkit] setConfig: unknown path "${path}" for instrument "${record.instrumentName}"`,
           );
         }
-        updateTrialConfig(trialId, key as never, value as never);
+        updateTrialConfig(trialId, path, value);
         if (instrument.onConfigChange) {
-          const nextConfig = { ...prevConfig, [key]: value };
+          const nextConfig = withValueAtPath(prevConfig, path, value);
           const nextState = instrument.onConfigChange(nextConfig, prevConfig, record.state);
           updateTrialState(trialId, nextState as never);
         }
       },
+      collapsedSections,
+      setSectionCollapsed: (key, collapsed) => setTrialSectionCollapsed(trialId, key, collapsed),
       undockedPanels: undockedIds,
       undockPanel: (sectionId, as) => undockPanelAction(trialId, sectionId, as),
       dockPanel: (sectionId) => dockPanelAction(trialId, sectionId),
@@ -155,6 +173,7 @@ export function TrialChrome({
     record,
     instrument,
     lab,
+    title,
     isLastTrial,
     updateTrialView,
     updateTrialConfig,
@@ -168,6 +187,9 @@ export function TrialChrome({
     undockedIds,
     undockPanelAction,
     dockPanelAction,
+    setTrialTitle,
+    setTrialSectionCollapsed,
+    collapsedSections,
   ]);
 
   const contributions = useMemo(
@@ -203,11 +225,14 @@ export function TrialChrome({
   return (
     <section
       className="lk-trial"
-      aria-label={`Trial ${record.instrumentName}`}
+      aria-label={`Trial ${title}`}
       tabIndex={-1}
       onKeyDown={handleKeyDown}
     >
-      <TrialTitleBar title={record.instrumentName}>
+      <TrialTitleBar
+        title={title}
+        lead={<TitleBarRegion placement="lead" contributions={inRegion('titlebar')} ctx={ctx} />}
+      >
         <TitleBarRegion contributions={inRegion('titlebar')} ctx={ctx} />
       </TrialTitleBar>
       <div className="lk-trial__toolbar">

package/src/trial/TrialTitleBar.tsx

@@ -6,15 +6,18 @@ import { useTrialDrag } from './TrialDragContext';
 /** Props for `<TrialTitleBar>`. */
 export interface TrialTitleBarProps {
   title: string;
+  /** Rendered at the leading edge, before the title. */
+  lead?: ReactNode;
   children?: ReactNode;
 }
 
 // `useDragHandle` needs a node id and windease's DragProvider, so the draggable
 // form is a separate component rather than a conditional hook.
-function Draggable({ nodeId, title, children }: TrialTitleBarProps & { nodeId: NodeId }) {
+function Draggable({ nodeId, title, lead, children }: TrialTitleBarProps & { nodeId: NodeId }) {
   const handlers = useDragHandle(nodeId);
   return (
     <div className="lk-trial__titlebar lk-trial__titlebar--draggable" {...handlers}>
+      {lead}
       <span className="lk-trial__title">{title}</span>
       {children}
     </div>
@@ -24,16 +27,17 @@ function Draggable({ nodeId, title, children }: TrialTitleBarProps & { nodeId: N
 /** A trial's title bar. When the workspace allows reordering the whole bar is
  *  the drag surface — there is no separate grip, because a window's title bar
  *  is already the thing you expect to drag. */
-export function TrialTitleBar({ title, children }: TrialTitleBarProps) {
+export function TrialTitleBar({ title, lead, children }: TrialTitleBarProps) {
   const drag = useTrialDrag();
   if (drag)
     return (
-      <Draggable nodeId={drag.nodeId} title={title}>
+      <Draggable nodeId={drag.nodeId} title={title} lead={lead}>
         {children}
       </Draggable>
     );
   return (
     <div className="lk-trial__titlebar">
+      {lead}
       <span className="lk-trial__title">{title}</span>
       {children}
     </div>

package/src/trial/index.ts

@@ -4,6 +4,7 @@ export type { TrialBodyProps } from './TrialBody';
 export { TrialBody } from './TrialBody';
 export type { TrialChromeProps, UndoBindings } from './TrialChrome';
 export { TrialChrome } from './TrialChrome';
+export type { AddTrialOptions } from './trialOps';
 export {
   addTrial,
   cloneTrial,

package/src/trial/trialOps.test.ts

@@ -26,7 +26,23 @@ const counterWithCanvas: Instrument<CounterState, CounterConfig> = {
   },
 };
 
-const instruments: Instrument[] = [counter as Instrument, counterWithCanvas as Instrument];
+interface SubjectConfig {
+  subject: string;
+  zoom: number;
+}
+
+const subjectInstrument: Instrument<{ label: string }, SubjectConfig> = {
+  name: 'Subject',
+  defaultConfig: () => ({ subject: 'none', zoom: 1 }),
+  initialState: (config) => ({ label: config.subject.toUpperCase() }),
+  render: () => null,
+};
+
+const instruments: Instrument[] = [
+  counter as Instrument,
+  counterWithCanvas as Instrument,
+  subjectInstrument as Instrument,
+];
 
 function head<T>(arr: T[]): T {
   const first = arr[0];
@@ -69,6 +85,28 @@ describe('addTrial', () => {
     addTrial(arr, instruments, 'Counter');
     expect(arr).toHaveLength(0);
   });
+
+  it('overlays a seed config on the instrument defaults', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: 'brick' } });
+    expect(out[0]?.config).toEqual({ subject: 'brick', zoom: 1 });
+  });
+
+  it('seeds the config before initialState reads it', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: 'brick' } });
+    expect(out[0]?.state).toEqual({ label: 'BRICK' });
+  });
+
+  it('gives each trial the seed it was opened with', () => {
+    const a = addTrial([], instruments, 'Subject', { config: { subject: 'one' } });
+    const b = addTrial(a, instruments, 'Subject', { config: { subject: 'two' } });
+    expect(b.map((t) => (t.config as SubjectConfig).subject)).toEqual(['one', 'two']);
+    expect(b.map((t) => (t.state as { label: string }).label)).toEqual(['ONE', 'TWO']);
+  });
+
+  it('ignores a seed key whose value is undefined', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: undefined } });
+    expect(out[0]?.config).toEqual({ subject: 'none', zoom: 1 });
+  });
 });
 
 describe('cloneTrial', () => {
@@ -139,6 +177,16 @@ describe('resetTrial', () => {
     resetTrial(arr, head(arr).id, instruments);
     expect((arr[0]?.config as CounterConfig).step).toBe(99);
   });
+
+  it('restores the seed the trial was opened with, not the bare defaults', () => {
+    let arr = addTrial([], instruments, 'Subject', { config: { subject: 'one' } });
+    arr = addTrial(arr, instruments, 'Subject', { config: { subject: 'two' } });
+    head(arr).config = { subject: 'edited', zoom: 4 } as SubjectConfig;
+    const reset = resetTrial(arr, head(arr).id, instruments);
+    expect(reset[0]?.config).toEqual({ subject: 'one', zoom: 1 });
+    expect(reset[0]?.state).toEqual({ label: 'ONE' });
+    expect(reset[1]?.config).toEqual({ subject: 'two', zoom: 1 });
+  });
 });
 
 describe('reorderTrials', () => {

package/src/trial/trialOps.ts

@@ -1,3 +1,4 @@
+import { fillConfigDefaults } from '../config/path';
 import type { Instrument, InstrumentList } from '../instrument/types';
 import type { TrialRecord } from '../state/types';
 
@@ -19,15 +20,31 @@ function initialView(instrument: Instrument): TrialRecord['view'] {
   return declared ? structuredClone(declared) : { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
 }
 
-/** Append a new trial running `instrumentName`, at that instrument's
- *  default config and initial state. */
+/** What a trial opens on beyond its instrument's own defaults. */
+export interface AddTrialOptions<TC = Record<string, unknown>> {
+  /** Overlaid on `defaultConfig()` before `initialState` reads it, so a trial
+   *  opened on a subject is running that subject from its first frame. Keys
+   *  whose value is `undefined` are left to the default. */
+  config?: Partial<TC>;
+}
+
+/** `defaultConfig()` with `seed` written over it, down the tree: a seed naming
+ *  one leaf of a group leaves that group's other leaves at their defaults. */
+function seedConfig<TC>(defaults: TC, seed: Partial<TC> | undefined): TC {
+  return seed ? fillConfigDefaults(seed, defaults) : defaults;
+}
+
+/** Append a new trial running `instrumentName`, at that instrument's default
+ *  config — with `options.config` written over it — and the initial state
+ *  that config produces. */
 export function addTrial(
   trials: TrialRecord[],
   instruments: InstrumentList,
   instrumentName: string,
+  options: AddTrialOptions = {},
 ): TrialRecord[] {
   const instrument = findInstrument(instruments, instrumentName);
-  const config = instrument.defaultConfig();
+  const config = seedConfig(instrument.defaultConfig(), options.config);
   const state = instrument.initialState(config);
   const record: TrialRecord = {
     id: crypto.randomUUID(),
@@ -37,6 +54,7 @@ export function addTrial(
     view: initialView(instrument),
     undoStack: { past: [], future: [] },
   };
+  if (options.config) record.configSeed = options.config;
   return [...trials, record];
 }
 
@@ -65,8 +83,8 @@ export function closeTrial(trials: TrialRecord[], id: string): TrialRecord[] {
   return next.length === trials.length ? trials : next;
 }
 
-/** Return a trial to its instrument's defaults, keeping its id and its
- *  place in the list. */
+/** Return a trial to what it opened on — its instrument's defaults under the
+ *  seed `addTrial` was given — keeping its id and its place in the list. */
 export function resetTrial(
   trials: TrialRecord[],
   id: string,
@@ -76,7 +94,7 @@ export function resetTrial(
   const current = trials[idx];
   if (!current) return trials;
   const instrument = findInstrument(instruments, current.instrumentName);
-  const config = instrument.defaultConfig();
+  const config = seedConfig(instrument.defaultConfig(), current.configSeed);
   const state = instrument.initialState(config);
   const reset: TrialRecord = {
     ...current,