@weasel-js/labkit 1.5.0 → 1.5.1

package/src/state/Persistence.stories.tsx

@@ -1,6 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { expect, userEvent, waitFor, within } from '@weasel-js/forge/play';
 import { useState } from 'react';
-import { expect, userEvent, waitFor, within } from 'storybook/test';
 import { createIndexedDbAdapter } from './adapters';
 import { Persistence } from './Persistence';
 import { usePersistedState } from './usePersistedState';
@@ -64,11 +64,11 @@ export const SurvivesARemountInIndexedDb: StoryObj<typeof Remountable> = {
   args: { database: `labkit-story-${Date.now()}` },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    await waitFor(() => expect(canvas.getByLabelText('tab')).toHaveTextContent('shape'));
+    await waitFor(() => expect(canvas.getByLabelText('tab').textContent).toBe('shape'));
     await userEvent.click(canvas.getByText('choose color'));
     await userEvent.click(canvas.getByText('remount'));
     await waitFor(() => expect(canvas.queryByLabelText('tab')).toBeNull());
-    await waitFor(() => expect(canvas.getByLabelText('tab')).toHaveTextContent('color'), {
+    await waitFor(() => expect(canvas.getByLabelText('tab').textContent).toBe('color'), {
       timeout: 3000,
     });
   },

package/src/state/store.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { auto } from '../config/auto';
 import type { Instrument } from '../instrument/types';
 import { createLabStore } from './store';
 import type { CreateLabStoreOptions } from './types';
@@ -163,6 +164,70 @@ describe('save/load/delete snapshots', () => {
     expect((s.getState().trials[0]?.state as { n: number }).n).toBe(5);
   });
 
+  it('loadSnapshot restores the auto paths the trial had when saved', () => {
+    const s = makeStore();
+    s.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1, y: 2 },
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+      auto: ['x'],
+    });
+    s.getState().saveSnapshot('w1', 'snap1');
+    expect(s.getState().savedSnapshots[0]?.auto).toEqual(['x']);
+    const snapId = s.getState().savedSnapshots[0]?.id ?? '';
+
+    const w = s.getState().trials[0];
+    s.getState().addTrial({ ...(w as NonNullable<typeof w>), id: 'w2', auto: ['y'] });
+    s.getState().loadSnapshot(snapId, 'w2');
+    expect(s.getState().trials[1]?.auto).toEqual(['x']);
+  });
+
+  it('a snapshot saved with nothing auto pins every field on load', () => {
+    const s = makeStore();
+    s.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1 },
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+    });
+    s.getState().saveSnapshot('w1', 'snap1');
+    expect(s.getState().savedSnapshots[0]?.auto).toEqual([]);
+    const snapId = s.getState().savedSnapshots[0]?.id ?? '';
+    s.getState().updateTrialConfig('w1', 'x', auto);
+    expect(s.getState().trials[0]?.auto).toEqual(['x']);
+    s.getState().loadSnapshot(snapId, 'w1');
+    expect(s.getState().trials[0]?.auto).toBeUndefined();
+  });
+
+  it("a snapshot saved before snapshots carried auto paths leaves the trial's own", () => {
+    const snap = {
+      id: 'old',
+      name: 'old',
+      trialId: 'w1',
+      instrumentName: 'T',
+      config: { x: 7 },
+      state: {},
+      savedAt: 1,
+    };
+    const s = makeStore({
+      initial: { version: 1, trials: [], saves: [snap], mode: 'auto' } as never,
+    });
+    s.getState().addTrial({
+      id: 'w1',
+      instrumentName: 'T',
+      config: { x: 1 },
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+      auto: ['x'],
+    });
+    s.getState().loadSnapshot('old', 'w1');
+    expect(s.getState().trials[0]?.config).toEqual({ x: 7 });
+    expect(s.getState().trials[0]?.auto).toEqual(['x']);
+  });
+
   it('loadSnapshot blocks cross-instrument load', () => {
     const s = makeStore();
     s.getState().addTrial({

package/src/state/store.ts

@@ -1,6 +1,12 @@
 import { createStore, type StoreApi } from 'zustand/vanilla';
-import { fillConfigDefaults, withValueAtPath } from '../config/path';
-import { configDefaultsOf, configMigrationsOf, serializersOf } from '../instrument/serializers';
+import { applyConfigWrite } from '../config/autoConfig';
+import { fillConfigDefaults } from '../config/path';
+import {
+  configDefaultsOf,
+  configMigrationsOf,
+  configSchemasOf,
+  serializersOf,
+} from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
 import { emptyDocument } from './document';
 import { deserializeTrials, emptyUndoStack, newId } from './helpers';
@@ -75,6 +81,7 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
         serializers: options.serializers ?? {},
         configDefaults: options.configDefaults ?? {},
         configMigrations: options.configMigrations ?? {},
+        configSchemas: options.configSchemas ?? {},
       };
   const initial = options.initial ?? emptyDocument(options.initialMode ?? 'auto');
 
@@ -117,9 +124,18 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
 
     updateTrialConfig: (id, path, value) => {
       set((s) => ({
-        trials: s.trials.map((w) =>
-          w.id === id ? { ...w, config: withValueAtPath(w.config, path, value) } : w,
-        ),
+        trials: s.trials.map((w) => {
+          if (w.id !== id) return w;
+          const was = w.auto ?? [];
+          // The sentinel is never stored: it becomes membership in `auto`, and
+          // the pinned value at the path is left exactly where it is.
+          const next = applyConfigWrite(w.config, was, path, value);
+          if (next.config === w.config && next.autoPaths === was) return w;
+          const { auto: _was, ...kept } = w;
+          const record: TrialRecord = { ...kept, config: next.config };
+          if (next.autoPaths.length > 0) record.auto = next.autoPaths;
+          return record;
+        }),
       }));
     },
 
@@ -202,6 +218,7 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
         instrumentName: trial.instrumentName,
         config: clonedConfig,
         state: serializedState,
+        auto: [...(trial.auto ?? [])],
         savedAt,
       };
       set((s) => ({ savedSnapshots: [...s.savedSnapshots, snapshot] }));
@@ -223,9 +240,14 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
         ? 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,
-        ),
+        trials: s.trials.map((w) => {
+          if (w.id !== trialId) return w;
+          const loaded: TrialRecord = { ...w, state: restoredState, config: snapshot.config };
+          if (snapshot.auto === undefined) return loaded;
+          delete loaded.auto;
+          if (snapshot.auto.length > 0) loaded.auto = [...snapshot.auto];
+          return loaded;
+        }),
       }));
     },
 
