@weasel-js/labkit 0.1.0

package/src/dragdrop/dragDrop.test.tsx

@@ -0,0 +1,145 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useContext } from 'react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { useStore } from 'zustand/react';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { LabStoreContext } from '../state/context';
+
+interface DropState {
+  items: { id: string; x: number; y: number }[];
+}
+
+const testInstrument = defineInstrument<DropState, Record<string, never>>({
+  name: 'TestDrop',
+  defaultConfig: () => ({}),
+  initialState: () => ({ items: [] }),
+  configSchema: () => [],
+  render: () => null,
+  canvas: {
+    initialView: { zoom: 1, pan: { x: 0, y: 0 } },
+    layers: [{ id: 'main', draw: () => undefined }],
+  },
+  dragDrop: {
+    palette: [{ id: 'a', label: 'Item A' }],
+    onDrop: (worldPos, item, state) => ({
+      items: [...state.items, { id: item.id, x: worldPos.x, y: worldPos.y }],
+    }),
+  },
+  undo: { snapshotOn: ['canvas.itemAdded'], maxDepth: 10 },
+});
+
+const originalGetBoundingClientRect = HTMLElement.prototype.getBoundingClientRect;
+
+function StateProbe({ onState }: { onState: (state: DropState) => void }) {
+  const ctx = useContext(LabStoreContext);
+  const ws = useStore(
+    ctx?.store ?? ({ getState: () => ({ workspaces: [] }) } as never),
+    (s) => (s as { workspaces: { state: unknown }[] }).workspaces[0],
+  );
+  if (ws) onState(ws.state as DropState);
+  return null;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: cross-generic instrument array
+const instruments: any[] = [testInstrument];
+
+function renderLab(probe?: (state: DropState) => void) {
+  return render(
+    <Lab instruments={instruments} defaultInstrument="TestDrop">
+      {probe ? <StateProbe onState={probe} /> : null}
+    </Lab>,
+  );
+}
+
+beforeEach(() => {
+  HTMLElement.prototype.getBoundingClientRect = function () {
+    if (this.classList.contains('lk-workspace__canvas-host')) {
+      return {
+        x: 100,
+        y: 100,
+        left: 100,
+        top: 100,
+        right: 500,
+        bottom: 500,
+        width: 400,
+        height: 400,
+        toJSON: () => ({}),
+      } as DOMRect;
+    }
+    return originalGetBoundingClientRect.call(this);
+  };
+});
+
+afterEach(() => {
+  HTMLElement.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+});
+
+function pointerDown(el: Element, x: number, y: number) {
+  fireEvent.pointerDown(el, { clientX: x, clientY: y });
+}
+
+function windowPointerMove(x: number, y: number) {
+  act(() => {
+    window.dispatchEvent(new MouseEvent('pointermove', { clientX: x, clientY: y, bubbles: true }));
+  });
+}
+
+function windowPointerUp(x: number, y: number) {
+  act(() => {
+    window.dispatchEvent(new MouseEvent('pointerup', { clientX: x, clientY: y, bubbles: true }));
+  });
+}
+
+describe('DragDrop integration', () => {
+  it('renders palette item in the sidebar', () => {
+    renderLab();
+    expect(screen.getByRole('button', { name: 'Item A' })).toBeInTheDocument();
+  });
+
+  it('drops an item onto the canvas and appends it to state', () => {
+    let latest: DropState = { items: [] };
+    renderLab((s) => {
+      latest = s;
+    });
+    const palette = screen.getByRole('button', { name: 'Item A' });
+
+    act(() => {
+      pointerDown(palette, 0, 0);
+    });
+    windowPointerUp(250, 250);
+
+    expect(latest.items).toHaveLength(1);
+    expect(latest.items[0]?.id).toBe('a');
+  });
+
+  it('drop outside the canvas leaves state unchanged', () => {
+    let latest: DropState = { items: [] };
+    renderLab((s) => {
+      latest = s;
+    });
+    const palette = screen.getByRole('button', { name: 'Item A' });
+
+    act(() => {
+      pointerDown(palette, 0, 0);
+    });
+    windowPointerMove(10, 10);
+    windowPointerUp(10, 10);
+
+    expect(latest.items).toHaveLength(0);
+    expect(document.querySelector('.lk-drag-ghost')).toBeNull();
+  });
+
+  it('shows drag ghost during drag and clears on drop', () => {
+    renderLab();
+    const palette = screen.getByRole('button', { name: 'Item A' });
+
+    act(() => {
+      pointerDown(palette, 5, 5);
+    });
+    expect(document.querySelector('.lk-drag-ghost')).not.toBeNull();
+
+    windowPointerUp(250, 250);
+    expect(document.querySelector('.lk-drag-ghost')).toBeNull();
+  });
+});

package/src/dragdrop/index.ts

@@ -0,0 +1 @@
+export type { DragDropCapability, DragFeedback, PaletteItem } from '../instrument/types';

package/src/index.ts

@@ -0,0 +1,70 @@
+export type { CanvasLayerDescriptor, CanvasStackContextValue, CanvasStackProps } from './canvas';
+export { CanvasStack, CanvasStackContext, screenToWorld, worldToScreen } from './canvas';
+export { ControlPanel } from './controls/ControlPanel';
+export type {
+  CheckboxField,
+  ColorField,
+  ConfigField,
+  ConfigFieldBase,
+  ConfigFieldType,
+  NumberField,
+  SelectField,
+  SelectOption,
+  SliderField,
+  TextField,
+} from './controls/types';
+export type { CapabilityFlags } from './instrument/capabilityDetector';
+export { detectCapabilities } from './instrument/capabilityDetector';
+export { defineInstrument } from './instrument/defineInstrument';
+export type {
+  CanvasCapability,
+  CanvasLayer,
+  DragDropCapability,
+  DragFeedback,
+  HitResult,
+  Instrument,
+  LayerCapability,
+  LayerDescriptor,
+  PaletteItem,
+  Point,
+  RenderContext,
+  SystemEvent,
+  UndoCapability,
+  ViewTransform,
+} from './instrument/types';
+export type { ValidationResult } from './instrument/validateConfigSchema';
+export { validateConfigSchema } from './instrument/validateConfigSchema';
+export * from './lab';
+export type { LayerListProps } from './layers';
+export { LayerList } from './layers';
+export * from './primitives';
+export {
+  createMemoryAdapter,
+  localStorageAdapter,
+  noneAdapter,
+  sessionStorageAdapter,
+  urlHashAdapter,
+} from './state/adapters';
+export {
+  LabStoreContext,
+  LabStoreProvider,
+  useLabStore,
+  useWorkspaceId,
+  WorkspaceIdContext,
+  WorkspaceIdProvider,
+} from './state/context';
+export type {
+  CreateLabStoreOptions,
+  ExperimentStateHandle,
+  LabStoreState,
+  SavedSnapshot,
+  StorageAdapter,
+  UndoStack,
+  WorkspaceRecord,
+} from './state/types';
+export { useExperimentState } from './state/useExperimentState';
+export * from './ui/layers';
+export * from './ui/properties';
+export type { EventBus, EventListener } from './undo';
+export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo';
+export * from './workspace';

package/src/instrument/SineWave.smoke.test.tsx

@@ -0,0 +1,94 @@
+import { render } from '@testing-library/react';
+import type { ReactElement } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from './defineInstrument';
+import type { RenderContext } from './types';
+import { validateConfigSchema } from './validateConfigSchema';
+
+interface SineState {
+  frame: number;
+}
+
+interface SineConfig {
+  frequency: number;
+  amplitude: number;
+  showGrid: boolean;
+}
+
+const SineWaveInstrument = defineInstrument<SineState, SineConfig>({
+  name: 'Sine Wave',
+  configSchema: () => [
+    {
+      key: 'frequency',
+      label: 'Frequency',
+      type: 'slider',
+      min: 0.1,
+      max: 10,
+      step: 0.1,
+      default: 2,
+    },
+    { key: 'amplitude', label: 'Amplitude', type: 'slider', min: 0.1, max: 1, default: 0.5 },
+    { key: 'showGrid', label: 'Show grid', type: 'checkbox', default: true },
+  ],
+  defaultConfig: () => ({ frequency: 2, amplitude: 0.5, showGrid: true }),
+  initialState: () => ({ frame: 0 }),
+  render: ({ state }) => <div className="lk-sine-wave">frame: {state.frame}</div>,
+  onConfigChange: (_config, _prev, state) => ({ ...state, frame: 0 }),
+  serialize: (state) => ({ frame: state.frame }),
+  deserialize: (data) => {
+    const d = data as { frame?: number };
+    return { frame: typeof d.frame === 'number' ? d.frame : 0 };
+  },
+});
+
+describe('SineWave instrument smoke test', () => {
+  it('configSchema validates clean', () => {
+    const result = validateConfigSchema(SineWaveInstrument.configSchema?.() ?? []);
+    expect(result.valid).toBe(true);
+  });
+
+  it('initialState produces { frame: 0 }', () => {
+    const s = SineWaveInstrument.initialState(SineWaveInstrument.defaultConfig());
+    expect(s).toEqual({ frame: 0 });
+  });
+
+  it('onConfigChange resets frame', () => {
+    const next = SineWaveInstrument.onConfigChange?.(
+      { frequency: 5, amplitude: 0.5, showGrid: true },
+      { frequency: 2, amplitude: 0.5, showGrid: true },
+      { frame: 3 },
+    );
+    expect(next).toEqual({ frame: 0 });
+  });
+
+  it('serialize round-trips', () => {
+    expect(SineWaveInstrument.serialize?.({ frame: 7 })).toEqual({ frame: 7 });
+  });
+
+  it('deserialize preserves valid data', () => {
+    expect(
+      SineWaveInstrument.deserialize?.({ frame: 7 }, SineWaveInstrument.defaultConfig()),
+    ).toEqual({
+      frame: 7,
+    });
+  });
+
+  it('deserialize falls back when field missing', () => {
+    expect(SineWaveInstrument.deserialize?.({}, SineWaveInstrument.defaultConfig())).toEqual({
+      frame: 0,
+    });
+  });
+
+  it('renders into the DOM', () => {
+    const ctx: RenderContext<SineState, SineConfig> = {
+      state: { frame: 0 },
+      config: SineWaveInstrument.defaultConfig(),
+      setState: vi.fn(),
+      setConfig: vi.fn(),
+      workspace: { id: 'w', zoom: 1, setZoom: vi.fn() },
+      emit: vi.fn(),
+    };
+    const { container } = render(SineWaveInstrument.render(ctx) as ReactElement);
+    expect(container.querySelector('.lk-sine-wave')).not.toBeNull();
+  });
+});

package/src/instrument/capabilityDetector.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { detectCapabilities } from './capabilityDetector';
+import type { Instrument } from './types';
+
+function baseInstrument(extras: Partial<Instrument>): Instrument {
+  return {
+    name: 'T',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: () => null,
+    ...extras,
+  };
+}
+
+describe('detectCapabilities', () => {
+  it('returns all false for a bare instrument', () => {
+    expect(detectCapabilities(baseInstrument({}))).toEqual({
+      hasCanvas: false,
+      hasLayers: false,
+      hasDragDrop: false,
+      hasUndo: false,
+    });
+  });
+
+  it('detects canvas only', () => {
+    const inst = baseInstrument({ canvas: { layers: [] } });
+    expect(detectCapabilities(inst)).toEqual({
+      hasCanvas: true,
+      hasLayers: false,
+      hasDragDrop: false,
+      hasUndo: false,
+    });
+  });
+
+  it('detects layers only', () => {
+    const inst = baseInstrument({ layers: { ids: ['a'] } });
+    expect(detectCapabilities(inst).hasLayers).toBe(true);
+  });
+
+  it('detects dragDrop only', () => {
+    const inst = baseInstrument({ dragDrop: { palette: [], onDrop: (_p, _i, s) => s } });
+    expect(detectCapabilities(inst).hasDragDrop).toBe(true);
+  });
+
+  it('detects undo only', () => {
+    const inst = baseInstrument({ undo: {} });
+    expect(detectCapabilities(inst).hasUndo).toBe(true);
+  });
+
+  it('detects all four capabilities', () => {
+    const inst = baseInstrument({
+      canvas: { layers: [] },
+      layers: { ids: [] },
+      dragDrop: { palette: [], onDrop: (_p, _i, s) => s },
+      undo: {},
+    });
+    expect(detectCapabilities(inst)).toEqual({
+      hasCanvas: true,
+      hasLayers: true,
+      hasDragDrop: true,
+      hasUndo: true,
+    });
+  });
+});

package/src/instrument/capabilityDetector.ts

@@ -0,0 +1,17 @@
+import type { Instrument } from './types';
+
+export interface CapabilityFlags {
+  hasCanvas: boolean;
+  hasLayers: boolean;
+  hasDragDrop: boolean;
+  hasUndo: boolean;
+}
+
+export function detectCapabilities(instrument: Instrument<unknown, unknown>): CapabilityFlags {
+  return {
+    hasCanvas: instrument.canvas != null,
+    hasLayers: instrument.layers != null,
+    hasDragDrop: instrument.dragDrop != null,
+    hasUndo: instrument.undo != null,
+  };
+}

package/src/instrument/defineInstrument.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineInstrument } from './defineInstrument';
+import type { Instrument } from './types';
+
+describe('defineInstrument', () => {
+  it('returns the same object reference passed in', () => {
+    const spec: Instrument<{ n: number }, { x: number }> = {
+      name: 'Test',
+      defaultConfig: () => ({ x: 1 }),
+      initialState: (c) => ({ n: c.x }),
+      render: () => null,
+    };
+    const result = defineInstrument(spec);
+    expect(result).toBe(spec);
+  });
+
+  it('infers TS and TC from the literal', () => {
+    const inst = defineInstrument({
+      name: 'Inferred',
+      defaultConfig: () => ({ flag: true }),
+      initialState: (c) => ({ count: c.flag ? 1 : 0 }),
+      render: () => null,
+    });
+    expectTypeOf(inst.defaultConfig()).toEqualTypeOf<{ flag: boolean }>();
+    expectTypeOf(inst.initialState({ flag: true })).toEqualTypeOf<{ count: number }>();
+  });
+});

