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

package/src/state/toolSlot.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { createLabStore } from './store';
+
+function store() {
+  return createLabStore({ storageKey: 'test', storage: { read: () => null, write: () => {} } });
+}
+
+const record = { id: 't1', instrumentName: 'X', config: {}, state: {}, view: {} };
+
+describe('the tool slot', () => {
+  it('starts empty at both levels', () => {
+    const s = store();
+    expect(s.getState().activeToolId).toBeNull();
+  });
+
+  it('sets the lab slot', () => {
+    const s = store();
+    s.getState().setLabTool('brush');
+    expect(s.getState().activeToolId).toBe('brush');
+  });
+
+  it('sets a trial slot without touching the lab one', () => {
+    const s = store();
+    s.getState().addTrial(record);
+    s.getState().setLabTool('brush');
+    s.getState().setTrialTool('t1', 'eraser');
+    expect(s.getState().activeToolId).toBe('brush');
+    expect(s.getState().trials[0].activeToolId).toBe('eraser');
+  });
+
+  it('leaves a trial slot undefined until it is set', () => {
+    const s = store();
+    s.getState().addTrial(record);
+    expect(s.getState().trials[0].activeToolId).toBeUndefined();
+  });
+});

package/src/state/types.ts

@@ -15,6 +15,8 @@ export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
   /** Opaque to labkit: persisted, restored on Reset and handed to the instrument,
    *  but never read into. A 3D lab puts an orbit here and keeps all three. */
   view: TV;
+  /** This trial's own tool slot. Undefined means it reads the lab's. */
+  activeToolId?: string | null;
   undoStack: UndoStack;
 }
 
@@ -39,6 +41,8 @@ export interface LabStoreState {
   trials: TrialRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
+  /** The lab's tool slot — what a trial with no slot of its own resolves to. */
+  activeToolId: string | null;
   /** Per-trial tile extents, keyed by trial id. Opaque here — the
    *  shape belongs to whatever lays the trials out. */
   layout: Record<string, unknown>;

package/src/styles.less

@@ -4,11 +4,17 @@
 @import './lab/LabShell.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Sidebar.less';
+@import './primitives/ZoomControl.less';
 @import './primitives/StatusBar.less';
+@import './primitives/JobProgress.less';
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
+@import './primitives/Legend.less';
+@import './primitives/FloatingPanel.less';
 @import './lab/Lab.less';
 @import './trial/Trial.less';
+@import './chrome/regions/ViewportRegion.less';
+@import './chrome/regions/PaletteRegion.less';
 @import './controls/ControlPanel.less';
 @import './canvas/CanvasStack.less';
 @import './layers/LayerList.less';

package/src/surface/useTiledSurface.ts

@@ -1,3 +1,4 @@
+import { useVisibleRaf } from '@weasel-js/core';
 import { useCallback, useEffect, useRef } from 'react';
 import { composeRects, rectsEqual } from './composeRects';
 import type { Box, Rect } from './rect';
@@ -35,7 +36,6 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
   const rects = useRef(new Map<string, Rect>());
   const dirty = useRef(new Set<string>());
   const needsMeasure = useRef(true);
-  const raf = useRef(0);
   const observer = useRef<ResizeObserver | null>(null);
   const lastDpr = useRef(0);
 
@@ -58,10 +58,8 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     return changed;
   }, []);
 
-  const schedule = useCallback(() => {
-    if (raf.current) return;
-    raf.current = requestAnimationFrame(() => {
-      raf.current = 0;
+  const frameLoop = useVisibleRaf(
+    () => {
       const el = container.current;
       if (!el) {
         dirty.current.clear();
@@ -85,8 +83,15 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
         size: { width: box.width, height: box.height },
       });
       dirty.current.clear();
-    });
-  }, [measure]);
+    },
+    // The host attaches its container through `containerRef`, which may land
+    // well after this hook's first effect; the gate re-resolves it per request.
+    { target: () => container.current },
+  );
+
+  const schedule = useCallback(() => {
+    frameLoop.request();
+  }, [frameLoop]);
 
   const invalidate = useCallback(
     (id: string) => {
@@ -148,10 +153,9 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     return () => {
       ro.disconnect();
       observer.current = null;
-      if (raf.current) cancelAnimationFrame(raf.current);
-      raf.current = 0;
+      frameLoop.cancel();
     };
-  }, [schedule]);
+  }, [schedule, frameLoop]);
 
   return { invalidate, invalidateAll, invalidateRects, registerTile, containerRef };
 }

package/src/test-setup.ts

@@ -31,6 +31,32 @@ if (typeof globalThis.ResizeObserver === 'undefined') {
   } as unknown as typeof ResizeObserver;
 }
 
+// jsdom ships no PointerEvent, so `fireEvent.pointerDown` builds a bare Event
+// and drops clientX/clientY — a drag handler then reads `undefined` and computes
+// NaN deltas, which the DOM rejects as invalid CSS rather than reporting.
+// MouseEvent already carries the coordinate fields.
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly isPrimary: boolean;
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 1;
+      this.pointerType = init.pointerType ?? 'mouse';
+      this.isPrimary = init.isPrimary ?? true;
+    }
+  }
+  globalThis.PointerEvent = PointerEventPolyfill as unknown as typeof PointerEvent;
+}
+
+// jsdom implements neither side of pointer capture.
+if (typeof Element.prototype.setPointerCapture === 'undefined') {
+  Element.prototype.setPointerCapture = () => {};
+  Element.prototype.releasePointerCapture = () => {};
+  Element.prototype.hasPointerCapture = () => false;
+}
+
 afterEach(() => {
   cleanup();
 });

