@weasel-js/labkit 1.4.2 → 1.4.3

package/src/instrument/serializers.ts

@@ -0,0 +1,36 @@
+import type { InstrumentSerializers } from '../state/types';
+import type { InstrumentList } from './types';
+
+/**
+ * Each instrument's default config, keyed by name — what `createLabStore`
+ * fills a stored config's gaps from, so one saved before its schema grew a
+ * branch still loads.
+ */
+export function configDefaultsOf(instruments: InstrumentList): Record<string, () => unknown> {
+  const out: Record<string, () => unknown> = {};
+  for (const instrument of instruments) out[instrument.name] = () => instrument.defaultConfig();
+  return out;
+}
+
+/**
+ * The `serialize` / `deserialize` an instrument list declares, keyed by
+ * instrument name — what `createLabStore` needs to rebuild a trial's state
+ * from storage.
+ *
+ * An instrument declaring neither gets no entry, which is what leaves a
+ * JSON-safe state to pass through untouched.
+ */
+export function serializersOf(instruments: InstrumentList): InstrumentSerializers {
+  const out: InstrumentSerializers = {};
+  for (const instrument of instruments) {
+    const { name, serialize, deserialize } = instrument;
+    if (!serialize && !deserialize) continue;
+    out[name] = {
+      ...(serialize ? { serialize: (state: unknown) => serialize(state) } : {}),
+      ...(deserialize
+        ? { deserialize: (data: unknown, config: unknown) => deserialize(data, config) }
+        : {}),
+    };
+  }
+  return out;
+}

package/src/instrument/types.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
-import type { ConfigSchema } from '../config/types';
+import type { ConfigPath, ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
 import type { LoupeDeclaration } from '../loupe/types';
@@ -15,7 +15,9 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   state: TS;
   config: TC;
   setState: (next: TS | ((prev: TS) => TS)) => void;
-  setConfig: (key: keyof TC, value: unknown) => void;
+  /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+   *  an `f.group`, `'cellSize'` for one at the root. */
+  setConfig: (path: ConfigPath<TC>, value: unknown) => void;
   /** labkit persists `view` and restores it on Reset without ever reading
    *  into it. */
   trial: TrialInfo & {

package/src/lab/Lab.test.tsx

@@ -1,7 +1,9 @@
 import { act, render, screen } from '@testing-library/react';
 import type { ReactNode } from 'react';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { labDocumentKey } from '../state/document';
 import { Lab } from './Lab';
 import { LabContext, type LabContextValue } from './LabContext';
 
@@ -135,4 +137,30 @@ describe('<Lab>', () => {
       /Unknown instrument/,
     );
   });
+
+  // The store reads its serializers while it is being built, so `<Lab>` is
+  // the only thing positioned to collect them off the instruments. They went
+  // uncollected for months, and an instrument holding anything JSON drops
+  // lost it with no error.
+  it('gives the store the serializers its instruments declare', () => {
+    vi.useFakeTimers();
+    const storage = createMemoryAdapter();
+    const mapped: Instrument = {
+      ...stub,
+      name: 'Mapped',
+      initialState: () => ({ seen: new Set(['a']) }),
+      serialize: (state) => ({ seen: [...(state as { seen: Set<string> }).seen] }),
+      deserialize: (data) => ({ seen: new Set((data as { seen: string[] }).seen) }),
+    };
+
+    render(
+      <Lab instruments={[mapped]} defaultInstrument="Mapped" storage={storage} storageKey="s" />,
+    );
+    act(() => vi.advanceTimersByTime(500));
+    expect(storage.read(labDocumentKey('s')) ?? '').toContain('"seen":["a"]');
+    vi.useRealTimers();
+
+    mountLab({ instruments: [mapped], defaultInstrument: 'Mapped', storage, storageKey: 's' });
+    expect((labRef?.trials[0]?.state as { seen: Set<string> }).seen).toEqual(new Set(['a']));
+  });
 });

