@weasel-js/labkit 1.2.0 → 1.3.0-pre.0

package/src/instrument/defineInstrument.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, expectTypeOf, it } from 'vitest';
+import { f } from '../config/builder';
+import type { ConfigOf } from '../config/types';
 import { defineInstrument } from './defineInstrument';
 import type { Instrument } from './types';
 
 describe('defineInstrument', () => {
-  it('returns the same object reference passed in', () => {
+  it('returns a legacy spec by reference', () => {
     const spec: Instrument<{ n: number }, { x: number }> = {
       name: 'Test',
       defaultConfig: () => ({ x: 1 }),
@@ -24,4 +26,39 @@ describe('defineInstrument', () => {
     expectTypeOf(inst.defaultConfig()).toEqualTypeOf<{ flag: boolean }>();
     expectTypeOf(inst.initialState({ flag: true })).toEqualTypeOf<{ count: number }>();
   });
+
+  it('synthesizes defaultConfig from a builder schema', () => {
+    const inst = defineInstrument({
+      name: 'Schema',
+      config: f.schema({ showGrid: f.boolean(true), cellSize: f.number(20) }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    expect(inst.defaultConfig()).toEqual({ showGrid: true, cellSize: 20 });
+  });
+
+  it('infers TC from the schema', () => {
+    const config = f.schema({ showGrid: f.boolean(true), mode: f.enum('fast', ['fast', 'slow']) });
+    const inst = defineInstrument<{ n: number }, ConfigOf<typeof config>>({
+      name: 'Schema',
+      config,
+      initialState: () => ({ n: 0 }),
+      render: () => null,
+    });
+    expectTypeOf(inst.defaultConfig()).toEqualTypeOf<{
+      showGrid: boolean;
+      mode: 'fast' | 'slow';
+    }>();
+  });
+
+  it('leaves an explicit defaultConfig alone even alongside a schema', () => {
+    const inst = defineInstrument({
+      name: 'Both',
+      config: f.schema({ a: f.number(1) }),
+      defaultConfig: () => ({ a: 99 }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    expect(inst.defaultConfig()).toEqual({ a: 99 });
+  });
 });

package/src/instrument/defineInstrument.ts

@@ -1,7 +1,34 @@
+import type { ConfigSchema } from '../config/types';
 import type { Instrument } from './types';
 
-/** Identity at runtime; exists so an instrument's state and config types are
- *  inferred from the spec rather than having to be written out. */
-export function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC> {
-  return spec;
+/** An instrument as it is written: either the legacy `defaultConfig` (plus an
+ *  optional `configSchema`), or a `config` schema that supplies both. */
+export type InstrumentSpec<TS, TC, TItem = unknown> =
+  | Instrument<TS, TC, TItem>
+  | (Omit<Instrument<TS, TC, TItem>, 'defaultConfig'> & { config: ConfigSchema<TC> });
+
+/**
+ * Normalizes an instrument spec, and infers its state and config types from
+ * the literal rather than making them be written out.
+ *
+ * A spec declaring `config` gets its `defaultConfig` synthesized from the
+ * schema, so nothing downstream branches on which way the config was
+ * declared. A spec written the legacy way is returned unchanged, by
+ * reference.
+ *
+ * Resolving the schema into controls does not happen here: rules are
+ * lab-scoped and this runs at module load. `useConfigSchema` does that.
+ *
+ * TypeScript infers all three type arguments or none, so a call that names
+ * `TS` and `TC` leaves `TItem` at `unknown` and a job's `onItem` needs a cast.
+ * Name the item type too, or pass no type arguments at all.
+ */
+export function defineInstrument<TS, TC, TItem = unknown>(
+  spec: InstrumentSpec<TS, TC, TItem>,
+): Instrument<TS, TC, TItem> {
+  if (spec.config && !('defaultConfig' in spec && spec.defaultConfig)) {
+    const schema = spec.config;
+    return { ...spec, defaultConfig: () => schema.defaults() } as Instrument<TS, TC, TItem>;
+  }
+  return spec as Instrument<TS, TC, TItem>;
 }

package/src/instrument/index.ts

@@ -1,3 +1,4 @@
+export type { ToolCapability, TrialTool } from '../tools/types';
 export { defineInstrument } from './defineInstrument';
 export type {
   CanvasCapability,

package/src/instrument/types.ts

@@ -1,6 +1,9 @@
 import type { ReactNode } from 'react';
+import type { TrialContribution } from '../chrome/types';
+import type { ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
+import type { ToolCapability } from '../tools/types';
 
 /** What an instrument's `render` is handed: its state and config, the setters
  *  for both, the trial it is mounted in, and a way to emit named events. */
@@ -19,6 +22,9 @@ export interface RenderContext<TS = unknown, TC = unknown> {
      *  a view that is not the 2D one. */
     zoom: number;
     setZoom: (z: number) => void;
+    /** Resolved active tool: this trial's slot, or the lab's. Null when neither
+     *  holds one. */
+    activeToolId: string | null;
   };
   emit: (event: string) => void;
   /** Present only when the instrument declares a `job`. */
@@ -40,12 +46,18 @@ export interface CanvasLayer<TS = unknown, TC = unknown> {
 export interface CanvasCapability<TS = unknown, TC = unknown> {
   layers: CanvasLayer<TS, TC>[];
   initialView?: { zoom: number; pan: { x: number; y: number } };
+  /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
+   *  regardless of these. */
+  minZoom?: number;
+  maxZoom?: number;
 }
 
 /** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
 export interface LayerCapability {
-  ids: string[];
+  /** In list order. A bare string is a layer id that doubles as its own label;
+   *  give a descriptor instead to label a layer or mark it `alwaysOn`. */
+  ids: readonly (string | LayerDescriptor)[];
 }
 
 /** Declares that an instrument accepts items dragged from a palette: what the
@@ -91,10 +103,16 @@ export type DragFeedback = { ok: boolean; reason?: string };
  * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
  * is what makes the trial provide the corresponding chrome.
  */
-export interface Instrument<TS = unknown, TC = unknown> {
+export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
   name: string;
   defaultConfig: () => TC;
   initialState: (config: TC) => TS;
+  /** The instrument's config, declared once: values, types and controls.
+   *  Supplying this makes `defaultConfig` optional — `defineInstrument`
+   *  synthesizes it. Prefer it over `defaultConfig` + `configSchema`. */
+  config?: ConfigSchema<TC>;
+  /** @deprecated Declare `config` instead; this repeats what `TC` already
+   *  says and nothing holds the two to one answer. */
   configSchema?: () => ConfigField[];
   /** The instrument's DOM. With `canvas`, this renders as an overlay above the
    *  layers rather than instead of them; return `null` for canvas only. */
@@ -106,13 +124,18 @@ export interface Instrument<TS = unknown, TC = unknown> {
   layers?: LayerCapability;
   dragDrop?: DragDropCapability<TS, TC>;
   undo?: UndoCapability;
+  /** Tools this instrument offers. Declaring them gives the trial a palette
+   *  region and its own tool slot. */
+  tools?: ToolCapability;
+  /** Chrome this instrument contributes beyond what its capabilities imply. */
+  chrome?: TrialContribution[];
   /** Work too slow to do during a render. The runtime starts it, aborts it on
    *  unmount and on a `key` change, and renders progress into the trial. */
-  job?: JobCapability<TS, TC, never>;
+  job?: JobCapability<TS, TC, TItem>;
 }
 
 /** Instruments as a lab receives them. `any` rather than `unknown` because
  *  parameter contravariance keeps a `defineInstrument<TS, TC>` result out of
  *  an `Instrument<unknown, unknown>[]`; it is contained to this alias. */
 // biome-ignore lint/suspicious/noExplicitAny: see above
-export type InstrumentList = readonly Instrument<any, any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any -- contravariant TC; see above
+export type InstrumentList = readonly Instrument<any, any, any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any -- contravariant TC; see above

package/src/instrument/validateConfigSchema.test.ts

@@ -21,12 +21,22 @@ describe('validateConfigSchema', () => {
     expect(r.errors).toContain('Duplicate config key: "a"');
   });
 
-  it('flags unknown field type', () => {
+  it('accepts an unknown field type — a lab may supply its renderer', () => {
     const fields = [
-      { key: 'x', label: 'X', type: 'mystery', default: 1 },
+      { key: 'x', label: 'X', type: 'vector2', default: 1 },
     ] as unknown as ConfigField[];
     const r = validateConfigSchema(fields);
-    expect(r.errors).toContain('Unknown field type: "mystery" on key "x"');
+    expect(r.valid).toBe(true);
+    expect(r.errors).toEqual([]);
+  });
+
+  it('still checks keys and labels on an unknown field type', () => {
+    const fields = [
+      { key: '', label: '', type: 'vector2', default: 1 },
+    ] as unknown as ConfigField[];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field has empty key');
+    expect(r.errors).toContain('Field "" has empty label');
   });
 
   it('flags slider min >= max', () => {

package/src/instrument/validateConfigSchema.ts

@@ -1,4 +1,4 @@
-import type { ConfigField, ConfigFieldType } from '../controls/types';
+import type { ConfigField } from '../controls/types';
 
 /** Whether a config schema is usable, and every problem found rather than
  *  just the first. */
@@ -7,11 +7,13 @@ export interface ValidationResult {
   errors: string[];
 }
 
-const KNOWN_TYPES: ConfigFieldType[] = ['slider', 'checkbox', 'select', 'number', 'text', 'color'];
-
 /** Check a config schema for the mistakes that would otherwise surface as a
- *  silently broken control: empty or duplicate keys, unknown field types, and
- *  fields whose own constraints do not hold. */
+ *  silently broken control: empty or duplicate keys, and fields whose own
+ *  constraints do not hold.
+ *
+ *  An unrecognized type is not an error — a lab supplies controls for its own
+ *  kinds through `ControlPanel`'s `renderers`, and this cannot see them. Such
+ *  a field simply has no constraints to check here. */
 export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
   const errors: string[] = [];
   const seenKeys = new Set<string>();
@@ -29,11 +31,6 @@ export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
       errors.push(`Field "${field.key}" has empty label`);
     }
 
-    if (!KNOWN_TYPES.includes(field.type)) {
-      errors.push(`Unknown field type: "${field.type}" on key "${field.key}"`);
-      continue;
-    }
-
     if (field.type === 'slider') {
       if (!Number.isFinite(field.default)) {
         errors.push(`Field "${field.key}": default must be a finite number`);

package/src/lab/Lab.chrome.test.tsx

@@ -0,0 +1,65 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { TrialContribution } from '../chrome/types';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+
+const Glyph = () => <svg />;
+const bare: Instrument = {
+  name: 'Bare',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+/** React logs the error it re-throws from a failed render; the assertions are
+ *  on the throw itself, so the console noise is not informative. */
+function silenceRenderError(): void {
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+}
+
+describe('<Lab> chrome', () => {
+  it('renders a consumer contribution', () => {
+    const extra: TrialContribution = {
+      id: 'export',
+      region: 'toolbar',
+      item: { icon: Glyph, label: 'Export', onActivate: () => {} },
+    };
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[extra]} />);
+    expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument();
+  });
+
+  it('suppresses a built-in by id', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['snapshot']} />);
+    expect(screen.queryByRole('button', { name: 'Save snapshot' })).toBeNull();
+    expect(screen.getByRole('button', { name: 'Clone trial' })).toBeInTheDocument();
+  });
+
+  it('throws when a consumer id collides with a built-in', () => {
+    silenceRenderError();
+    const clash: TrialContribution = {
+      id: 'clone',
+      region: 'toolbar',
+      item: { icon: Glyph, label: 'Mine', onActivate: () => {} },
+    };
+    expect(() =>
+      render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[clash]} />),
+    ).toThrow(/duplicate contribution id "clone"/);
+  });
+
+  it('throws when suppressing an id that is not there', () => {
+    silenceRenderError();
+    expect(() =>
+      render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['nope']} />),
+    ).toThrow(/cannot suppress "nope"/);
+  });
+
+  it('renders an instrument-declared contribution', () => {
+    const withChrome: Instrument = {
+      ...bare,
+      chrome: [{ id: 'mine', region: 'status', item: { text: 'ready' } }],
+    };
+    render(<Lab title="T" instruments={[withChrome]} defaultInstrument="Bare" />);
+    expect(screen.getByText('ready')).toBeInTheDocument();
+  });
+});

package/src/lab/Lab.tsx

@@ -1,12 +1,15 @@
 import { ThemeProvider } from '@weasel-js/theme/react';
 import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
 import { useStore } from 'zustand/react';
+import type { TrialContribution } from '../chrome/types';
+import type { ConfigRule, ControlRenderer } from '../config/types';
 import type { InstrumentList } from '../instrument/types';
 import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore, type LabStore } from '../state/store';
 import type { LabMode, StorageAdapter, TrialRecord } from '../state/types';
 import { interstellarTheme } from '../theme/interstellar';
+import type { TrialTool } from '../tools/types';
 import { Trial } from '../trial/Trial';
 import {
   addTrial as addTrialOp,
@@ -16,6 +19,8 @@ import {
   resetTrial as resetTrialOp,
 } from '../trial/trialOps';
 import { LabContext, type LabContextValue } from './LabContext';
+import { LabHeader } from './LabHeader';
+import { LabPalette } from './LabPalette';
 import { LabShell } from './LabShell';
 import { useResolvedMode } from './useSystemMode';
 import { type TrialLayout, Workspace } from './Workspace';
@@ -35,6 +40,22 @@ export interface LabProps {
    */
   nebula?: readonly string[];
   title?: string;
+  /** Rendered in the shell's footer, below the workspace. */
+  footer?: ReactNode;
+  /** Contributions added to every trial's chrome, after the instrument's own. */
+  chrome?: readonly TrialContribution[];
+  /** Built-in contribution ids to drop. Throws on an id that is not there. */
+  suppress?: readonly string[];
+  /** Tools offered lab-wide. A trial whose instrument declares none of its own
+   *  reflects and writes this slot. */
+  tools?: readonly TrialTool[];
+  /** Rules run over every instrument's config leaves, before labkit's own
+   *  inference — where a lab states a convention once instead of annotating
+   *  each field. Memoize or hoist. */
+  configRules?: readonly ConfigRule[];
+  /** Control overrides and app-defined kinds for every trial's settings panel.
+   *  Keys are config paths (checked first) or leaf kinds. Memoize or hoist. */
+  controls?: Record<string, ControlRenderer>;
   children?: ReactNode;
 }
 
@@ -88,6 +109,12 @@ export function Lab({
   mode,
   nebula,
   title,
+  footer,
+  chrome,
+  suppress,
+  tools,
+  configRules,
+  controls,
   children,
 }: LabProps) {
   if (process.env.NODE_ENV !== 'production' && instruments.length === 0) {
@@ -160,7 +187,8 @@ export function Lab({
       },
       savedSnapshots,
       saveSnapshot: (trialId, name) => {
-        store.getState().saveSnapshot(trialId, name ?? `Save ${new Date().toLocaleString()}`);
+        const taken = store.getState().savedSnapshots.filter((s) => s.trialId === trialId).length;
+        store.getState().saveSnapshot(trialId, name ?? `Snapshot ${taken + 1}`);
       },
       loadSnapshot: (trialId, snapshotId) => {
         store.getState().loadSnapshot(snapshotId, trialId);
@@ -172,8 +200,10 @@ export function Lab({
       setMode: (m) => {
         store.getState().setMode(m);
       },
+      configRules,
+      controls,
     };
-  }, [instruments, trials, savedSnapshots, modeValue, store]);
+  }, [instruments, trials, savedSnapshots, modeValue, store, configRules, controls]);
 
   // Only override the backdrop in dark, where there is one to override.
   // Setting a CSS custom property is the sanctioned use of inline style.
@@ -191,19 +221,32 @@ export function Lab({
           className="lk-lab"
           style={backdropStyle}
         >
-          <LabShell title={title ?? 'Labkit'} mode={modeValue} header={children}>
-            <Workspace
-              ids={trials.map((w) => w.id)}
-              resizable
-              reorderable
-              onReorder={(ids) => contextValue.reorderTrials(ids)}
-              layout={layout as TrialLayout}
-              onLayoutChange={(next) => store.getState().setLayout(next)}
-            >
-              {trials.map((w) => (
-                <Trial key={w.id} id={w.id} />
-              ))}
-            </Workspace>
+          <LabShell
+            title={title ?? 'Labkit'}
+            mode={modeValue}
+            footer={footer}
+            header={
+              <>
+                <LabHeader />
+                {children}
+              </>
+            }
+          >
+            <div className="lk-lab__body">
+              {tools ? <LabPalette tools={tools} /> : null}
+              <Workspace
+                ids={trials.map((w) => w.id)}
+                resizable
+                reorderable
+                onReorder={(ids) => contextValue.reorderTrials(ids)}
+                layout={layout as TrialLayout}
+                onLayoutChange={(next) => store.getState().setLayout(next)}
+              >
+                {trials.map((w) => (
+                  <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
+                ))}
+              </Workspace>
+            </div>
           </LabShell>
         </ThemeProvider>
       </LabContext.Provider>

package/src/lab/LabContext.ts

@@ -1,4 +1,5 @@
 import { createContext, useContext } from 'react';
+import type { ConfigRule, ControlRenderer } from '../config/types';
 import type { InstrumentList } from '../instrument/types';
 import type { LabMode, SavedSnapshot, TrialRecord } from '../state/types';
 
@@ -19,6 +20,11 @@ export interface LabContextValue {
   deleteSnapshot: (snapshotId: string) => void;
   mode: LabMode;
   setMode: (m: LabMode) => void;
+  /** Lab-wide rules run over every instrument's config leaves, before
+   *  labkit's own inference. */
+  configRules?: readonly ConfigRule[];
+  /** Lab-wide control overrides, keyed by config path or by leaf kind. */
+  controls?: Record<string, ControlRenderer>;
 }
 
 /** Context carrying the surrounding lab. Prefer `useLabContext`. */