package/src/theme/base.less

@@ -16,6 +16,10 @@
 
 // Resets and global element defaults.
 .lk-root {
+  // labkit's own vocabulary over the theme's raw scale — named for the thing
+  // rather than the step, so "the workspace is too tight" has one place to go.
+  --lk-workspace-pad: var(--wzl-space-sm);
+
   font-family: var(--wzl-font-ui);
   font-size: var(--wzl-font-size);
   font-weight: var(--wzl-font-weight-light);
@@ -26,8 +30,15 @@
   *, *::before, *::after {
     box-sizing: border-box;
   }
+}
 
-  button {
+// Defaults for labkit's own bare markup. `.lk-root` is inside :where() too, so
+// the whole selector scores (0,0,0): a weasel-ui module class beats it on
+// specificity instead of on which stylesheet happened to be injected last.
+// Deliberate overrides of a weasel-ui component go the other way — see the
+// `.lk-root` prefix convention below.
+:where(.lk-root) {
+  :where(button) {
     font: inherit;
     color: inherit;
     background: var(--wzl-surface-raised);
@@ -55,11 +66,17 @@
     }
   }
 
-  input[type="range"] {
+  :where(input[type="range"]) {
     accent-color: var(--wzl-accent);
   }
 }
 
+// The `.lk-root` prefix convention: a labkit class handed to a weasel-ui
+// component through `className` lands beside that component's own CSS-module
+// class at equal specificity, so injection order — not intent — decides the
+// winner. Prefixing with `.lk-root` scores (0,2,0) and settles it. Use it only
+// where labkit means to override the component; plain `.lk-*` elsewhere.
+
 // Cosmic background applied to the Lab root. The starscape sits as a fixed
 // pseudo-element so panning the trial doesn't shift the field of stars.
 .lk-lab {

package/src/theme/interstellar.tokens.json

@@ -28,7 +28,9 @@
         "fg-subtle": { "$value": "#5a5a78" },
         "accent": { "$value": "#b08adb" },
         "accent-hover": { "$value": "#c6a3ee" },
-        "focus-ring": { "$value": "rgba(176, 138, 219, 0.45)" }
+        "focus-ring": { "$value": "rgba(176, 138, 219, 0.45)" },
+        "shadow": { "$value": "rgba(0, 0, 0, 0.7)" },
+        "border-raised": { "$value": "rgba(255, 255, 255, 0.36)" }
       },
       "gradient": {
         "$type": "gradient",
@@ -50,7 +52,9 @@
         "fg-subtle": { "$value": "#a89b85" },
         "accent": { "$value": "#a86f3c" },
         "accent-hover": { "$value": "#c2854f" },
-        "focus-ring": { "$value": "rgba(168, 111, 60, 0.35)" }
+        "focus-ring": { "$value": "rgba(168, 111, 60, 0.35)" },
+        "shadow": { "$value": "rgba(80, 60, 40, 0.18)" },
+        "border-raised": { "$value": "#9e8b71" }
       }
     }
   }

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

@@ -1,4 +1,4 @@
-import { render, waitFor } from '@testing-library/react';
+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';
@@ -13,22 +13,22 @@ interface C {
 }
 
 function makeInstrument(name: string, n: number, delay: number) {
-  return defineInstrument<S, C>({
+  return defineInstrument<S, C, number>({
     name,
     defaultConfig: () => ({ n }),
     initialState: () => ({ items: [] }),
     render: () => null,
     job: {
       auto: true,
-      run: async function* ({ config, signal }): AsyncGenerator<JobEvent<never>> {
+      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 as never };
+          yield { kind: 'item', item: i };
         }
       },
-      onItem: (item, state) => ({ items: [...state.items, item as number] }),
+      onItem: (item, state) => ({ items: [...state.items, item] }),
     },
   });
 }
@@ -37,25 +37,23 @@ 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(() => {
-      expect(document.querySelector('.lk-trial__job')).toBeInTheDocument();
-    });
-    await waitFor(() => {
-      expect(document.querySelector('.lk-trial__job-count')?.textContent).toMatch(/3\s*\/\s*3/);
+      // 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(() => {
-      const el = document.querySelector('.lk-trial__job-cancel');
-      expect(el).toBeInTheDocument();
-      return el as HTMLElement;
-    });
+    const cancel = await waitFor(() => screen.getByRole('button', { name: /cancel/i }));
     await userEvent.click(cancel);
     await waitFor(() => {
-      expect(document.querySelector('.lk-trial__job-cancel')).not.toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: /cancel/i })).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,20 +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__job {
+
+.lk-trial__titlebar {
   display: flex;
-  gap: 8px;
   align-items: center;
-  font-size: 0.75rem;
+  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__job-failures,
-.lk-trial__job-error {
-  color: var(--wsl-color-danger, #c0392b);
+.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

@@ -59,6 +59,7 @@ function Harness() {
                 setView: () => {},
                 zoom: 1,
                 setZoom: () => {},
+                activeToolId: null,
               },
               emit: () => {},
             })}