@weasel-js/labkit 0.1.0

package/src/instrument/validateConfigSchema.ts

@@ -0,0 +1,65 @@
+import type { ConfigField, ConfigFieldType } from '../controls/types';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const KNOWN_TYPES: ConfigFieldType[] = ['slider', 'checkbox', 'select', 'number', 'text', 'color'];
+
+export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
+  const errors: string[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const field of fields) {
+    if (field.key === '') {
+      errors.push('Field has empty key');
+    } else if (seenKeys.has(field.key)) {
+      errors.push(`Duplicate config key: "${field.key}"`);
+    } else {
+      seenKeys.add(field.key);
+    }
+
+    if (field.label === '') {
+      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`);
+      }
+      if (field.min >= field.max) {
+        errors.push(`Slider "${field.key}": min must be < max`);
+      } else if (field.default < field.min || field.default > field.max) {
+        errors.push(`Slider "${field.key}": default ${field.default} is outside [min, max]`);
+      }
+    } else if (field.type === 'number') {
+      if (!Number.isFinite(field.default)) {
+        errors.push(`Field "${field.key}": default must be a finite number`);
+      }
+    } else if (field.type === 'select') {
+      if (field.options.length === 0) {
+        errors.push(`Select "${field.key}": options array must not be empty`);
+      } else {
+        const seenValues = new Set<string>();
+        for (const opt of field.options) {
+          if (seenValues.has(opt.value)) {
+            errors.push(`Select "${field.key}": duplicate option value "${opt.value}"`);
+          } else {
+            seenValues.add(opt.value);
+          }
+        }
+        if (!seenValues.has(field.default)) {
+          errors.push(`Select "${field.key}": default "${field.default}" is not among options`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/lab/Lab.less

@@ -0,0 +1,3 @@
+.lk-lab {
+  height: 100%;
+}

package/src/lab/Lab.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect } from 'react';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+import { useLabContext } from './LabContext';
+
+const StubInstrument: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({ value: 50 }),
+  initialState: (config) => ({ doubled: (config as { value: number }).value * 2 }),
+  render: ({ state }) => (
+    <div className="lk-stub-display">doubled: {(state as { doubled: number }).doubled}</div>
+  ),
+};
+
+const meta: Meta<typeof Lab> = {
+  title: 'labkit/Lab/Lab',
+  component: Lab,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Lab>;
+
+export const Default: Story = {
+  args: {
+    instruments: [StubInstrument],
+    defaultInstrument: 'Stub',
+    title: 'Default Lab',
+    storage: null,
+  },
+};
+
+function AddSecondWorkspace() {
+  const ctx = useLabContext();
+  // biome-ignore lint/correctness/useExhaustiveDependencies: run once on mount
+  useEffect(() => {
+    if (ctx.workspaces.length < 2) ctx.addWorkspace('Stub');
+  }, []);
+  return null;
+}
+
+export const TwoWorkspaces: Story = {
+  args: {
+    instruments: [StubInstrument],
+    defaultInstrument: 'Stub',
+    title: 'Two Workspaces',
+    storage: null,
+    children: <AddSecondWorkspace />,
+  },
+};

package/src/lab/Lab.test.tsx

@@ -0,0 +1,126 @@
+import { act, render, screen } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+import { LabContext, type LabContextValue } from './LabContext';
+
+const stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({ count: 0 }),
+  initialState: (config) => ({ value: (config as { count: number }).count }),
+  render: () => <div data-testid="stub-content">stub</div>,
+};
+
+const stubB: Instrument = {
+  ...stub,
+  name: 'StubB',
+  render: () => <div data-testid="stub-b-content">b</div>,
+};
+
+let labRef: LabContextValue | null = null;
+
+function CaptureLab({ children }: { children?: ReactNode }) {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        if (value) labRef = value;
+        return children ?? null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+function mountLab(props: Partial<Parameters<typeof Lab>[0]> = {}) {
+  labRef = null;
+  return render(
+    <Lab instruments={[stub, stubB]} defaultInstrument="Stub" {...props}>
+      <CaptureLab />
+    </Lab>,
+  );
+}
+
+describe('<Lab>', () => {
+  it('renders one workspace by default', () => {
+    mountLab();
+    expect(screen.getAllByRole('region', { name: /workspace/i })).toHaveLength(1);
+  });
+
+  it('addWorkspace adds a second workspace', () => {
+    mountLab();
+    act(() => labRef?.addWorkspace('Stub'));
+    expect(screen.getAllByRole('region', { name: /workspace/i })).toHaveLength(2);
+  });
+
+  it('closeWorkspace removes one when more than one exists', () => {
+    mountLab();
+    act(() => labRef?.addWorkspace('Stub'));
+    const first = labRef?.workspaces[0];
+    act(() => labRef?.closeWorkspace(first?.id ?? ''));
+    expect(screen.getAllByRole('region', { name: /workspace/i })).toHaveLength(1);
+  });
+
+  it('closeWorkspace is a no-op on the last workspace', () => {
+    mountLab();
+    const only = labRef?.workspaces[0];
+    act(() => labRef?.closeWorkspace(only?.id ?? ''));
+    expect(screen.getAllByRole('region', { name: /workspace/i })).toHaveLength(1);
+  });
+
+  it('cloneWorkspace inserts immediately after source', () => {
+    mountLab();
+    act(() => labRef?.addWorkspace('StubB'));
+    const ws0 = labRef?.workspaces[0];
+    const ws1 = labRef?.workspaces[1];
+    act(() => labRef?.cloneWorkspace(ws0?.id ?? ''));
+    const ids = labRef?.workspaces.map((w) => w.id) ?? [];
+    expect(ids).toHaveLength(3);
+    expect(ids[0]).toBe(ws0?.id);
+    expect(ids[2]).toBe(ws1?.id);
+  });
+
+  it('resetWorkspace restores defaults', () => {
+    mountLab();
+    const ws = labRef?.workspaces[0];
+    if (!ws) throw new Error('no workspace');
+    act(() => labRef?.resetWorkspace(ws.id));
+    const reset = labRef?.workspaces[0];
+    expect(reset?.config).toEqual({ count: 0 });
+    expect(reset?.state).toEqual({ value: 0 });
+  });
+
+  it('theme="light" applies lk-theme-light class', () => {
+    const { container } = mountLab({ theme: 'light' });
+    expect(container.querySelector('.lk-lab')?.className).toMatch(/lk-theme-light/);
+  });
+
+  it('theme="interstellar" applies lk-theme-interstellar class', () => {
+    const { container } = mountLab({ theme: 'interstellar' });
+    expect(container.querySelector('.lk-lab')?.className).toMatch(/lk-theme-interstellar/);
+  });
+
+  it('theme="auto" applies neither class', () => {
+    const { container } = mountLab({ theme: 'auto' });
+    const cls = container.querySelector('.lk-lab')?.className ?? '';
+    expect(cls).not.toMatch(/lk-theme-light/);
+    expect(cls).not.toMatch(/lk-theme-interstellar/);
+  });
+
+  it('setTheme updates class at runtime', () => {
+    const { container } = mountLab({ theme: 'auto' });
+    act(() => labRef?.setTheme('light'));
+    expect(container.querySelector('.lk-lab')?.className).toMatch(/lk-theme-light/);
+  });
+
+  it('throws when instruments is empty', () => {
+    expect(() => render(<Lab instruments={[]} defaultInstrument="Stub" />)).toThrow(
+      /requires a non-empty `instruments` array/,
+    );
+  });
+
+  it('throws when defaultInstrument does not match any instrument', () => {
+    expect(() => render(<Lab instruments={[stub]} defaultInstrument="Missing" />)).toThrow(
+      /Unknown instrument/,
+    );
+  });
+});

package/src/lab/Lab.tsx

@@ -0,0 +1,196 @@
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
+import { useStore } from 'zustand/react';
+import type { Instrument } from '../instrument/types';
+import { noneAdapter } from '../state/adapters';
+import { LabStoreContext } from '../state/context';
+import { createLabStore, type LabStore } from '../state/store';
+import type { StorageAdapter, WorkspaceRecord } from '../state/types';
+import { Workspace } from '../workspace/Workspace';
+import {
+  addWorkspace as addWorkspaceOp,
+  cloneWorkspace as cloneWorkspaceOp,
+  closeWorkspace as closeWorkspaceOp,
+  resetWorkspace as resetWorkspaceOp,
+} from '../workspace/workspaceOps';
+import { LabContext, type LabContextValue } from './LabContext';
+import { LabShell } from './LabShell';
+import { WorkspaceGrid } from './WorkspaceGrid';
+
+export interface LabProps {
+  instruments: Instrument[];
+  defaultInstrument: string;
+  storage?: StorageAdapter | null;
+  storageKey?: string;
+  theme?: 'auto' | 'light' | 'interstellar';
+  /**
+   * Optional list of CSS colors used to compose the interstellar theme's
+   * cosmic backdrop. Each color becomes one radial-gradient blob on the
+   * dark void base. Order maps to a fixed spread of positions; extras wrap
+   * around. Ignored unless `theme="interstellar"` is active.
+   */
+  nebula?: readonly string[];
+  title?: string;
+  children?: ReactNode;
+}
+
+function buildStore(
+  instruments: Instrument[],
+  defaultInstrument: string,
+  storage: StorageAdapter,
+  storageKey: string,
+  initialTheme: 'auto' | 'light' | 'interstellar',
+): LabStore {
+  const store = createLabStore({ storageKey, storage, initialTheme });
+  if (store.getState().workspaces.length === 0) {
+    const seeded = addWorkspaceOp([], instruments, defaultInstrument);
+    const record = seeded[0];
+    if (record) {
+      const { undoStack: _undoStack, ...rest } = record;
+      store.getState().addWorkspace(rest);
+    }
+  }
+  return store;
+}
+
+// Fixed spread of nebula blob positions / sizes / fall-off stops. Colors
+// supplied via the `nebula` prop are slotted into these slots in order;
+// callers passing more than 5 wrap around (intentional — keeps the look
+// readable and bounded).
+const NEBULA_SLOTS = [
+  { cx: '18%', cy: '30%', sx: '60%', sy: '80%', stop: '70%' },
+  { cx: '78%', cy: '70%', sx: '55%', sy: '90%', stop: '65%' },
+  { cx: '50%', cy: '50%', sx: '50%', sy: '70%', stop: '75%' },
+  { cx: '12%', cy: '82%', sx: '50%', sy: '70%', stop: '70%' },
+  { cx: '85%', cy: '18%', sx: '55%', sy: '80%', stop: '70%' },
+] as const;
+
+function buildNebula(colors: readonly string[]): string {
+  const blobs = colors.map((c, i) => {
+    const p = NEBULA_SLOTS[i % NEBULA_SLOTS.length]!;
+    return `radial-gradient(ellipse ${p.sx} ${p.sy} at ${p.cx} ${p.cy}, color-mix(in srgb, ${c} 22%, transparent), transparent ${p.stop})`;
+  });
+  blobs.push('radial-gradient(ellipse at center, #0a0a18 0%, #02020a 100%)');
+  return blobs.join(', ');
+}
+
+export function Lab({
+  instruments,
+  defaultInstrument,
+  storage,
+  storageKey,
+  theme,
+  nebula,
+  title,
+  children,
+}: LabProps) {
+  if (process.env.NODE_ENV !== 'production' && instruments.length === 0) {
+    throw new Error('[labkit] <Lab> requires a non-empty `instruments` array');
+  }
+
+  const storeRef = useRef<LabStore | null>(null);
+  if (storeRef.current === null) {
+    storeRef.current = buildStore(
+      instruments,
+      defaultInstrument,
+      storage ?? noneAdapter,
+      storageKey ?? 'labkit',
+      theme ?? 'auto',
+    );
+  }
+  const store = storeRef.current;
+
+  const workspaces = useStore(store, (s) => s.workspaces);
+  const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
+  const themeValue = useStore(store, (s) => s.theme);
+
+  useEffect(() => {
+    if (theme && theme !== store.getState().theme) {
+      store.getState().setTheme(theme);
+    }
+  }, [theme, store]);
+
+  const contextValue = useMemo<LabContextValue>(() => {
+    const replaceWorkspaces = (next: WorkspaceRecord[]): void => {
+      const currentById = new Map(store.getState().workspaces.map((w) => [w.id, w]));
+      const merged = next.map((w) => currentById.get(w.id) ?? w);
+      store.setState({ workspaces: merged });
+      // Trigger persistence flush via a tracked action.
+      store.getState().setTheme(store.getState().theme);
+    };
+
+    return {
+      instruments,
+      workspaces,
+      addWorkspace: (instrumentName) => {
+        const next = addWorkspaceOp(store.getState().workspaces, instruments, instrumentName);
+        replaceWorkspaces(next);
+      },
+      cloneWorkspace: (id) => {
+        const next = cloneWorkspaceOp(store.getState().workspaces, id);
+        replaceWorkspaces(next);
+      },
+      closeWorkspace: (id) => {
+        const next = closeWorkspaceOp(store.getState().workspaces, id);
+        replaceWorkspaces(next);
+      },
+      resetWorkspace: (id) => {
+        const next = resetWorkspaceOp(store.getState().workspaces, id, instruments);
+        const record = next.find((w) => w.id === id);
+        if (!record) return;
+        store.setState((s) => ({
+          workspaces: s.workspaces.map((w) =>
+            w.id === id
+              ? { ...w, config: record.config, state: record.state, view: record.view }
+              : w,
+          ),
+        }));
+        store.getState().updateWorkspaceView(id, record.view);
+      },
+      savedSnapshots,
+      saveSnapshot: (workspaceId, name) => {
+        store.getState().saveSnapshot(workspaceId, name ?? `Save ${new Date().toLocaleString()}`);
+      },
+      loadSnapshot: (workspaceId, snapshotId) => {
+        store.getState().loadSnapshot(snapshotId, workspaceId);
+      },
+      deleteSnapshot: (snapshotId) => {
+        store.getState().deleteSnapshot(snapshotId);
+      },
+      theme: themeValue,
+      setTheme: (t) => {
+        store.getState().setTheme(t);
+      },
+    };
+  }, [instruments, workspaces, savedSnapshots, themeValue, store]);
+
+  const themeClass =
+    themeValue === 'light'
+      ? 'lk-theme-light'
+      : themeValue === 'interstellar'
+        ? 'lk-theme-interstellar'
+        : '';
+
+  // Only apply the nebula override when interstellar is active and at
+  // least one color is provided. Setting a CSS custom property is the
+  // sanctioned use of inline style.
+  const nebulaStyle =
+    themeValue === 'interstellar' && nebula && nebula.length > 0
+      ? ({ ['--lk-space-nebula' as string]: buildNebula(nebula) } as CSSProperties)
+      : undefined;
+
+  return (
+    <LabStoreContext.Provider value={{ store }}>
+      <LabContext.Provider value={contextValue}>
+        <div className={`lk-lab ${themeClass}`.trim()} style={nebulaStyle}>
+          <LabShell title={title ?? 'Labkit'} theme={themeValue} header={children}>
+            <WorkspaceGrid>
+              {workspaces.map((w) => (
+                <Workspace key={w.id} id={w.id} />
+              ))}
+            </WorkspaceGrid>
+          </LabShell>
+        </div>
+      </LabContext.Provider>
+    </LabStoreContext.Provider>
+  );
+}

package/src/lab/LabContext.test.ts

@@ -0,0 +1,11 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { useLabContext } from './LabContext';
+
+describe('useLabContext', () => {
+  it('throws when used outside <Lab>', () => {
+    expect(() => renderHook(() => useLabContext())).toThrow(
+      /useLabContext must be used inside <Lab>/,
+    );
+  });
+});

package/src/lab/LabContext.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react';
+import type { Instrument } from '../instrument/types';
+import type { SavedSnapshot, WorkspaceRecord } from '../state/types';
+
+export interface LabContextValue {
+  instruments: Instrument[];
+  workspaces: WorkspaceRecord[];
+  addWorkspace: (instrumentName: string) => void;
+  cloneWorkspace: (id: string) => void;
+  closeWorkspace: (id: string) => void;
+  resetWorkspace: (id: string) => void;
+  savedSnapshots: SavedSnapshot[];
+  saveSnapshot: (workspaceId: string, name?: string) => void;
+  loadSnapshot: (workspaceId: string, snapshotId: string) => void;
+  deleteSnapshot: (snapshotId: string) => void;
+  theme: 'auto' | 'light' | 'interstellar';
+  setTheme: (t: 'auto' | 'light' | 'interstellar') => void;
+}
+
+export const LabContext = createContext<LabContextValue | null>(null);
+
+export function useLabContext(): LabContextValue {
+  const ctx = useContext(LabContext);
+  if (ctx === null) {
+    throw new Error('useLabContext must be used inside <Lab>');
+  }
+  return ctx;
+}

package/src/lab/LabShell.less

@@ -0,0 +1,45 @@
+.lk-shell {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100vh;
+  background: var(--lk-bg);
+}
+
+.lk-shell-header {
+  display: flex;
+  align-items: center;
+  gap: var(--lk-spacing-md);
+  padding: var(--lk-spacing-sm) var(--lk-spacing-md);
+  background: var(--lk-bg-elevated);
+  border-bottom: 1px solid var(--lk-border);
+  z-index: var(--lk-z-toolbar);
+}
+
+.lk-shell-title {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--lk-text);
+}
+
+.lk-shell-header-actions {
+  margin-left: auto;
+  display: flex;
+  gap: var(--lk-spacing-sm);
+}
+
+.lk-shell-body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  padding: var(--lk-spacing-md);
+}
+
+.lk-shell-footer {
+  border-top: 1px solid var(--lk-border);
+  padding: var(--lk-spacing-xs) var(--lk-spacing-md);
+  background: var(--lk-bg-elevated);
+  color: var(--lk-text-muted);
+  font-size: var(--lk-font-size-sm);
+}

package/src/lab/LabShell.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { LabShell } from './LabShell';
+
+const meta: Meta<typeof LabShell> = {
+  title: 'labkit/Lab/LabShell',
+  component: LabShell,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof LabShell>;
+
+export const Default: Story = {
+  args: {
+    title: 'My Lab',
+    children: <p>Body content goes here.</p>,
+  },
+};
+
+export const WithHeaderActions: Story = {
+  args: {
+    title: 'My Lab',
+    header: (
+      <>
+        <button type="button">+ Add</button>
+        <button type="button">Reset</button>
+      </>
+    ),
+    children: <p>Body content with header actions.</p>,
+  },
+};
+
+export const WithFooter: Story = {
+  args: {
+    title: 'My Lab',
+    children: <p>Body content with footer.</p>,
+    footer: <span>Status: ready</span>,
+  },
+};

package/src/lab/LabShell.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { LabShell } from './LabShell';
+
+describe('LabShell', () => {
+  test('renders title in header', () => {
+    render(<LabShell title="My Lab">body</LabShell>);
+    expect(screen.getByRole('heading', { name: 'My Lab' })).toBeInTheDocument();
+  });
+
+  test('renders children in body', () => {
+    render(<LabShell title="t">body content</LabShell>);
+    expect(screen.getByText('body content')).toBeInTheDocument();
+  });
+
+  test('renders header slot when provided', () => {
+    render(
+      <LabShell title="t" header={<button type="button">action</button>}>
+        body
+      </LabShell>,
+    );
+    expect(screen.getByRole('button', { name: 'action' })).toBeInTheDocument();
+  });
+
+  test('applies lk-theme-light class when theme="light"', () => {
+    const { container } = render(
+      <LabShell title="t" theme="light">
+        x
+      </LabShell>,
+    );
+    const root = container.firstChild as HTMLElement;
+    expect(root.classList.contains('lk-theme-light')).toBe(true);
+    expect(root.classList.contains('lk-theme-interstellar')).toBe(false);
+  });
+
+  test('applies lk-theme-interstellar class when theme="interstellar"', () => {
+    const { container } = render(
+      <LabShell title="t" theme="interstellar">
+        x
+      </LabShell>,
+    );
+    const root = container.firstChild as HTMLElement;
+    expect(root.classList.contains('lk-theme-interstellar')).toBe(true);
+    expect(root.classList.contains('lk-theme-light')).toBe(false);
+  });
+
+  test('applies neither theme class when theme="auto" (default)', () => {
+    const { container } = render(<LabShell title="t">x</LabShell>);
+    const root = container.firstChild as HTMLElement;
+    expect(root.classList.contains('lk-theme-light')).toBe(false);
+    expect(root.classList.contains('lk-theme-interstellar')).toBe(false);
+  });
+
+  test('always applies lk-root class', () => {
+    const { container } = render(<LabShell title="t">x</LabShell>);
+    const root = container.firstChild as HTMLElement;
+    expect(root.classList.contains('lk-root')).toBe(true);
+  });
+});

package/src/lab/LabShell.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+
+export type LabTheme = 'auto' | 'light' | 'interstellar';
+
+export interface LabShellProps {
+  title: string;
+  children: ReactNode;
+  /** Optional content rendered into the header (e.g., action buttons). */
+  header?: ReactNode;
+  /** Optional content rendered into the footer. */
+  footer?: ReactNode;
+  /** Theme override. "auto" (default) follows prefers-color-scheme. */
+  theme?: LabTheme;
+}
+
+export function LabShell({ title, children, header, footer, theme = 'auto' }: LabShellProps) {
+  const themeClass =
+    theme === 'light'
+      ? ' lk-theme-light'
+      : theme === 'interstellar'
+        ? ' lk-theme-interstellar'
+        : '';
+  return (
+    <div className={`lk-root lk-shell${themeClass}`}>
+      <header className="lk-shell-header">
+        <h1 className="lk-shell-title">{title}</h1>
+        {header && <div className="lk-shell-header-actions">{header}</div>}
+      </header>
+      <main className="lk-shell-body">{children}</main>
+      {footer && <footer className="lk-shell-footer">{footer}</footer>}
+    </div>
+  );
+}

package/src/lab/WorkspaceGrid.less

@@ -0,0 +1,8 @@
+.lk-workspace-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--lk-grid-cols, 1), 1fr);
+  grid-template-rows: repeat(var(--lk-grid-rows, 1), 1fr);
+  gap: var(--lk-spacing-md);
+  width: 100%;
+  height: 100%;
+}