package/src/lab/Lab.tsx

@@ -11,6 +11,7 @@ import {
 import { useStore } from 'zustand/react';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
+import { configDefaultsOf, serializersOf } from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
 import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
@@ -78,7 +79,15 @@ function buildStore(
   storageKey: string,
   initialMode: LabMode,
 ): LabStore {
-  const store = createLabStore({ storageKey, storage, initialMode });
+  // Hydration reads the serializers, so they go in with the store rather than
+  // being registered onto it afterwards.
+  const store = createLabStore({
+    storageKey,
+    storage,
+    initialMode,
+    serializers: serializersOf(instruments),
+    configDefaults: configDefaultsOf(instruments),
+  });
   if (store.getState().trials.length === 0) {
     const seeded = addTrialOp([], instruments, defaultInstrument);
     const record = seeded[0];

package/src/lab/LabShell.test.tsx

@@ -39,6 +39,14 @@ describe('LabShell', () => {
     expect(root.getAttribute('data-wzl-mode')).toMatch(/^(light|dark)$/);
   });
 
+  // The overlays weasel-ui ships default to the nearest portal host, and
+  // `.lk-root` is where labkit's element defaults live — not the themed
+  // wrapper above it.
+  test('marks lk-root as the portal host for overlays', () => {
+    const { container } = render(<LabShell title="t">x</LabShell>);
+    expect(container.querySelector('.lk-root')?.hasAttribute('data-wzl-portal-host')).toBe(true);
+  });
+
   test('always applies lk-root class', () => {
     const { container } = render(<LabShell title="t">x</LabShell>);
     expect(container.querySelector('.lk-root')).not.toBeNull();

package/src/lab/LabShell.tsx

@@ -24,7 +24,9 @@ export function LabShell({ title, children, header, footer, mode = 'auto' }: Lab
   const outer = useThemeOptional();
 
   const shell = (
-    <div className="lk-root lk-shell">
+    // Overlays portal here rather than to the themed wrapper above: `.lk-root`
+    // carries the element defaults a lab's bare markup is styled by.
+    <div className="lk-root lk-shell" data-wzl-portal-host="">
       <header className="lk-shell-header">
         <h1 className="lk-shell-title">{title}</h1>
         {header && <div className="lk-shell-header-actions">{header}</div>}

package/src/primitives/ZoomControl.less

@@ -13,7 +13,7 @@
   }
 }
 
-// Both children are weasel-ui components whose module classes set `width`.
+// The slider is a weasel-ui component whose module class sets `width`.
 // See the `.lk-root` prefix convention in theme/base.less.
 .lk-root {
   .lk-zoom {
@@ -24,8 +24,12 @@
       min-width: 64px;
     }
 
+    // `width: fit` sizes the field from this rather than from the input's
+    // 20-character intrinsic width. "800%" measures 33px against the 35px a
+    // 5ch box gives, which is no margin at all in another UI font; 6ch also
+    // holds the "1600%" a consumer raising `max` can reach.
     &__field {
-      width: 62px;
+      --wzl-number-field-width: 6ch;
     }
   }
 }

package/src/primitives/ZoomControl.tsx

@@ -60,6 +60,7 @@ export function ZoomControl({
           factor itself and renders 0.5 as "50%". */}
       <NumberField
         className="lk-zoom__field"
+        width="fit"
         aria-label="Zoom"
         value={zoom}
         minValue={min}

package/src/state/helpers.ts

@@ -58,7 +58,7 @@ export function deserializeTrials(
     const d = deserializers[r.instrumentName];
     return {
       ...r,
-      state: d?.deserialize ? d.deserialize(r.state) : r.state,
+      state: d?.deserialize ? d.deserialize(r.state, r.config) : r.state,
       undoStack: emptyUndoStack(),
     };
   });

package/src/state/store.test.ts

@@ -100,10 +100,114 @@ describe('updateTrialConfig', () => {
       state: {},
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
-    s.getState().updateTrialConfig('w1', 'x' as never, 99 as never);
+    s.getState().updateTrialConfig('w1', 'x', 99);
     expect((s.getState().trials[0]?.config as { x: number }).x).toBe(99);
     expect((s.getState().trials[0]?.config as { y: number }).y).toBe(2);
   });
+
+  it('writes down a dotted path without disturbing its siblings', () => {
+    const s = makeStore();
+    const config = { grid: { size: 20, color: '#fff' }, showGrid: true };
+    s.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config,
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().updateTrialConfig('w1', 'grid.size', 40);
+    expect(s.getState().trials[0]?.config).toEqual({
+      grid: { size: 40, color: '#fff' },
+      showGrid: true,
+    });
+    // The record handed in is never mutated: a trial re-renders on identity.
+    expect(config.grid.size).toBe(20);
+  });
+});
+
+describe('createLabStore - config defaults', () => {
+  const stored = (config: unknown) =>
+    JSON.stringify({
+      version: CURRENT_DOCUMENT_VERSION,
+      trials: [
+        {
+          id: 'w1',
+          instrumentName: 'T',
+          config,
+          state: {},
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+        },
+      ],
+      saves: [
+        {
+          id: 's1',
+          name: 'saved',
+          trialId: 'w1',
+          instrumentName: 'T',
+          config,
+          state: {},
+          savedAt: 1,
+        },
+      ],
+      layout: {},
+      undockedPanels: {},
+      mode: 'auto',
+    });
+
+  it('fills a branch a config stored before the schema nested it never had', () => {
+    const storage = createMemoryAdapter();
+    storage.write(labDocumentKey('test'), stored({ showGrid: false, gridSize: 40 }));
+    const s = createLabStore({
+      storageKey: 'test',
+      storage,
+      configDefaults: { T: () => ({ showGrid: true, grid: { size: 20, color: '#fff' } }) },
+    });
+    expect(s.getState().trials[0]?.config).toEqual({
+      showGrid: false,
+      gridSize: 40,
+      grid: { size: 20, color: '#fff' },
+    });
+  });
+
+  it('fills the config on a saved snapshot the same way', () => {
+    const storage = createMemoryAdapter();
+    storage.write(labDocumentKey('test'), stored({ grid: { size: 40 } }));
+    const s = createLabStore({
+      storageKey: 'test',
+      storage,
+      configDefaults: { T: () => ({ grid: { size: 20, color: '#fff' } }) },
+    });
+    expect(s.getState().savedSnapshots[0]?.config).toEqual({
+      grid: { size: 40, color: '#fff' },
+    });
+  });
+
+  it('hands a deserializer the filled config, not the stored one', () => {
+    const storage = createMemoryAdapter();
+    storage.write(labDocumentKey('test'), stored({ grid: { size: 40 } }));
+    const seen: unknown[] = [];
+    createLabStore({
+      storageKey: 'test',
+      storage,
+      configDefaults: { T: () => ({ grid: { size: 20, color: '#fff' } }) },
+      serializers: {
+        T: {
+          deserialize: (state, config) => {
+            seen.push(config);
+            return state;
+          },
+        },
+      },
+    });
+    expect(seen).toEqual([{ grid: { size: 40, color: '#fff' } }]);
+  });
+
+  it('leaves a config alone when no defaults are registered for its instrument', () => {
+    const storage = createMemoryAdapter();
+    storage.write(labDocumentKey('test'), stored({ only: 1 }));
+    const s = createLabStore({ storageKey: 'test', storage });
+    expect(s.getState().trials[0]?.config).toEqual({ only: 1 });
+  });
 });
 
 describe('setMode', () => {
@@ -222,6 +326,56 @@ describe('persistence — hydration', () => {
     expect(hydrated.getState().trials).toHaveLength(1);
     expect((hydrated.getState().trials[0]?.state as { n: number }).n).toBe(7);
   });
+
+  // An instrument holding a Map, a Set or anything else JSON drops needs these
+  // to run at both ends. They are read while the store is being built, which
+  // is why they arrive as an option rather than being registered afterwards.
+  it("runs an instrument's serializers at flush and at hydrate", () => {
+    vi.useFakeTimers();
+    const mem = createMemoryAdapter();
+    const serializers = {
+      T: {
+        serialize: (state: unknown) => [...(state as Map<string, number>)],
+        deserialize: (data: unknown) => new Map(data as [string, number][]),
+      },
+    };
+
+    const seed = createLabStore({ storageKey: 'test', storage: mem, serializers });
+    seed.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config: {},
+      state: new Map([['a', 1]]),
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    vi.advanceTimersByTime(500);
+    vi.useRealTimers();
+
+    const written = mem.read(labDocumentKey('test')) ?? '';
+    expect(written).toContain('[["a",1]]');
+
+    const hydrated = createLabStore({ storageKey: 'test', storage: mem, serializers });
+    expect(hydrated.getState().trials[0]?.state).toEqual(new Map([['a', 1]]));
+  });
+
+  it('hands `deserialize` the config the state was saved against', () => {
+    vi.useFakeTimers();
+    const mem = createMemoryAdapter();
+    const deserialize = vi.fn((data: unknown) => data);
+    const seed = createLabStore({ storageKey: 'test', storage: mem });
+    seed.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { scale: 4 },
+      state: { n: 1 },
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    vi.advanceTimersByTime(500);
+    vi.useRealTimers();
+
+    createLabStore({ storageKey: 'test', storage: mem, serializers: { T: { deserialize } } });
+    expect(deserialize).toHaveBeenCalledWith({ n: 1 }, { scale: 4 });
+  });
 });
 
 describe('persistence — debounced writes', () => {

package/src/state/store.ts

@@ -1,4 +1,5 @@
 import { createStore, type StoreApi } from 'zustand/vanilla';
+import { fillConfigDefaults, withValueAtPath } from '../config/path';
 import {
   CURRENT_DOCUMENT_VERSION,
   deleteLegacyKeys,
@@ -13,7 +14,6 @@ import {
 import { deserializeTrials, emptyUndoStack, serializeTrials } from './helpers';
 import type {
   CreateLabStoreOptions,
-  InstrumentSerializers,
   LabDocument,
   LabMode,
   LabStoreState,
@@ -32,7 +32,9 @@ export interface LabStoreActions {
   addTrial: (record: Omit<TrialRecord, 'undoStack'>) => void;
   removeTrial: (id: string) => void;
   updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
-  updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
+  /** Write one config value. `path` is dotted for a value nested under an
+   *  `f.group`, and the bare key for one at the root. */
+  updateTrialConfig: (id: string, path: string, value: unknown) => void;
   updateTrialView: (id: string, view: unknown) => void;
   updateTrialSidebarWidth: (id: string, width: number) => void;
   /** Retitle a trial. `null` returns it to its instrument's name. */
@@ -59,16 +61,14 @@ export interface LabStoreActions {
   dockPanel: (trialId: string, sectionId?: string) => void;
 }
 
-/** A lab's store: its state and actions, plus the hook instruments use to
- *  register how their state is serialized. */
-export type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
-  registerSerializers: (s: InstrumentSerializers) => void;
-};
+/** A lab's store: its state and its actions. How each instrument's state is
+ *  serialized comes in through `CreateLabStoreOptions.serializers`. */
+export type LabStore = StoreApi<LabStoreState & LabStoreActions>;
 
 /** Build a lab store, hydrating from storage if anything was saved under the
  *  same key. Writes back are debounced. */
 export function createLabStore(options: CreateLabStoreOptions): LabStore {
-  let serializers: InstrumentSerializers = {};
+  const serializers = options.serializers ?? {};
   let flushTimer: ReturnType<typeof setTimeout> | null = null;
 
   const hydration = hydrateDocument(options);
@@ -77,8 +77,20 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
   // Cleared once the legacy keys are actually gone; see the flush.
   let foldedFromLegacy = hydration.foldedFromLegacy;
 
-  const hydratedTrials = deserializeTrials(hydrated.trials, serializers);
-  const hydratedSnapshots = hydrated.saves;
+  const configDefaults = options.configDefaults ?? {};
+  const filled = (instrumentName: string, config: unknown): unknown => {
+    const defaults = configDefaults[instrumentName];
+    return defaults ? fillConfigDefaults(config, defaults()) : config;
+  };
+
+  const hydratedTrials = deserializeTrials(
+    hydrated.trials.map((t) => ({ ...t, config: filled(t.instrumentName, t.config) })),
+    serializers,
+  );
+  const hydratedSnapshots = hydrated.saves.map((sn) => ({
+    ...sn,
+    config: filled(sn.instrumentName, sn.config),
+  }));
   const hydratedLayout = hydrated.layout;
   const hydratedMode = hydrated.mode;
 
@@ -121,15 +133,11 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
-    updateTrialConfig: (id, key, value) => {
+    updateTrialConfig: (id, path, value) => {
       set((s) => ({
-        trials: s.trials.map((w) => {
-          if (w.id !== id) return w;
-          return {
-            ...w,
-            config: { ...(w.config as Record<string, unknown>), [key as string]: value },
-          };
-        }),
+        trials: s.trials.map((w) =>
+          w.id === id ? { ...w, config: withValueAtPath(w.config, path, value) } : w,
+        ),
       }));
       scheduleFlush();
     },
@@ -237,7 +245,9 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         return;
       }
       const reg = serializers[snapshot.instrumentName];
-      const restoredState = reg?.deserialize ? reg.deserialize(snapshot.state) : snapshot.state;
+      const restoredState = reg?.deserialize
+        ? reg.deserialize(snapshot.state, snapshot.config)
+        : snapshot.state;
       set((s) => ({
         trials: s.trials.map((w) =>
           w.id === trialId ? { ...w, state: restoredState, config: snapshot.config } : w,
@@ -313,11 +323,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
   // fold; the flush is what removes the legacy keys.
   if (foldedFromLegacy) scheduleFlush();
 
-  return Object.assign(store, {
-    registerSerializers(s: InstrumentSerializers) {
-      serializers = s;
-    },
-  });
+  return store;
 }
 
 interface HydrateResult {

package/src/state/types.ts

@@ -1,3 +1,4 @@
+import type { ConfigPath, ValueAtPath } from '../config/types';
 import type { UndockedPanels } from './undock';
 /** A trial's undo history, as snapshots of its state either side of the
  *  present. */
@@ -95,7 +96,9 @@ export interface TrialStateHandle<TS, TC> {
   state: TS;
   setState: (next: TS | ((prev: TS) => TS)) => void;
   config: TC;
-  setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
+  /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+   *  an `f.group`, `'cellSize'` for one at the root. */
+  setConfig: <P extends ConfigPath<TC> & string>(path: P, value: ValueAtPath<TC, P>) => void;
 }
 
 /** Options for `createLabStore`. `storageKey` namespaces the keys written, so
@@ -104,13 +107,31 @@ export interface CreateLabStoreOptions {
   storageKey: string;
   storage: StorageAdapter;
   initialMode?: LabMode;
+  /** Each instrument's default config, keyed by instrument name, used to fill
+   *  the gaps in a stored one. A config saved before its schema grew a branch
+   *  arrives holding that branch's defaults rather than `undefined`, and keeps
+   *  whatever keys the schema has since stopped naming. `<Lab>` collects these
+   *  off its `instruments`. */
+  configDefaults?: Record<string, () => unknown>;
+  /** How each instrument's state survives a reload. Hydration is the first
+   *  thing `createLabStore` does, so these have to arrive with the store —
+   *  anything registered afterwards is already too late to read the document
+   *  it was built from. `<Lab>` collects them off its `instruments`. */
+  serializers?: InstrumentSerializers;
 }
 
 /** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
- *  instrument whose state is already JSON-safe needs no entry. */
+ *  instrument whose state is already JSON-safe needs no entry. `deserialize`
+ *  is handed the config the state was saved against — a trial's own for a
+ *  reload, the snapshot's for a load — since a state rebuilt without it can
+ *  disagree with the settings sitting next to it. */
 export type InstrumentSerializers = Record<
   string,
-  { serialize?: (state: unknown) => unknown; deserialize?: (data: unknown) => unknown } | undefined
+  | {
+      serialize?: (state: unknown) => unknown;
+      deserialize?: (data: unknown, config: unknown) => unknown;
+    }
+  | undefined
 >;
 
 /** A trial as it is persisted: everything but the undo history, which is

package/src/state/useTrialState.ts

@@ -24,6 +24,6 @@ export function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS
     state: record.state as TS,
     config: record.config as TC,
     setState: (next) => updateTrialState(trialId, next as Parameters<typeof updateTrialState>[1]),
-    setConfig: (key, value) => updateTrialConfig(trialId, key as never, value as never),
+    setConfig: (path, value) => updateTrialConfig(trialId, path, value),
   };
 }

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

@@ -106,3 +106,47 @@ describe('lab-wide config seams', () => {
     expect(screen.queryByText('Settings')).not.toBeInTheDocument();
   });
 });
+
+describe('a nested config value, end to end', () => {
+  const nestedInstrument = () => {
+    const seen: { config: unknown; prev: unknown }[] = [];
+    const instrument = defineInstrument({
+      name: 'Nested',
+      config: f.schema({
+        showGrid: f.boolean(true),
+        grid: f.group({ size: f.number(20).label('Cell size'), color: f.color('#ffffff') }),
+      }),
+      initialState: () => ({}),
+      onConfigChange: (config, prev, state) => {
+        seen.push({ config, prev });
+        return state;
+      },
+      render: (ctx) => (
+        <output>{String((ctx.config as { grid: { size: number } }).grid.size)}</output>
+      ),
+    });
+    return { instrument, seen };
+  };
+
+  it('renders a nested leaf and writes the change back into the tree', () => {
+    const { instrument } = nestedInstrument();
+    render(<Lab instruments={[instrument]} defaultInstrument="Nested" />);
+    expect(screen.getByText('20')).toBeInTheDocument();
+    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' } });
+    expect(seen.at(-1)?.config).toEqual({
+      showGrid: true,
+      grid: { size: 40, color: '#ffffff' },
+    });
+    expect(seen.at(-1)?.prev).toEqual({
+      showGrid: true,
+      grid: { size: 20, color: '#ffffff' },
+    });
+  });
+});

package/src/trial/Trial.tsx

@@ -239,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);
     },

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';
@@ -135,16 +136,20 @@ 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);
         }

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';
 
@@ -27,15 +28,10 @@ export interface AddTrialOptions<TC = Record<string, unknown>> {
   config?: Partial<TC>;
 }
 
-/** `defaultConfig()` with `seed` written over it. Config is flat — a leaf's
- *  path is its config key — so this is the whole merge. */
+/** `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 {
-  if (!seed) return defaults;
-  const out = { ...defaults };
-  for (const [key, value] of Object.entries(seed)) {
-    if (value !== undefined) (out as Record<string, unknown>)[key] = value;
-  }
-  return out;
+  return seed ? fillConfigDefaults(seed, defaults) : defaults;
 }
 
 /** Append a new trial running `instrumentName`, at that instrument's default