@@ -302,6 +324,7 @@ function hooksOf(instruments: InstrumentList): InstrumentHooks {
   return {
     serializers: serializersOf(instruments),
     configDefaults: configDefaultsOf(instruments),
+    configSchemas: configSchemasOf(instruments),
     configMigrations: configMigrationsOf(instruments),
   };
 }
@@ -317,6 +340,7 @@ function mergedHooks(old: InstrumentHooks, instruments: InstrumentList): Instrum
   return {
     serializers: { ...unlisted(old.serializers), ...fresh.serializers },
     configDefaults: { ...unlisted(old.configDefaults), ...fresh.configDefaults },
+    configSchemas: { ...unlisted(old.configSchemas), ...fresh.configSchemas },
     configMigrations: { ...unlisted(old.configMigrations), ...fresh.configMigrations },
   };
 }

package/src/state/types.ts

@@ -1,4 +1,5 @@
-import type { ConfigPath, ValueAtPath } from '../config/types';
+import type { Auto } from '../config/auto';
+import type { ConfigPath, ResolvedConfig, ValueAtPath } from '../config/types';
 import type { InstrumentList } from '../instrument/types';
 import type { UndockedPanels } from './undock';
 /** A trial's undo history, as snapshots of its state either side of the
@@ -31,6 +32,15 @@ export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
    *  defaults. Kept so Reset restores the trial's own subject rather than the
    *  bare defaults. */
   configSeed?: Partial<TC>;
