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

package/src/tools/types.ts

@@ -0,0 +1,24 @@
+import type { IconComponent } from '../chrome/types';
+
+/**
+ * A tool a trial can be in. labkit's own — core's `ToolsApi` carries hotkey
+ * slots, ambient tools, eligibility tiers and canvas overlay layers, all bound
+ * to the gesture dispatcher, and a labkit instrument is an arbitrary canvas or
+ * DOM tree rather than a weasel scene.
+ */
+export interface TrialTool {
+  id: string;
+  label: string;
+  icon: IconComponent;
+  /** Shown in the tooltip. Not bound here — the instrument owns its keymap. */
+  shortcut?: string;
+  /** Presentation grouping in the palette. Ungrouped tools sort after grouped. */
+  group?: string;
+}
+
+/** What an instrument declares to get a palette region. */
+export interface ToolCapability {
+  tools: TrialTool[];
+  /** Which tool a fresh trial starts in. Defaults to the first. */
+  initial?: string;
+}

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

@@ -0,0 +1,113 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { f } from '../config/builder';
+import type { ConfigRule, ControlRenderer } from '../config/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+
+const schemaInstrument = defineInstrument({
+  name: 'Schema',
+  config: f.schema({
+    showGrid: f.boolean(true),
+    cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+  }),
+  initialState: () => ({}),
+  render: () => null,
+});
+
+const legacyInstrument = defineInstrument({
+  name: 'Legacy',
+  defaultConfig: () => ({ showGrid: true }),
+  configSchema: () => [
+    { type: 'checkbox' as const, key: 'showGrid', label: 'Show grid', default: true },
+  ],
+  initialState: () => ({}),
+  render: () => null,
+});
+
+describe('a trial renders its instrument config', () => {
+  it('renders a builder schema into the settings sidebar', () => {
+    render(<Lab instruments={[schemaInstrument]} defaultInstrument="Schema" />);
+    expect(screen.getByLabelText('Show grid')).toBeInTheDocument();
+    expect(screen.getByText('Grid spacing')).toBeInTheDocument();
+  });
+
+  it('renders a legacy ConfigField list through the same path', () => {
+    render(<Lab instruments={[legacyInstrument]} defaultInstrument="Legacy" />);
+    expect(screen.getByLabelText('Show grid')).toBeInTheDocument();
+  });
+
+  it('writes a config change back to the trial', () => {
+    render(<Lab instruments={[schemaInstrument]} defaultInstrument="Schema" />);
+    const checkbox = screen.getByLabelText('Show grid') as HTMLInputElement;
+    expect(checkbox.checked).toBe(true);
+    fireEvent.click(checkbox);
+    expect((screen.getByLabelText('Show grid') as HTMLInputElement).checked).toBe(false);
+  });
+});
+
+describe('lab-wide config seams', () => {
+  it('applies a lab-wide rule before labkit inference', () => {
+    const inst = defineInstrument({
+      name: 'Ruled',
+      config: f.schema({ tintColor: f.value('#ffffff') }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    const colorByName: ConfigRule = (ctx) =>
+      ctx.key.endsWith('Color') ? { kind: 'color' } : null;
+    render(
+      <Lab instruments={[inst]} defaultInstrument="Ruled" configRules={[colorByName]} />,
+    );
+    expect(screen.getByLabelText('Tint color')).toHaveAttribute('type', 'color');
+  });
+
+  it('without the rule the same leaf falls back to a text input', () => {
+    const inst = defineInstrument({
+      name: 'Unruled',
+      config: f.schema({ tintColor: f.value('#ffffff') }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    render(<Lab instruments={[inst]} defaultInstrument="Unruled" />);
+    expect(screen.getByLabelText('Tint color')).toHaveAttribute('type', 'text');
+  });
+
+  it('supplies a lab-wide control for a kind labkit does not ship', () => {
+    const inst = defineInstrument({
+      name: 'Custom',
+      config: f.schema({ offset: f.custom('vector2', { x: 3 }) }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    const vector2: ControlRenderer = (ctx) => (
+      <span>vec:{String((ctx.value as { x: number }).x)}</span>
+    );
+    render(
+      <Lab instruments={[inst]} defaultInstrument="Custom" controls={{ vector2 }} />,
+    );
+    expect(screen.getByText('vec:3')).toBeInTheDocument();
+  });
+
+  it('shows the placeholder when no control is supplied for that kind', () => {
+    const inst = defineInstrument({
+      name: 'Unwired',
+      config: f.schema({ offset: f.custom('vector2', { x: 3 }) }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    render(<Lab instruments={[inst]} defaultInstrument="Unwired" />);
+    expect(screen.getByText(/vector2/)).toBeInTheDocument();
+  });
+
+  it('omits the settings section for an instrument with no config', () => {
+    const inst = defineInstrument({
+      name: 'Bare',
+      defaultConfig: () => ({}),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    render(<Lab instruments={[inst]} defaultInstrument="Bare" />);
+    expect(screen.queryByText('Settings')).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,73 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { JobEvent } from '../job/types';
+import { Lab } from '../lab/Lab';
+
+interface S {
+  items: number[];
+}
+interface C {
+  n: number;
+}
+
+function makeInstrument(name: string, n: number, delay: number) {
+  return defineInstrument<S, C, number>({
+    name,
+    defaultConfig: () => ({ n }),
+    initialState: () => ({ items: [] }),
+    render: () => null,
+    job: {
+      auto: true,
+      run: async function* ({ config, signal }): AsyncGenerator<JobEvent<number>> {
+        yield { kind: 'total', total: config.n };
+        for (let i = 0; i < config.n; i++) {
+          await new Promise((r) => setTimeout(r, delay));
+          if (signal.aborted) return;
+          yield { kind: 'item', item: i };
+        }
+      },
+      onItem: (item, state) => ({ items: [...state.items, item] }),
+    },
+  });
+}
+
+describe('a trial whose instrument declares a job', () => {
+  it('shows progress in the trial chrome', async () => {
+    const fast = makeInstrument('fast', 3, 1);
+    render(<Lab instruments={[fast]} defaultInstrument="fast" storage={null} />);
+    const bar = await waitFor(() => screen.getByRole('progressbar', { name: /job progress/i }));
+    await waitFor(() => {
+      // A job that reported a total drives a determinate bar, so the count and
+      // the accessible value have to agree.
+      expect(bar).toHaveAttribute('aria-valuemax', '3');
+      expect(bar).toHaveAttribute('aria-valuenow', '3');
+    });
+    expect(document.querySelector('.lk-job__count')?.textContent).toMatch(/3\s*\/\s*3/);
+  });
+
+  it('offers a cancel control while running, and drops it once cancelled', async () => {
+    const slow = makeInstrument('slow', 40, 20);
+    render(<Lab instruments={[slow]} defaultInstrument="slow" storage={null} />);
+    const cancel = await waitFor(() => screen.getByRole('button', { name: /cancel/i }));
+    await userEvent.click(cancel);
+    await waitFor(() => {
+      expect(screen.queryByRole('button', { name: /cancel/i })).not.toBeInTheDocument();
+    });
+  });
+
+  it('renders no job chrome for an instrument that declares none', async () => {
+    const plain = defineInstrument<S, C>({
+      name: 'plain',
+      defaultConfig: () => ({ n: 0 }),
+      initialState: () => ({ items: [] }),
+      render: () => null,
+    });
+    render(<Lab instruments={[plain]} defaultInstrument="plain" storage={null} />);
+    await waitFor(() => {
+      expect(document.querySelector('.lk-trial')).toBeInTheDocument();
+    });
+    expect(document.querySelector('.lk-trial__job')).not.toBeInTheDocument();
+  });
+});

package/src/trial/Trial.less

@@ -1,10 +1,17 @@
 .lk-trial {
   display: flex;
+  // Click-focusable so the trial's own shortcuts reach it; the trial is not a
+  // control, so it draws no focus ring of its own.
+  outline: none;
   flex-direction: column;
   height: 100%;
-  background: var(--wzl-surface);
-  border: 1px solid var(--wzl-border);
+  // The lab paints --wzl-surface, so a trial on the same token was separated
+  // from its own workspace by nothing but a hairline. Raised reads as a panel,
+  // and in dark it is translucent, so the backdrop still shows through.
+  background: var(--wzl-surface-raised);
+  border: var(--wzl-border-w) solid var(--wzl-border-raised);
   border-radius: var(--wzl-radius-md);
+  box-shadow: 0 1px 3px var(--wzl-shadow);
   overflow: hidden;
 
   &__body {
@@ -15,21 +22,52 @@
 
   &__sidebar {
     flex-shrink: 0;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    // Sections floor at their content height, so without this the last ones
+    // are cut rather than reachable.
+    overflow-y: auto;
   }
 
+  // An instrument's rendered output is dropped in here directly, so the
+  // content well is what makes `height: 100%` mean anything to it. Without
+  // the column context and the stretched child, anything a lab returns
+  // collapses to its intrinsic height and the trial looks empty below it.
   &__content {
+    // The viewport region anchors against this well.
+    position: relative;
     flex: 1;
+    min-width: 0;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
     overflow: auto;
+
+    > * {
+      flex: 1 1 auto;
+      min-height: 0;
+    }
+
+    // An instrument owns its own interior; the frame contributes chrome, not
+    // inset. `--flush` is now only about scrolling.
+    &--flush {
+      overflow: hidden;
+    }
+  }
+
+  &__canvas-host {
+    position: relative;
+    width: 100%;
+    height: 100%;
   }
 
   &__toolbar {
     flex-shrink: 0;
-    border-bottom: 1px solid var(--wzl-line-subtle);
   }
 
   &__status {
     flex-shrink: 0;
-    border-top: 1px solid var(--wzl-line-subtle);
   }
 
   &--unknown {
@@ -51,8 +89,87 @@
   font-size: var(--wzl-font-size-sm);
 }
 
+// Same `width: 100%` default as the header's Select — pinned so it cannot
+// absorb the toolbar's slack. Placeholder-only, so it need only fit "Load…".
+.lk-root .lk-toolbar__load-select {
+  width: 88px;
+}
+
 .lk-sidebar__placeholder {
   padding: var(--wzl-space-sm);
   color: var(--wzl-fg-muted);
   font-size: var(--wzl-font-size-sm);
 }
+
+
+.lk-trial__titlebar {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+  flex-shrink: 0;
+  padding: 0 var(--wzl-space-sm);
+  min-height: calc(var(--wzl-font-size-sm) * var(--wzl-leading) + var(--wzl-space-xs));
+  background: var(--wzl-surface-sunken);
+  border-bottom: var(--wzl-border-w) solid var(--wzl-border);
+  border-radius: var(--wzl-radius-md) var(--wzl-radius-md) 0 0;
+
+  // The bar is the drag surface, so it carries the cursor rather than an
+  // affordance of its own.
+  &--draggable {
+    cursor: grab;
+    touch-action: none;
+
+    &:active { cursor: grabbing; }
+  }
+}
+
+.lk-trial__titlebar-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  margin-left: auto;
+}
+
+// Prefixed with `.lk-root` to outrank base.less's `:where(button)` default,
+// which would give a 12px glyph a 24px chrome box on the title bar.
+.lk-root .lk-titlebar-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--wzl-radius-sm);
+  background: transparent;
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  // Matches .lk-trial__title — the X reads as part of the bar's own type,
+  // not as chrome sitting on top of it.
+  color: var(--wzl-fg-muted);
+  cursor: pointer;
+
+  &:hover {
+    background: var(--wzl-surface-hover);
+    color: var(--wzl-fg);
+  }
+
+  &:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+
+  &--danger:hover:not(:disabled) {
+    background: color-mix(in srgb, var(--wzl-danger) 15%, transparent);
+    color: var(--wzl-danger);
+  }
+}
+
+.lk-trial__title {
+  font-size: var(--wzl-font-size-sm);
+  font-weight: var(--wzl-font-weight-bold);
+  color: var(--wzl-fg-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/src/trial/Trial.stories.tsx

@@ -5,6 +5,7 @@ import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore } from '../state/store';
 import type { TrialRecord } from '../state/types';
+import { DEFAULT_VIEW } from '../state/view';
 import { TrialChrome } from './TrialChrome';
 
 const noop = () => {};
@@ -52,7 +53,14 @@ function Harness() {
               config: {},
               setState: () => {},
               setConfig: () => {},
-              trial: { id: 'ws-demo', zoom: 1, setZoom: () => {} },
+              trial: {
+                id: 'ws-demo',
+                view: DEFAULT_VIEW,
+                setView: () => {},
+                zoom: 1,
+                setZoom: () => {},
+                activeToolId: null,
+              },
               emit: () => {},
             })}
           </TrialChrome>

package/src/trial/Trial.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, within } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
@@ -6,92 +6,9 @@ import { Lab } from '../lab/Lab';
 import { LabContext, type LabContextValue } from '../lab/LabContext';
 import { LabStoreContext } from '../state/context';
 import { createLabStore } from '../state/store';
-import type { TrialRecord } from '../state/types';
-import { DefaultToolbar } from './DefaultToolbar';
-import type { TrialToolbarContext } from './slotTypes';
+import type { SavedSnapshot, TrialRecord } from '../state/types';
 import { TrialChrome } from './TrialChrome';
 
-function makeCtx(overrides: Partial<TrialToolbarContext> = {}): TrialToolbarContext {
-  return {
-    trialId: 'ws-1',
-    instrumentName: 'Stub',
-    hasUndo: false,
-    canUndo: false,
-    canRedo: false,
-    undo: vi.fn(),
-    redo: vi.fn(),
-    zoom: 1,
-    setZoom: vi.fn(),
-    zoomIn: vi.fn(),
-    zoomOut: vi.fn(),
-    resetZoom: vi.fn(),
-    hasCanvas: false,
-    savedSnapshots: [],
-    saveSnapshot: vi.fn(),
-    loadSnapshot: vi.fn(),
-    clone: vi.fn(),
-    reset: vi.fn(),
-    close: vi.fn(),
-    isLastTrial: false,
-    ...overrides,
-  };
-}
-
-describe('<DefaultToolbar>', () => {
-  it('renders close button', () => {
-    render(<DefaultToolbar ctx={makeCtx()} />);
-    expect(screen.getByRole('button', { name: /close/i })).toBeInTheDocument();
-  });
-
-  it('disables close when isLastTrial is true', () => {
-    render(<DefaultToolbar ctx={makeCtx({ isLastTrial: true })} />);
-    expect(screen.getByRole('button', { name: /close/i })).toBeDisabled();
-  });
-
-  it('omits undo/redo buttons when hasUndo is false', () => {
-    render(<DefaultToolbar ctx={makeCtx({ hasUndo: false })} />);
-    expect(screen.queryByRole('button', { name: /undo/i })).toBeNull();
-    expect(screen.queryByRole('button', { name: /redo/i })).toBeNull();
-  });
-
-  it('shows undo/redo buttons when hasUndo is true', () => {
-    render(<DefaultToolbar ctx={makeCtx({ hasUndo: true, canUndo: true, canRedo: false })} />);
-    expect(screen.getByRole('button', { name: /undo/i })).not.toBeDisabled();
-    expect(screen.getByRole('button', { name: /redo/i })).toBeDisabled();
-  });
-
-  it('omits zoom buttons when hasCanvas is false', () => {
-    render(<DefaultToolbar ctx={makeCtx({ hasCanvas: false })} />);
-    expect(screen.queryByTitle('Zoom in')).toBeNull();
-    expect(screen.queryByTitle('Zoom out')).toBeNull();
-  });
-
-  it('shows zoom controls when hasCanvas is true', () => {
-    render(<DefaultToolbar ctx={makeCtx({ hasCanvas: true, zoom: 1.5 })} />);
-    expect(screen.getByTitle('Zoom in')).toBeInTheDocument();
-    expect(screen.getByTitle('Zoom out')).toBeInTheDocument();
-    expect(screen.getByText('150%')).toBeInTheDocument();
-  });
-
-  it('shows load select when snapshots exist', () => {
-    const ctx = makeCtx({
-      savedSnapshots: [
-        {
-          id: 's1',
-          name: 'First',
-          trialId: 'ws-1',
-          instrumentName: 'Stub',
-          config: {},
-          state: {},
-          savedAt: 1,
-        },
-      ],
-    });
-    render(<DefaultToolbar ctx={ctx} />);
-    expect(screen.getByRole('combobox', { name: /load snapshot/i })).toBeInTheDocument();
-  });
-});
-
 const stubInstrument: Instrument = {
   name: 'Stub',
   defaultConfig: () => ({}),
@@ -113,6 +30,7 @@ type ChromeProps = Parameters<typeof TrialChrome>[0];
 function ChromeHarness({
   children,
   labOverrides,
+  instrument = stubInstrument,
   ...props
 }: { children?: ReactNode; labOverrides?: Partial<LabContextValue> } & Partial<ChromeProps>) {
   const store = createLabStore({
@@ -120,7 +38,7 @@ function ChromeHarness({
     storage: { read: () => null, write: () => {} },
   });
   const labCtx: LabContextValue = {
-    instruments: [stubInstrument],
+    instruments: [instrument],
     trials: [stubRecord],
     addTrial: vi.fn(),
     cloneTrial: vi.fn(),
@@ -141,7 +59,7 @@ function ChromeHarness({
         <TrialChrome
           trialId="ws-1"
           record={stubRecord}
-          instrument={stubInstrument}
+          instrument={instrument}
           isLastTrial={false}
           {...props}
         >
@@ -158,15 +76,47 @@ describe('<TrialChrome>', () => {
     expect(screen.getByTestId('content')).toBeInTheDocument();
   });
 
-  it('renders default toolbar when no toolbar prop is given', () => {
+  it('renders the built-in trial actions', () => {
+    render(<ChromeHarness />);
+    expect(screen.getByRole('button', { name: 'Close trial' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Clone trial' })).toBeInTheDocument();
+  });
+
+  it('disables close on the last trial', () => {
+    render(<ChromeHarness isLastTrial />);
+    expect(screen.getByRole('button', { name: /close/i })).toBeDisabled();
+  });
+
+  it('omits undo and redo unless the instrument declares undo', () => {
     render(<ChromeHarness />);
-    expect(screen.getByRole('button', { name: /close/i })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Undo' })).toBeNull();
+    render(
+      <ChromeHarness
+        instrument={{ ...stubInstrument, undo: {} }}
+        undoBindings={{ canUndo: true, canRedo: false, undo: vi.fn(), redo: vi.fn() }}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Undo' })).not.toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Redo' })).toBeDisabled();
+  });
+
+  it('offers the snapshot loader once a snapshot exists', () => {
+    const snapshot: SavedSnapshot = {
+      id: 's1',
+      name: 'First',
+      trialId: 'ws-1',
+      instrumentName: 'Stub',
+      config: {},
+      state: {},
+      savedAt: 1,
+    };
+    render(<ChromeHarness labOverrides={{ savedSnapshots: [snapshot] }} />);
+    expect(screen.getByRole('button', { name: /load snapshot/i })).toBeInTheDocument();
   });
 
-  it('renders custom toolbar when toolbar prop is provided', () => {
-    render(<ChromeHarness toolbar={() => <div data-testid="custom-toolbar">custom</div>} />);
-    expect(screen.getByTestId('custom-toolbar')).toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: /close/i })).toBeNull();
+  it('renders a consumer contribution alongside the built-ins', () => {
+    render(<ChromeHarness chrome={[{ id: 'mine', region: 'status', item: { text: 'ready' } }]} />);
+    expect(screen.getByText('ready')).toBeInTheDocument();
   });
 
   it('Cmd+S triggers saveSnapshot', () => {
@@ -178,10 +128,31 @@ describe('<TrialChrome>', () => {
   });
 });
 
-describe('<Lab> + TrialChrome integration', () => {
+describe('chrome regions in a mounted lab', () => {
+  function renderLabWith(instrument: Instrument) {
+    return render(<Lab title="T" instruments={[instrument]} defaultInstrument={instrument.name} />);
+  }
+
+  it('puts zoom in the viewport region and not in the toolbar', () => {
+    renderLabWith({ ...stubInstrument, canvas: { layers: [] }, undo: {} });
+    const toolbar = document.querySelector('.lk-trial__toolbar') as HTMLElement;
+    const viewport = document.querySelector('.lk-viewport-controls') as HTMLElement;
+    expect(within(viewport).getByRole('button', { name: 'Zoom in' })).toBeInTheDocument();
+    expect(within(toolbar).queryByRole('button', { name: 'Zoom in' })).toBeNull();
+  });
+
+  it('renders no undo group for an instrument that does not declare undo', () => {
+    renderLabWith({ ...stubInstrument, canvas: { layers: [] } });
+    expect(screen.queryByRole('button', { name: 'Undo' })).toBeNull();
+  });
+
+  it('renders no viewport region for an instrument with no canvas', () => {
+    renderLabWith(stubInstrument);
+    expect(document.querySelector('.lk-viewport-controls')).toBeNull();
+  });
+
   it('Lab provides context for nested TrialChrome', () => {
-    render(<Lab instruments={[stubInstrument]} defaultInstrument="Stub" />);
-    // Lab seeds a trial; no chrome rendered without children — sanity check Lab mounts.
+    renderLabWith(stubInstrument);
     expect(document.querySelector('.lk-lab')).toBeTruthy();
   });
 });