@weasel-js/labkit 1.5.0 → 1.5.2

package/src/theme/interstellar.theme.json

@@ -0,0 +1,180 @@
+{
+  "name": "interstellar",
+  "extends": "weasel",
+  "pins": {
+    "radius-md": {
+      "value": "6px",
+      "type": "dimension"
+    },
+    "glass-blur": {
+      "value": "12px",
+      "type": "dimension"
+    },
+    "font-weight-light": {
+      "value": 300,
+      "type": "fontWeight"
+    },
+    "font-weight-medium": {
+      "value": 500,
+      "type": "fontWeight"
+    },
+    "font-weight-bold": {
+      "value": 700,
+      "type": "fontWeight"
+    },
+    "surface": {
+      "by": "mode",
+      "dark": {
+        "value": "#0a0a14",
+        "type": "color"
+      },
+      "light": {
+        "value": "#fafaf7",
+        "type": "color"
+      }
+    },
+    "surface-raised": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(20, 20, 36, 0.55)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#ffffff",
+        "type": "color"
+      }
+    },
+    "surface-sunken": {
+      "by": "mode",
+      "dark": {
+        "value": "#02020a",
+        "type": "color"
+      },
+      "light": {
+        "value": "#f0ebe2",
+        "type": "color"
+      }
+    },
+    "border": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.14)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#c9bba5",
+        "type": "color"
+      }
+    },
+    "line-subtle": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.08)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(0, 0, 0, 0.08)",
+        "type": "color"
+      }
+    },
+    "fg": {
+      "by": "mode",
+      "dark": {
+        "value": "#e8e8f0",
+        "type": "color"
+      },
+      "light": {
+        "value": "#2a2018",
+        "type": "color"
+      }
+    },
+    "fg-muted": {
+      "by": "mode",
+      "dark": {
+        "value": "#a8a8c0",
+        "type": "color"
+      },
+      "light": {
+        "value": "#6b5c4a",
+        "type": "color"
+      }
+    },
+    "fg-subtle": {
+      "by": "mode",
+      "dark": {
+        "value": "#5a5a78",
+        "type": "color"
+      },
+      "light": {
+        "value": "#a89b85",
+        "type": "color"
+      }
+    },
+    "accent": {
+      "by": "mode",
+      "dark": {
+        "value": "#b08adb",
+        "type": "color"
+      },
+      "light": {
+        "value": "#a86f3c",
+        "type": "color"
+      }
+    },
+    "accent-hover": {
+      "by": "mode",
+      "dark": {
+        "value": "#c6a3ee",
+        "type": "color"
+      },
+      "light": {
+        "value": "#c2854f",
+        "type": "color"
+      }
+    },
+    "focus-ring": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(176, 138, 219, 0.45)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(168, 111, 60, 0.35)",
+        "type": "color"
+      }
+    },
+    "shadow": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(0, 0, 0, 0.7)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(80, 60, 40, 0.18)",
+        "type": "color"
+      }
+    },
+    "border-strong": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.36)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#9e8b71",
+        "type": "color"
+      }
+    },
+    "backdrop": {
+      "by": "mode",
+      "dark": {
+        "value": "radial-gradient(ellipse 60% 80% at 18% 30%, rgba(150, 80, 200, 0.22), transparent 70%), radial-gradient(ellipse 55% 90% at 78% 70%, rgba(220, 100, 140, 0.18), transparent 65%), radial-gradient(ellipse 50% 70% at 50% 50%, rgba(60, 110, 200, 0.18), transparent 75%), radial-gradient(ellipse at center, #0a0a18 0%, #02020a 100%)",
+        "type": "gradient"
+      },
+      "light": {
+        "value": "none",
+        "type": "gradient"
+      }
+    }
+  }
+}

package/src/theme/interstellar.ts

@@ -1,9 +1,12 @@
-import { loadDTCG, type Theme } from '@weasel-js/theme';
-import doc from './interstellar.tokens.json' with { type: 'json' };
+import { defineTheme, type Theme, type ThemeInput, weaselTheme } from '@weasel-js/theme';
+import definition from './interstellar.theme.json' with { type: 'json' };
 
 /**
  * labkit's theme: a cosmic dark and a warm parchment light, extending the
- * built-in weasel theme. Authored as DTCG and loaded at import time — the
- * interchange path a theme exported from a design tool would take.
+ * built-in weasel theme. A pins-only theme definition: nothing in it is
+ * derived, so it loads without the engine.
  */