package/src/instrument/defineInstrument.ts

@@ -0,0 +1,5 @@
+import type { Instrument } from './types';
+
+export function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC> {
+  return spec;
+}

package/src/instrument/index.ts

@@ -0,0 +1,19 @@
+export { defineInstrument } from './defineInstrument';
+export type {
+  CanvasCapability,
+  CanvasLayer,
+  DragDropCapability,
+  DragFeedback,
+  HitResult,
+  Instrument,
+  LayerCapability,
+  LayerDescriptor,
+  PaletteItem,
+  Point,
+  RenderContext,
+  SystemEvent,
+  UndoCapability,
+  ViewTransform,
+} from './types';
+export type { ValidationResult } from './validateConfigSchema';
+export { validateConfigSchema } from './validateConfigSchema';

package/src/instrument/types.ts

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+import type { ConfigField } from '../controls/types';
+
+export interface RenderContext<TS = unknown, TC = unknown> {
+  state: TS;
+  config: TC;
+  setState: (next: TS | ((prev: TS) => TS)) => void;
+  setConfig: (key: keyof TC, value: unknown) => void;
+  workspace: {
+    id: string;
+    zoom: number;
+    setZoom: (z: number) => void;
+  };
+  emit: (event: string) => void;
+}
+
+export interface CanvasLayer<TS = unknown, TC = unknown> {
+  id: string;
+  draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
+}
+
+export interface CanvasCapability<TS = unknown, TC = unknown> {
+  layers: CanvasLayer<TS, TC>[];
+  initialView?: { zoom: number; pan: { x: number; y: number } };
+}
+
+export interface LayerCapability {
+  ids: string[];
+}
+
+export interface DragDropCapability<TS = unknown, TC = unknown> {
+  palette: PaletteItem[] | ((state: TS, config: TC) => PaletteItem[]);
+  onDrop: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => TS;
+  onDragOver?: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => DragFeedback | null;
+  pickUp?: (hit: HitResult, state: TS, config: TC) => { item: PaletteItem; state: TS } | null;
+}
+
+export interface UndoCapability {
+  snapshotOn?: string[];
+  maxDepth?: number;
+}
+
+export type SystemEvent = string;
+
+export type Point = { x: number; y: number };
+export type HitResult = { hit: boolean; layerId?: string; pointId?: string };
+export type ViewTransform = { zoom: number; pan: Point };
+export type LayerDescriptor = { id: string; label: string; alwaysOn?: boolean };
+export type PaletteItem = { id: string; label: string; data?: unknown };
+export type DragFeedback = { ok: boolean; reason?: string };
+
+export interface Instrument<TS = unknown, TC = unknown> {
+  name: string;
+  defaultConfig: () => TC;
+  initialState: (config: TC) => TS;
+  configSchema?: () => ConfigField[];
+  render: (ctx: RenderContext<TS, TC>) => ReactNode;
+  onConfigChange?: (config: TC, prev: TC, state: TS) => TS;
+  serialize?: (state: TS) => unknown;
+  deserialize?: (data: unknown, config: TC) => TS;
+  canvas?: CanvasCapability<TS, TC>;
+  layers?: LayerCapability;
+  dragDrop?: DragDropCapability<TS, TC>;
+  undo?: UndoCapability;
+}

