@weasel-js/labkit 1.4.2 → 1.4.4

package/src/lab/LabSwitcher.tsx

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+
+/** One page in a project's set of labs. */
+export interface LabPage {
+  /** The page's own URL, and how the switcher knows which page is open. */
+  href: string;
+  label: string;
+}
+
+/** Props for `<LabSwitcher>`. */
+export interface LabSwitcherProps {
+  /** The open page's title, shown as the control's own label. */
+  title: string;
+  pages: readonly LabPage[];
+  /** Defaults to the current location. Pass it in tests, or to render a
+   *  switcher for a page other than the one being viewed. */
+  path?: string;
+  className?: string;
+}
+
+/** Which of `pages` a path is on, or -1.
+ *
+ *  Matched on the end of the path so a query string, a trailing slash or a
+ *  leftover `.html` cannot lose it: a project whose dev server maps `/stats`
+ *  to `stats.html` serves both spellings, and a bookmark from before the URLs
+ *  lost their extension still resolves to the same page. */
+export function currentPage(path: string, pages: readonly LabPage[]): number {
+  const here = path.split('?')[0]!.split('#')[0]!
+    .replace(/\/$/, '').replace(/\.html$/, '');
+  return pages.findIndex((p) => here.endsWith(p.href.replace(/\.html$/, '')));
+}
+
+/** A project's lab title, doubling as the way to reach its other labs.
+ *
+ *  The menu holds real anchors, not a `<select>` and not buttons. These are
+ *  separate documents, so an `href` is what gets middle-click, cmd-click and
+ *  the back button for free; a select fires a change event and can do none of
+ *  the three. The trigger is a button because it opens something rather than
+ *  going anywhere.
+ *
+ *  Pages accumulate -- a project grows a wall, a dashboard, an ingest page, a
+ *  bench -- and a tab strip is the layout that stops working first. */
+export function LabSwitcher({ title, pages, path, className }: LabSwitcherProps) {
+  const [open, setOpen] = useState(false);
+  const root = useRef<HTMLDivElement>(null);
+  const menuId = useId();
+  const here = currentPage(path ?? (typeof window === 'undefined'
+    ? '' : window.location.pathname), pages);
+
+  const close = useCallback(() => setOpen(false), []);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        close();
+        root.current?.querySelector('button')?.focus();
+      }
+    };
+    // Pointer, not click: a press that starts outside should dismiss before
+    // whatever it lands on reacts, the way every other menu on the page does.
+    const onDown = (e: PointerEvent) => {
+      if (!root.current?.contains(e.target as Node)) close();
+    };
+    document.addEventListener('keydown', onKey);
+    document.addEventListener('pointerdown', onDown);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.removeEventListener('pointerdown', onDown);
+    };
+  }, [open, close]);
+
+  // One lab is not a set to choose from, and a disclosure arrow promising a
+  // menu of itself is worse than no control.
+  if (pages.length < 2) {
+    return <h1 className={`lk-switcher-title${className ? ` ${className}` : ''}`}>{title}</h1>;
+  }
+
+  return (
+    <div className={`lk-switcher${className ? ` ${className}` : ''}`} ref={root}>
+      <h1 className="lk-switcher-title">
+        <button
+          type="button"
+          className="lk-switcher-trigger"
+          aria-expanded={open}
+          aria-haspopup="menu"
+          aria-controls={open ? menuId : undefined}
+          onClick={() => setOpen((was) => !was)}
+        >
+          {title}
+          <span className="lk-switcher-caret" aria-hidden="true" />
+        </button>
+      </h1>
+      {open && (
+        <div className="lk-switcher-menu" id={menuId} role="menu">
+          {pages.map((page, i) => (
+            <a
+              key={page.href}
+              href={page.href}
+              role="menuitem"
+              className="lk-switcher-item"
+              aria-current={i === here ? 'page' : undefined}
+              onClick={close}
+            >
+              {page.label}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/lab/index.ts

@@ -6,5 +6,7 @@ export type { LabPaletteProps } from './LabPalette';
 export { LabPalette } from './LabPalette';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
+export type { LabPage, LabSwitcherProps } from './LabSwitcher';
+export { currentPage, LabSwitcher } from './LabSwitcher';
 export type { PanelDescriptor, TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

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.test.ts

@@ -4,6 +4,7 @@ import {
   deserializeTrials,
   emptyUndoStack,
   encodeUrlHash,
+  newId,
   labStorageKey,
   serializeTrials,
 } from './helpers';
@@ -114,4 +115,23 @@ describe('deserializeTrials', () => {
   it('returns an empty list when given something that is not an array', () => {
     expect(deserializeTrials(undefined as never, {})).toEqual([]);
   });
+
+  describe('newId', () => {
+    it('mints distinct ids', () => {
+      expect(newId()).not.toBe(newId());
+    });
+
+    it('falls back where crypto.randomUUID is absent', () => {
+      // What a lab reached by LAN IP gets: not a secure context, so the
+      // function is not there. It used to throw on the first render and show a
+      // blank page.
+      const real = globalThis.crypto;
+      Object.defineProperty(globalThis, 'crypto', { value: {}, configurable: true });
+      try {
+        expect(newId()).not.toBe(newId());
+      } finally {
+        Object.defineProperty(globalThis, 'crypto', { value: real, configurable: true });
+      }
+    });
+  });
 });

package/src/state/helpers.ts

@@ -25,6 +25,22 @@ export function decodeUrlHash(hash: string): string | null {
   }
 }
 
+/**
+ * An id for a trial or a snapshot.
+ *
+ * `crypto.randomUUID` exists only in a secure context, and a LAN address is
+ * not one — so a lab opened on a phone or a tablet by IP throws on its first
+ * render and shows a blank page with nothing in reach to say why. The counter
+ * is per page load, which is all these ids have to survive: they name records
+ * inside one session's store, and a saved snapshot carries its own name.
+ */
+let idCounter = 0;
+export function newId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+  return `lk-${Date.now().toString(36)}-${idCounter++}`;
+}
+
 /** A fresh, empty undo history. */
 export function emptyUndoStack(): UndoStack {
   return { past: [], future: [] };
@@ -58,7 +74,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,
@@ -10,10 +11,9 @@ import {
   readLegacyDocument,
   runMigrations,
 } from './document';
-import { deserializeTrials, emptyUndoStack, serializeTrials } from './helpers';
+import { deserializeTrials, emptyUndoStack, newId, 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();
     },
@@ -213,7 +221,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       const lastAt = get().savedSnapshots.reduce((m, sn) => (sn.savedAt > m ? sn.savedAt : m), 0);
       const savedAt = Math.max(Date.now(), lastAt + 1);
       const snapshot: SavedSnapshot = {
-        id: crypto.randomUUID(),
+        id: newId(),
         name,
         trialId,
         instrumentName: trial.instrumentName,
@@ -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/styles.less

@@ -2,6 +2,7 @@
 @import './theme/base.less';
 @import './lab/Workspace.less';
 @import './lab/LabShell.less';
+@import './lab/LabSwitcher.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Sidebar.less';
 @import './primitives/ZoomControl.less';

package/src/theme/base.less

@@ -79,13 +79,13 @@
     &::-webkit-slider-runnable-track {
       height: var(--wzl-slider-track-h);
       border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
     }
 
     &::-moz-range-track {
       height: var(--wzl-slider-track-h);
       border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
     }
 
     &::-webkit-slider-thumb {
@@ -95,7 +95,7 @@
       height: var(--wzl-slider-thumb-size);
       border: none;
       border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
       margin-top: calc((var(--wzl-slider-track-h) - var(--wzl-slider-thumb-size)) / 2);
     }
 
@@ -104,7 +104,7 @@
       height: var(--wzl-slider-thumb-size);
       border: none;
       border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-tint), transparent);
+      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
     }
   }
 }

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' },
+    });
+  });
+});