+  /** Dotted paths the trial's seed config opened as auto. Kept beside
+   *  `configSeed`, which cannot carry them: the sentinel is stripped on the way
+   *  in, so Reset would otherwise have no way back to the state the trial
+   *  opened in. Absent means none. */
+  autoSeed?: readonly string[];
+  /** Dotted paths this trial has unpinned. The value at such a path stays in
+   *  `config` — it is what the field pins back to — but the instrument reads
+   *  the resolver's value, or `undefined`, instead. Absent means none. */
+  auto?: readonly string[];
   /** This trial's own tool slot. Undefined means it reads the lab's. */
   activeToolId?: string | null;
   /** The extent the trial's sidebar was last dragged to, in pixels. Undefined
@@ -60,6 +70,10 @@ export interface SavedSnapshot {
   instrumentName: string;
   config: unknown;
   state: unknown;
+  /** The trial's `auto` paths when saved; empty means every field was pinned.
+   *  Absent on a snapshot saved before snapshots carried them, which loads
+   *  over the trial's current set rather than guessing one. */
+  auto?: readonly string[];
   savedAt: number;
 }
 
@@ -111,9 +125,14 @@ export interface TrialStateHandle<TS, TC> {
   state: TS;
   setState: (next: TS | ((prev: TS) => TS)) => void;
   config: TC;
+  /** The config as stored, before any auto path is resolved. What the control
+   *  panel renders, so a ghosted control sits at the value it pins back to. */
+  raw: TC;
+  /** Dotted paths this trial has unpinned. */
+  auto: ReadonlySet<string>;
   /** 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;
+  setConfig: <P extends ConfigPath<TC> & string>(path: P, value: ValueAtPath<TC, P> | Auto) => void;
 }
 
 /** Options for `createLabStore`, which knows nothing about storage. */
@@ -129,6 +148,10 @@ export interface CreateLabStoreOptions {
   /** Each instrument's `migrateConfig`, keyed by instrument name, run on a
    *  stored config before its defaults fill it. */
   configMigrations?: Record<string, (stored: unknown) => unknown>;
+  /** Each instrument's resolved config schema, keyed by instrument name. What
+   *  a trial's auto paths are read against, away from the lab that would
+   *  otherwise supply the rules. */
+  configSchemas?: Record<string, ResolvedConfig>;
   /** How each instrument's state survives a reload. Hydration is the first
    *  thing `createLabStore` does, so these have to arrive with the store. */
   serializers?: InstrumentSerializers;
@@ -142,6 +165,7 @@ export interface InstrumentHooks {
   serializers: InstrumentSerializers;
   configDefaults: Record<string, () => unknown>;
   configMigrations: Record<string, (stored: unknown) => unknown>;
+  configSchemas: Record<string, ResolvedConfig>;
 }
 
 /** Per-instrument serialize/deserialize hooks, keyed by instrument name. An

package/src/state/useTrialState.test.tsx

@@ -1,6 +1,10 @@
 import { act, renderHook } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { describe, expect, it } from 'vitest';
+import { auto } from '../config/auto';
+import { f } from '../config/builder';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { Instrument } from '../instrument/types';
 import { LabStoreProvider, TrialIdProvider } from './context';
 import { createLabStore } from './store';
 import { useTrialState } from './useTrialState';
@@ -99,3 +103,84 @@ describe('useTrialState', () => {
     expect(() => renderHook(() => useTrialState())).toThrow('[labkit]');
   });
 });
+
+const autoInstrument = defineInstrument({
+  name: 'Auto',
+  config: f.schema({
+    width: f.number(432),
+    gap: f.number(12).auto((c) => (c.width as number) / 24),
+  }),
+  initialState: () => ({ count: 0 }),
+  render: () => null,
+});
+
+function makeAutoWrapper(trialId: string) {
+  const store = createLabStore({ instruments: [autoInstrument as Instrument] });
+  store.getState().addTrial({
+    id: trialId,
+    instrumentName: 'Auto',
+    config: autoInstrument.defaultConfig(),
+    state: { count: 0 },
+    view: { zoom: 1, pan: { x: 0, y: 0 } },
+  });
+  return {
+    store,
+    wrapper: ({ children }: { children: ReactNode }) => (
+      <LabStoreProvider store={store}>
+        <TrialIdProvider trialId={trialId}>{children}</TrialIdProvider>
+      </LabStoreProvider>
+    ),
+  };
+}
+
+describe('auto paths', () => {
+  it('hands the instrument the resolved config and the raw one separately', () => {
+    const { store, wrapper } = makeAutoWrapper('w1');
+    const { result } = renderHook(
+      () => useTrialState<{ count: number }, { width: number; gap: number }>(),
+      { wrapper },
+    );
+    act(() => store.getState().updateTrialConfig('w1', 'gap', auto));
+    expect(result.current.config.gap).toBe(18);
+    expect(result.current.raw.gap).toBe(12);
+    expect([...result.current.auto]).toEqual(['gap']);
+  });
+
+  it('leaves a pinned config untouched', () => {
+    const { wrapper } = makeAutoWrapper('w1');
+    const { result } = renderHook(
+      () => useTrialState<{ count: number }, { width: number; gap: number }>(),
+      { wrapper },
+    );
+    expect(result.current.config.gap).toBe(12);
+    expect(result.current.config).toBe(result.current.raw);
+    expect([...result.current.auto]).toEqual([]);
+  });
+
+  it('records a path written as auto instead of storing the sentinel', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', 24);
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    const rec = store.getState().trials[0];
+    expect(rec?.auto).toEqual(['gap']);
+    // The last pinned value survives, so un-pinning is lossless.
+    expect(rec?.config).toEqual({ width: 432, gap: 24 });
+  });
+
+  it('pins again when a real value is written to an auto path', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    store.getState().updateTrialConfig('w1', 'gap', 30);
+    const rec = store.getState().trials[0];
+    expect(rec?.auto).toBeUndefined();
+    expect((rec?.config as { gap: number }).gap).toBe(30);
+  });
+
+  it('does not allocate a new record when the path is already auto', () => {
+    const { store } = makeAutoWrapper('w1');
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    const first = store.getState().trials[0];
+    store.getState().updateTrialConfig('w1', 'gap', auto);
+    expect(store.getState().trials[0]).toBe(first);
+  });
+});

package/src/state/useTrialState.ts

@@ -1,5 +1,6 @@
 import { useContext } from 'react';
 import { useStore } from 'zustand/react';
+import { useResolvedConfig } from '../config/useResolvedConfig';
 import { LabStoreContext, TrialIdContext } from './context';
 import type { TrialStateHandle } from './types';
 
@@ -19,10 +20,17 @@ export function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS
 
   const updateTrialState = useStore(ctx.store, (s) => s.updateTrialState);
   const updateTrialConfig = useStore(ctx.store, (s) => s.updateTrialConfig);
+  // The store's own copy, not `useConfigSchema`: that reads `LabContext`, and
+  // this hook only has the store's.
+  const instrumentHooks = useStore(ctx.store, (s) => s.instrumentHooks);
+  const schema = instrumentHooks().configSchemas[record.instrumentName];
+  const { config, auto } = useResolvedConfig<TC>(schema, record.config as TC, record.auto);
 
   return {
     state: record.state as TS,
-    config: record.config as TC,
+    config,
+    raw: record.config as TC,
+    auto,
     setState: (next) => updateTrialState(trialId, next as Parameters<typeof updateTrialState>[1]),
     setConfig: (path, value) => updateTrialConfig(trialId, path, value),
   };

package/src/styles.less

@@ -25,3 +25,4 @@
 @import './annotations/Annotations.less';
 @import './dragdrop/Palette.less';
 @import './dragdrop/DragGhost.less';
+@import './specimen/Specimen.less';

package/src/surface/index.ts

@@ -1,8 +1,8 @@
 export { composeRects, rectsEqual } from './composeRects';
 export { toDeviceRect } from './deviceRect';
 export type { Box, Rect } from './rect';
-export { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
 export type { SurfaceCanvases, SurfaceLayer } from './SurfaceContext';
+export { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
 export {
   useSurface,
   useSurfaceCanvas,

package/src/surface/useSurfaceTile.test.tsx

@@ -11,7 +11,7 @@ function fakeHandle(): SurfaceHandle {
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
     registerClear: vi.fn(() => () => {}),
-  registerPainter: vi.fn(() => () => {}),
+    registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),
   };

package/src/surface/useTiledSurface.test.tsx

@@ -1,4 +1,4 @@
-import { act, render } from '@testing-library/react';
+import { act, render, renderHook } from '@testing-library/react';
 import { useEffect } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
@@ -315,8 +315,20 @@ describe('useTiledSurface', () => {
               surface.containerRef(el);
             }}
           >
-            <div ref={(el) => { if (!el) return; stubBox(el, 0, 0, 400, 600); surface.registerTile('a', el); }} />
-            <div ref={(el) => { if (!el) return; stubBox(el, 400, 0, 400, 600); surface.registerTile('b', el); }} />
+            <div
+              ref={(el) => {
+                if (!el) return;
+                stubBox(el, 0, 0, 400, 600);
+                surface.registerTile('a', el);
+              }}
+            />
+            <div
+              ref={(el) => {
+                if (!el) return;
+                stubBox(el, 400, 0, 400, 600);
+                surface.registerTile('b', el);
+              }}
+            />
           </div>
         );
       }
@@ -345,7 +357,12 @@ describe('useTiledSurface', () => {
       const frames: SurfaceFrame[] = [];
       let handle: SurfaceHandle | null = null;
       const { getByTestId } = render(
-        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
       );
       flushFrames();
       frames.length = 0;
@@ -368,7 +385,12 @@ describe('useTiledSurface', () => {
       const frames: SurfaceFrame[] = [];
       let handle: SurfaceHandle | null = null;
       const { getByTestId } = render(
-        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
       );
       flushFrames();
 
@@ -407,7 +429,12 @@ describe('useTiledSurface', () => {
       const frames: SurfaceFrame[] = [];
       let handle: SurfaceHandle | null = null;
       const { getByTestId } = render(
-        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
       );
       flushFrames();
 
@@ -423,8 +450,18 @@ describe('useTiledSurface', () => {
       const stops = [340, 370, 400, 400, 400];
       let call = 0;
       vi.spyOn(b, 'getBoundingClientRect').mockImplementation(() => {
-        const left = stops[Math.min(call++, stops.length - 1)]!;
-        return { left, top: 0, width: 400, height: 600, right: left + 400, bottom: 600, x: left, y: 0, toJSON: () => ({}) } as DOMRect;
+        const left = stops[Math.min(call++, stops.length - 1)] ?? 0;
+        return {
+          left,
+          top: 0,
+          width: 400,
+          height: 600,
+          right: left + 400,
+          bottom: 600,
+          x: left,
+          y: 0,
+          toJSON: () => ({}),
+        } as DOMRect;
       });
 
       seen.length = 0;
@@ -442,13 +479,20 @@ describe('useTiledSurface', () => {
       const frames: SurfaceFrame[] = [];
       let handle: SurfaceHandle | null = null;
       const { getByTestId } = render(
-        <Harness frames={frames} onHandle={(h) => { handle = h; }} />,
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
       );
       flushFrames();
 
       const clear = vi.fn();
       let off: (() => void) | undefined;
-      act(() => { off = handle?.registerClear('a', clear); });
+      act(() => {
+        off = handle?.registerClear('a', clear);
+      });
       stubBox(getByTestId('b'), 310, 0, 400, 600);
       act(() => handle?.invalidateRects());
       flushFrames();
@@ -462,3 +506,14 @@ describe('useTiledSurface', () => {
     });
   });
 });
+
+describe('useTiledSurface handle identity', () => {
+  it('returns the same handle across renders', () => {
+    // A new handle per render reaches useSurfaceTile through context as a new
+    // ref callback, which unregisters and re-registers every tile and retiles.
+    const { result, rerender } = renderHook(() => useTiledSurface({ onFrame: () => {} }));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/surface/useTiledSurface.ts

@@ -1,5 +1,5 @@
 import { useVisibleRaf } from '@weasel-js/core';
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { composeRects, rectsEqual } from './composeRects';
 import type { Box, Rect } from './rect';
 
@@ -235,14 +235,26 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     };
   }, [schedule, frameLoop]);
 
-  return {
-    invalidate,
-    invalidateAll,
-    invalidateRects,
-    registerTile,
-    registerClear,
-    registerPainter,
-    containerRef,
-    getContainer,
-  };
+  return useMemo(
+    () => ({
+      invalidate,
+      invalidateAll,
+      invalidateRects,
+      registerTile,
+      registerClear,
+      registerPainter,
+      containerRef,
+      getContainer,
+    }),
+    [
+      invalidate,
+      invalidateAll,
+      invalidateRects,
+      registerTile,
+      registerClear,
+      registerPainter,
+      containerRef,
+      getContainer,
+    ],
+  );
 }

package/src/theme/Interstellar.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { TokenName } from '@weasel-js/theme';
 import { useTheme } from '@weasel-js/theme/react';
 import {
@@ -18,7 +18,7 @@ const meta: Meta = {
       description: {
         component:
           'The interstellar theme: deep-space cosmic gradient + starscape backdrop, glass surfaces, Oswald display type, purple accent. ' +
-          'Authored as DTCG in `src/theme/interstellar.tokens.json` and loaded with `loadDTCG`; it extends the built-in weasel theme, overriding values rather than adding tokens.',
+          'A pins-only theme definition in `src/theme/interstellar.theme.json`, loaded with `defineTheme`; it extends the built-in weasel theme, overriding values rather than adding tokens.',
       },
     },
   },

package/src/theme/interstellar.test.ts

@@ -1,11 +1,20 @@
-import { resolveTheme } from '@weasel-js/theme';
+import { resolveTheme, THEME_SOURCES, type ThemeDefinition } from '@weasel-js/theme';
+import { derive } from '@weasel-js/theme/engine';
 import { describe, expect, it } from 'vitest';
 import { interstellarTheme } from './interstellar';
+import definition from './interstellar.theme.json' with { type: 'json' };
 
 describe('interstellarTheme', () => {
+  it('derives as a definition extending weasel with no issues', () => {
+    const lookup = (name: string) => (name === 'weasel' ? THEME_SOURCES.weasel : undefined);
+    for (const mode of ['dark', 'light']) {
+      expect(derive(definition as ThemeDefinition, { mode }, lookup).issues, mode).toEqual([]);
+    }
+  });
+
   it('extends weasel and resolves both modes', () => {
-    const dark = resolveTheme(interstellarTheme, 'dark');
-    const light = resolveTheme(interstellarTheme, 'light');
+    const dark = resolveTheme(interstellarTheme, { mode: 'dark' });
+    const light = resolveTheme(interstellarTheme, { mode: 'light' });
 
     // Values carried over verbatim from the retired Less.
     expect(dark['--wzl-surface']).toBe('#0a0a14');
@@ -24,7 +33,9 @@ describe('interstellarTheme', () => {
   });
 
   it('carries the cosmic backdrop in dark and drops it in light', () => {
-    expect(resolveTheme(interstellarTheme, 'dark')['--wzl-backdrop']).toContain('radial-gradient');
-    expect(resolveTheme(interstellarTheme, 'light')['--wzl-backdrop']).toBe('none');
+    expect(resolveTheme(interstellarTheme, { mode: 'dark' })['--wzl-backdrop']).toContain(
+      'radial-gradient',
+    );
+    expect(resolveTheme(interstellarTheme, { mode: 'light' })['--wzl-backdrop']).toBe('none');
   });
 });