package/src/instrument/validateConfigSchema.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import type { ConfigField } from '../controls/types';
+import { validateConfigSchema } from './validateConfigSchema';
+
+describe('validateConfigSchema', () => {
+  it('returns valid for a well-formed schema', () => {
+    const fields: ConfigField[] = [
+      { key: 'freq', label: 'Frequency', type: 'slider', min: 0, max: 10, default: 5 },
+      { key: 'on', label: 'On', type: 'checkbox', default: true },
+    ];
+    expect(validateConfigSchema(fields)).toEqual({ valid: true, errors: [] });
+  });
+
+  it('flags duplicate keys', () => {
+    const fields: ConfigField[] = [
+      { key: 'a', label: 'A', type: 'checkbox', default: true },
+      { key: 'a', label: 'A2', type: 'checkbox', default: false },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.valid).toBe(false);
+    expect(r.errors).toContain('Duplicate config key: "a"');
+  });
+
+  it('flags unknown field type', () => {
+    const fields = [
+      { key: 'x', label: 'X', type: 'mystery', default: 1 },
+    ] as unknown as ConfigField[];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Unknown field type: "mystery" on key "x"');
+  });
+
+  it('flags slider min >= max', () => {
+    const fields: ConfigField[] = [
+      { key: 's', label: 'S', type: 'slider', min: 5, max: 5, default: 5 },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Slider "s": min must be < max');
+  });
+
+  it('flags slider default outside [min, max]', () => {
+    const fields: ConfigField[] = [
+      { key: 's', label: 'S', type: 'slider', min: 0, max: 10, default: 99 },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Slider "s": default 99 is outside [min, max]');
+  });
+
+  it('flags select with empty options', () => {
+    const fields: ConfigField[] = [
+      { key: 'sel', label: 'Sel', type: 'select', default: 'a', options: [] },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Select "sel": options array must not be empty');
+  });
+
+  it('flags select with duplicate option values', () => {
+    const fields: ConfigField[] = [
+      {
+        key: 'sel',
+        label: 'Sel',
+        type: 'select',
+        default: 'a',
+        options: [
+          { value: 'a', label: 'A' },
+          { value: 'a', label: 'A2' },
+        ],
+      },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Select "sel": duplicate option value "a"');
+  });
+
+  it('flags select default not in options', () => {
+    const fields: ConfigField[] = [
+      {
+        key: 'sel',
+        label: 'Sel',
+        type: 'select',
+        default: 'z',
+        options: [{ value: 'a', label: 'A' }],
+      },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Select "sel": default "z" is not among options');
+  });
+
+  it('flags non-finite slider default', () => {
+    const fields: ConfigField[] = [
+      { key: 's', label: 'S', type: 'slider', min: 0, max: 10, default: Number.NaN },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field "s": default must be a finite number');
+  });
+
+  it('flags non-finite number default', () => {
+    const fields: ConfigField[] = [
+      { key: 'n', label: 'N', type: 'number', default: Number.POSITIVE_INFINITY },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field "n": default must be a finite number');
+  });
+
+  it('flags empty key', () => {
+    const fields: ConfigField[] = [{ key: '', label: 'L', type: 'checkbox', default: false }];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field has empty key');
+  });
+
+  it('flags empty label', () => {
+    const fields: ConfigField[] = [{ key: 'k', label: '', type: 'checkbox', default: false }];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field "k" has empty label');
+  });
+
+  it('collects multiple errors in a single call', () => {
+    const fields: ConfigField[] = [
+      { key: 'a', label: 'A', type: 'slider', min: 10, max: 0, default: 5 },
+      { key: 'a', label: 'A2', type: 'checkbox', default: true },
+    ];
+    const r = validateConfigSchema(fields);
+    expect(r.errors.length).toBeGreaterThanOrEqual(2);
+    expect(r.errors).toContain('Slider "a": min must be < max');
+    expect(r.errors).toContain('Duplicate config key: "a"');
+  });
+});