-export const interstellarTheme: Theme = loadDTCG(doc);
+export const interstellarTheme: Theme = defineTheme({
+  ...definition,
+  extends: weaselTheme,
+} as ThemeInput);

package/src/tools/labTool.ts

@@ -2,10 +2,10 @@ import type { InstrumentList } from '../instrument/types';
 
 /**
  * The tool the lab's slot holds, once its default is applied: a lab with any
- * annotating instrument starts in `select`, so a first click on a picture
- * selects rather than draws.
+ * annotating instrument starts in `pointer`, so a first click reaches the
+ * instrument rather than the marks over it.
  */
 export function resolveLabTool(slot: string | null, instruments: InstrumentList): string | null {
   if (slot !== null) return slot;
-  return instruments.some((i) => i.annotations != null) ? 'select' : null;
+  return instruments.some((i) => i.annotations != null) ? 'pointer' : null;
 }

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

@@ -55,7 +55,16 @@ const plain = defineInstrument<Record<string, never>, Record<string, never>>({
 describe('an instrument that declares annotations', () => {
   it('gets a drawing palette', () => {
     render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
-    for (const label of ['Select', 'Freehand', 'Line', 'Arrow', 'Rectangle', 'Ellipse', 'Text']) {
+    for (const label of [
+      'Interact',
+      'Select',
+      'Freehand',
+      'Line',
+      'Arrow',
+      'Rectangle',
+      'Ellipse',
+      'Text',
+    ]) {
       expect(screen.getByRole('button', { name: label })).toBeTruthy();
     }
   });
@@ -65,9 +74,9 @@ describe('an instrument that declares annotations', () => {
     expect(screen.getByTestId('pane').dataset.marks).toBe('0');
   });
 
-  it('starts in select, so a first click does not draw', () => {
+  it('starts in interact, so a first click reaches the instrument', () => {
     render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
-    expect(screen.getByRole('button', { name: 'Select' }).getAttribute('aria-current')).toBe(
+    expect(screen.getByRole('button', { name: 'Interact' }).getAttribute('aria-current')).toBe(
       'true',
     );
   });
@@ -106,7 +115,7 @@ describe('the annotation tool', () => {
     act(() => labRef?.addTrial('Annotating'));
     const panes = screen.getAllByTestId('pane');
     expect(panes).toHaveLength(2);
-    for (const p of panes) expect(p.dataset.tool).toBe('select');
+    for (const p of panes) expect(p.dataset.tool).toBe('pointer');
 
     act(() => {
       fireEvent.click(screen.getByRole('button', { name: 'Rectangle' }));

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

@@ -1,7 +1,10 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { auto } from '../config/auto';
+import { f } from '../config/builder';
 import { defineInstrument } from '../instrument/defineInstrument';
+import type { Instrument } from '../instrument/types';
 import { Lab } from '../lab/Lab';
 
 interface St {
@@ -74,6 +77,39 @@ describe('an instrument that draws', () => {
   });
 });
 
+describe('an auto config path', () => {
+  it('draws with the resolved value, which is what the panel shows too', async () => {
+    const draw = vi.fn();
+    const instrument = defineInstrument({
+      name: 'Auto',
+      config: f.schema({
+        gap: f
+          .number(12)
+          .auto(() => 18)
+          .range(0, 48)
+          .initial(auto),
+      }),
+      initialState: () => ({ n: 0 }),
+      render: () => null,
+      canvas: { layers: [{ id: 'main', draw }] },
+    });
+    const { container } = render(
+      <Lab instruments={[instrument as Instrument]} defaultInstrument="Auto" />,
+    );
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    expect(draw).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ config: { gap: 18 } }),
+    );
+    // The panel is handed the raw config, but an auto row holds what the
+    // resolver decided, so pinning it keeps the number the instrument drew.
+    // The row hides its control while auto, which takes it out of the
+    // accessibility tree — so this reads the element rather than the role.
+    expect(container.querySelector('input[type=range]')).toHaveValue('18');
+  });
+});
+
 describe('LabProps.instruments', () => {
   it('accepts a typed instrument with no cast', () => {
     // The assignment is the assertion: this file fails to compile if

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

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

package/src/trial/Trial.less

@@ -14,6 +14,10 @@
   box-shadow: 0 1px 3px var(--wzl-shadow);
   overflow: hidden;
 
+  &[data-focused='true'] {
+    border-color: var(--wzl-accent);
+  }
+
   &__body {
     display: flex;
     flex: 1;

package/src/trial/Trial.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { Instrument } from '../instrument/types';
 import { LabContext, type LabContextValue } from '../lab/LabContext';
 import { LabStoreContext } from '../state/context';
@@ -35,6 +35,9 @@ function Harness() {
     closeTrial: noop,
     resetTrial: noop,
     reorderTrials: noop,
+    swapTrial: noop,
+    focusedTrialId: record.id,
+    focusTrial: noop,
     savedSnapshots: [],
     saveSnapshot: noop,
     loadSnapshot: noop,

package/src/trial/Trial.test.tsx

@@ -62,6 +62,9 @@ function ChromeHarness({
     closeTrial: vi.fn(),
     resetTrial: vi.fn(),
     reorderTrials: vi.fn(),
+    swapTrial: vi.fn(),
+    focusedTrialId: stubRecord.id,
+    focusTrial: vi.fn(),
     savedSnapshots: [],
     saveSnapshot: vi.fn(),
     loadSnapshot: vi.fn(),

package/src/trial/Trial.tsx

@@ -11,6 +11,8 @@ import { fitStage, Stage } from '../canvas/Stage';
 import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
 import { applyCamera, type ViewportSize } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
+import { useConfigSchema } from '../config/useConfigSchema';
+import { useResolvedConfig } from '../config/useResolvedConfig';
 import { DragOverlay, useDragDrop } from '../dragdrop/DragDropRuntime';
 import { Palette } from '../dragdrop/Palette';
 import type {
@@ -143,6 +145,11 @@ function TrialRuntime({
   const setLabTool = useStore(store, (s) => s.setLabTool);
   const setTrialTool = useStore(store, (s) => s.setTrialTool);
 
+  // Everything below reads `config`; `record.config` is the panel's view, and
+  // reaches it through `record` on `TrialChrome`.
+  const schema = useConfigSchema(instrument);
+  const { config } = useResolvedConfig(schema, record.config, record.auto);
+
   const busRef = useRef<EventBus | null>(null);
   if (busRef.current === null) busRef.current = createEventBus();
   const bus = busRef.current;
@@ -193,15 +200,15 @@ function TrialRuntime({
   const targetsRef = useRef<() => readonly AnnotationTargetInfo[]>(() => []);
   targetsRef.current = () =>
     annotationsCap
-      ? annotationsCap.targets(record.state, record.config, { id: record.id, view: record.view })
+      ? annotationsCap.targets(record.state, config, { id: record.id, view: record.view })
       : [];
 
   // One store for the trial's lifetime.
   const annotationsRef = useRef<ReturnType<typeof annotationsFromJSON> | null>(null);
   // Read through refs for the same reason `targets` is: the store is built
   // once, and an export must draw against the config the trial holds now.
-  const configRef = useRef<unknown>(record.config);
-  configRef.current = record.config;
+  const configRef = useRef<unknown>(config);
+  configRef.current = config;
   // The instrument can be swapped under a live trial, so the capability is read at use too.
   const capRef = useRef(annotationsCap);
   capRef.current = annotationsCap;
@@ -289,14 +296,14 @@ function TrialRuntime({
   // this — with a runner that yields nothing and is never started.
   const job = useJob({
     capability: jobCap ?? { run: async function* () {}, onItem: (_i, st) => st },
-    config: record.config,
+    config,
     state: record.state,
     setState: (next) => updateTrialState(record.id, next as never),
   });
 
   const renderCtx: RenderContext<unknown, unknown> = {
     state: record.state,
-    config: record.config,
+    config,
     setState: (next) => {
       snapshotIfNeeded('state.change');
       updateTrialState(record.id, next);
@@ -365,8 +372,8 @@ function TrialRuntime({
   const loupeCap = useMemo(() => {
     const declared = instrument.loupe;
     if (declared == null) return null;
-    return resolveLoupe(typeof declared === 'function' ? declared(record.config) : declared);
-  }, [instrument.loupe, record.config]);
+    return resolveLoupe(typeof declared === 'function' ? declared(config) : declared);
+  }, [instrument.loupe, config]);
   const loupeBindings: LoupeBindings | undefined = loupeCap
     ? { on: loupeOn, toggle: () => setLoupeOn((v) => !v) }
     : undefined;
@@ -384,10 +391,10 @@ function TrialRuntime({
         // Camera applied here, so a layer draws in world coordinates. `zoom`
         // stays in the args for line widths, which must not scale with it.
         applyCamera(ctx, view, frame);
-        layer.draw(ctx, { state: record.state, config: record.config, zoom: view.zoom });
+        layer.draw(ctx, { state: record.state, config, zoom: view.zoom });
       },
     }));
-  }, [instrument.canvas, record.state, record.config, layerVisibility, layerOrder]);
+  }, [instrument.canvas, record.state, config, layerVisibility, layerOrder]);
 
   const layerDescriptors: LayerDescriptor[] = useMemo(() => {
     if (!instrument.layers) return [];
@@ -400,7 +407,7 @@ function TrialRuntime({
     view: view2d ?? DEFAULT_VIEW,
     worldSpec: instrument.canvas?.worldSpec,
     state: record.state,
-    config: record.config,
+    config,
     setState: (next) => {
       snapshotIfNeeded('canvas.itemAdded');
       updateTrialState(record.id, next as never);
@@ -414,8 +421,8 @@ function TrialRuntime({
   const paletteItems: PaletteItem[] = useMemo(() => {
     if (!instrument.dragDrop) return [];
     const p = instrument.dragDrop.palette;
-    return typeof p === 'function' ? p(record.state, record.config) : p;
-  }, [instrument.dragDrop, record.state, record.config]);
+    return typeof p === 'function' ? p(record.state, config) : p;
+  }, [instrument.dragDrop, record.state, config]);
 
   const layersWithFeedback: CanvasLayerDescriptor[] = useMemo(() => {
     if (!dragDropResult.drag?.feedback) return canvasLayers;
@@ -449,7 +456,7 @@ function TrialRuntime({
       capability={loupeCap}
       enabled={loupeOn}
       state={record.state}
-      config={record.config}
+      config={config}
       view={view2d ?? DEFAULT_VIEW}
       worldSpec={instrument.canvas?.worldSpec}
       hostRef={loupeHostRef}
@@ -553,7 +560,7 @@ function TrialRuntime({
     <AnnotationTargets
       capability={annotationsCap}
       state={record.state}
-      config={record.config}
+      config={config}
       trial={{ id: record.id, view: record.view }}
       annotations={annotations}
       activeToolId={labTool}

package/src/trial/TrialChrome.tsx

@@ -9,8 +9,10 @@ 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 { applyConfigWrite, resolveAutoConfig } from '../config/autoConfig';
+import { hasConfigPath, schemaNodeAtPath } from '../config/path';
 import { useConfigSchema } from '../config/useConfigSchema';
+import { useResolvedConfig } from '../config/useResolvedConfig';
 import type { Instrument } from '../instrument/types';
 import type { JobHandle } from '../job/types';
 import { useLabContext } from '../lab/LabContext';
@@ -110,6 +112,13 @@ export function TrialChrome({
   const view2d = as2DView(record.view);
 
   const configSchema = useConfigSchema(instrument);
+  // What the instrument is looking at right now. The panel reads `record.config`
+  // — the pinned values — but anything instrument-facing gets the resolved one.
+  const { config: resolvedConfig, auto } = useResolvedConfig(
+    configSchema,
+    record.config,
+    record.auto,
+  );
 
   const title = record.title ?? instrument.title ?? instrument.name;
   const collapsedSections = record.collapsedSections ?? NO_SECTIONS;
@@ -136,6 +145,7 @@ export function TrialChrome({
       configSchema,
       configFields: instrument.config ? [] : (instrument.configSchema?.() ?? []),
       config: record.config,
+      auto,
       setConfig: (path, value) => {
         const prevConfig = record.config as Record<string, unknown>;
         if (
@@ -149,8 +159,9 @@ export function TrialChrome({
         }
         updateTrialConfig(trialId, path, value);
         if (instrument.onConfigChange) {
-          const nextConfig = withValueAtPath(prevConfig, path, value);
-          const nextState = instrument.onConfigChange(nextConfig, prevConfig, record.state);
+          const next = applyConfigWrite(prevConfig, record.auto ?? [], path, value);
+          const nextConfig = resolveAutoConfig(configSchema, next.config, new Set(next.autoPaths));
+          const nextState = instrument.onConfigChange(nextConfig, resolvedConfig, record.state);
           updateTrialState(trialId, nextState as never);
         }
       },
@@ -184,6 +195,8 @@ export function TrialChrome({
     activeToolId,
     setActiveTool,
     configSchema,
+    resolvedConfig,
+    auto,
     undockedIds,
     undockPanelAction,
     dockPanelAction,
@@ -226,6 +239,7 @@ export function TrialChrome({
     <section
       className="lk-trial"
       data-trial-id={trialId}
+      data-focused={lab.trials.length > 1 && lab.focusedTrialId === trialId ? 'true' : undefined}
       aria-label={`Trial ${title}`}
       tabIndex={-1}
       onKeyDown={handleKeyDown}