@weasel-js/labkit 0.1.0

package/src/workspace/Workspace.tsx

@@ -0,0 +1,255 @@
+import { type ReactNode, useContext, useMemo, useRef, useState } from 'react';
+import { useStore } from 'zustand/react';
+import { CanvasStack } from '../canvas/CanvasStack';
+import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
+import { DragOverlay, useDragDrop } from '../dragdrop/DragDropRuntime';
+import { Palette } from '../dragdrop/Palette';
+import type {
+  Instrument,
+  LayerDescriptor,
+  PaletteItem,
+  RenderContext,
+  ViewTransform,
+} from '../instrument/types';
+import { useLabContext } from '../lab/LabContext';
+import { LayerList } from '../layers/LayerList';
+import { LabStoreContext } from '../state/context';
+import type { LabStore } from '../state/store';
+import type { WorkspaceRecord } from '../state/types';
+import { createEventBus, type EventBus } from '../undo/eventBus';
+import { pushSnapshot, redo as undoRedo, undo as undoUndo } from '../undo/undoStack';
+import type { UndoBindings } from './WorkspaceChrome';
+import { WorkspaceChrome } from './WorkspaceChrome';
+
+export interface WorkspaceProps {
+  id: string;
+}
+
+export function Workspace({ id }: WorkspaceProps) {
+  const lab = useLabContext();
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] <Workspace> requires <LabStoreProvider>');
+  const record = useStore(storeCtx.store, (s) => s.workspaces.find((w) => w.id === id));
+  if (!record) {
+    return <div className="lk-workspace lk-workspace--unknown">Workspace not found: {id}</div>;
+  }
+  const instrument = lab.instruments.find((i) => i.name === record.instrumentName);
+  if (!instrument) {
+    return (
+      <div className="lk-workspace lk-workspace--unknown">
+        Unknown instrument: {record.instrumentName}
+      </div>
+    );
+  }
+  return (
+    <WorkspaceRuntime
+      record={record}
+      instrument={instrument}
+      store={storeCtx.store}
+      isLast={lab.workspaces.length <= 1}
+    />
+  );
+}
+
+interface WorkspaceRuntimeProps {
+  record: WorkspaceRecord;
+  instrument: Instrument;
+  store: LabStore;
+  isLast: boolean;
+}
+
+function WorkspaceRuntime({ record, instrument, store, isLast }: WorkspaceRuntimeProps) {
+  const canvasContainerRef = useRef<HTMLDivElement | null>(null);
+  const updateWorkspaceState = useStore(store, (s) => s.updateWorkspaceState);
+  const updateWorkspaceConfig = useStore(store, (s) => s.updateWorkspaceConfig);
+  const updateWorkspaceView = useStore(store, (s) => s.updateWorkspaceView);
+  const updateWorkspaceUndoStack = useStore(store, (s) => s.updateWorkspaceUndoStack);
+
+  const busRef = useRef<EventBus | null>(null);
+  if (busRef.current === null) busRef.current = createEventBus();
+  const bus = busRef.current;
+
+  const [layerVisibility, setLayerVisibility] = useState<Record<string, boolean>>({});
+  const [layerOrder, setLayerOrder] = useState<string[] | null>(null);
+
+  const undoCap = instrument.undo;
+  const undoEvents = useMemo(() => new Set(undoCap?.snapshotOn ?? ['state.change']), [undoCap]);
+  const maxDepth = undoCap?.maxDepth ?? 50;
+
+  const snapshotIfNeeded = (event: string): void => {
+    if (!undoCap || !undoEvents.has(event)) return;
+    const current = store.getState().workspaces.find((w) => w.id === record.id);
+    if (!current) return;
+    const snap = structuredClone(current.state);
+    updateWorkspaceUndoStack(record.id, (prev) => pushSnapshot(prev, snap, maxDepth));
+  };
+
+  const setView = (v: ViewTransform): void => updateWorkspaceView(record.id, v);
+
+  const renderCtx: RenderContext<unknown, unknown> = {
+    state: record.state,
+    config: record.config,
+    setState: (next) => {
+      snapshotIfNeeded('state.change');
+      updateWorkspaceState(record.id, next);
+      bus.emit('state.change');
+    },
+    setConfig: (key, value) => {
+      const evt = `config.change:${String(key)}`;
+      snapshotIfNeeded('config.change');
+      snapshotIfNeeded(evt);
+      updateWorkspaceConfig(record.id, key as never, value as never);
+      bus.emit('config.change');
+      bus.emit(evt);
+    },
+    workspace: {
+      id: record.id,
+      zoom: record.view.zoom,
+      setZoom: (z) => updateWorkspaceView(record.id, { ...record.view, zoom: z }),
+    },
+    emit: (event) => {
+      snapshotIfNeeded(event);
+      bus.emit(event);
+    },
+  };
+
+  const undoBindings: UndoBindings | undefined = undoCap
+    ? {
+        canUndo: record.undoStack.past.length > 0,
+        canRedo: record.undoStack.future.length > 0,
+        undo: () => {
+          const result = undoUndo(record.undoStack, structuredClone(record.state));
+          if (!result) return;
+          updateWorkspaceState(record.id, result.snapshot as never);
+          updateWorkspaceUndoStack(record.id, result.stack);
+        },
+        redo: () => {
+          const result = undoRedo(record.undoStack, structuredClone(record.state));
+          if (!result) return;
+          updateWorkspaceState(record.id, result.snapshot as never);
+          updateWorkspaceUndoStack(record.id, result.stack);
+        },
+      }
+    : undefined;
+
+  const canvasLayers: CanvasLayerDescriptor[] = useMemo(() => {
+    if (!instrument.canvas) return [];
+    const baseLayers = instrument.canvas.layers;
+    const ordered = layerOrder
+      ? [...baseLayers].sort((a, b) => layerOrder.indexOf(a.id) - layerOrder.indexOf(b.id))
+      : baseLayers;
+    return ordered.map((layer) => ({
+      id: layer.id,
+      visible: layerVisibility[layer.id] !== false,
+      render: (ctx, view) =>
+        layer.draw(ctx, { state: record.state, config: record.config, zoom: view.zoom }),
+    }));
+  }, [instrument.canvas, record.state, record.config, layerVisibility, layerOrder]);
+
+  const layerDescriptors: LayerDescriptor[] = useMemo(() => {
+    if (!instrument.layers) return [];
+    return instrument.layers.ids.map((lid) => ({ id: lid, label: lid }));
+  }, [instrument.layers]);
+
+  const dragDropResult = useDragDrop({
+    capability: instrument.dragDrop ?? { palette: [], onDrop: (_p, _i, s) => s },
+    canvasContainerRef,
+    view: record.view,
+    state: record.state,
+    config: record.config,
+    setState: (next) => {
+      snapshotIfNeeded('canvas.itemAdded');
+      updateWorkspaceState(record.id, next as never);
+    },
+    emit: (evt) => {
+      snapshotIfNeeded(evt);
+      bus.emit(evt);
+    },
+  });
+
+  const paletteItems: PaletteItem[] = useMemo(() => {
+    if (!instrument.dragDrop) return [];
+    const p = instrument.dragDrop.palette;
+    return typeof p === 'function' ? p(record.state, record.config) : p;
+  }, [instrument.dragDrop, record.state, record.config]);
+
+  const layersWithFeedback: CanvasLayerDescriptor[] = useMemo(() => {
+    if (!dragDropResult.drag?.feedback) return canvasLayers;
+    const fb = dragDropResult.drag.feedback;
+    const screen = dragDropResult.drag.screenPos;
+    return [
+      ...canvasLayers,
+      {
+        id: '__lk_drag_feedback',
+        visible: true,
+        render: (ctx) => {
+          const el = canvasContainerRef.current;
+          if (!el) return;
+          const r = el.getBoundingClientRect();
+          ctx.save();
+          ctx.strokeStyle = fb.ok ? '#3a7' : '#c44';
+          ctx.lineWidth = 2;
+          ctx.beginPath();
+          ctx.arc(screen.x - r.left, screen.y - r.top, 16, 0, Math.PI * 2);
+          ctx.stroke();
+          ctx.restore();
+        },
+      },
+    ];
+  }, [canvasLayers, dragDropResult.drag]);
+
+  let body: ReactNode;
+  if (instrument.canvas) {
+    body = (
+      <div
+        ref={canvasContainerRef}
+        className="lk-workspace__canvas-host"
+        style={{ width: '100%', height: '100%', position: 'relative' }}
+      >
+        <CanvasStack layers={layersWithFeedback} view={record.view} onViewChange={setView} />
+        <DragOverlay drag={dragDropResult.drag} />
+      </div>
+    );
+  } else {
+    body = instrument.render(renderCtx);
+  }
+
+  const paletteNode =
+    paletteItems.length > 0 ? (
+      <Palette items={paletteItems} onDragStart={dragDropResult.startDrag} />
+    ) : null;
+
+  const layerListNode =
+    instrument.layers && layerDescriptors.length > 0 ? (
+      <LayerList
+        layers={layerDescriptors}
+        visibility={layerVisibility}
+        onReorder={(next) => {
+          setLayerOrder(next.map((l) => l.id));
+          bus.emit('layers.reorder');
+        }}
+        onToggle={(lid, visible) => {
+          setLayerVisibility((prev) => ({ ...prev, [lid]: visible }));
+          bus.emit('layers.toggle');
+        }}
+      />
+    ) : null;
+
+  return (
+    <WorkspaceChrome
+      workspaceId={record.id}
+      record={record}
+      instrument={instrument}
+      isLastWorkspace={isLast}
+      undoBindings={undoBindings}
+      sidebarExtras={
+        <>
+          {paletteNode}
+          {layerListNode}
+        </>
+      }
+    >
+      {body}
+    </WorkspaceChrome>
+  );
+}

package/src/workspace/WorkspaceChrome.tsx

@@ -0,0 +1,150 @@
+import { type KeyboardEvent, type ReactNode, useContext, useMemo } from 'react';
+import { useStore } from 'zustand/react';
+import type { Instrument } from '../instrument/types';
+import { useLabContext } from '../lab/LabContext';
+import { LabStoreContext } from '../state/context';
+import type { WorkspaceRecord } from '../state/types';
+import { DefaultSidebar } from './DefaultSidebar';
+import { DefaultStatusBar } from './DefaultStatusBar';
+import { DefaultToolbar } from './DefaultToolbar';
+import type {
+  SidebarSlot,
+  StatusBarSlot,
+  ToolbarSlot,
+  WorkspaceSidebarContext,
+  WorkspaceStatusBarContext,
+  WorkspaceToolbarContext,
+} from './slotTypes';
+
+export interface UndoBindings {
+  canUndo: boolean;
+  canRedo: boolean;
+  undo: () => void;
+  redo: () => void;
+}
+
+export interface WorkspaceChromeProps {
+  workspaceId: string;
+  record: WorkspaceRecord;
+  instrument: Instrument;
+  isLastWorkspace: boolean;
+  toolbar?: ToolbarSlot;
+  sidebar?: SidebarSlot;
+  statusBar?: StatusBarSlot;
+  undoBindings?: UndoBindings;
+  sidebarExtras?: ReactNode;
+  children: ReactNode;
+}
+
+export function WorkspaceChrome({
+  workspaceId,
+  record,
+  instrument,
+  isLastWorkspace,
+  toolbar,
+  sidebar,
+  statusBar,
+  undoBindings,
+  sidebarExtras,
+  children,
+}: WorkspaceChromeProps) {
+  const lab = useLabContext();
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] WorkspaceChrome requires <LabStoreProvider>');
+  const updateWorkspaceView = useStore(storeCtx.store, (s) => s.updateWorkspaceView);
+  const updateWorkspaceConfig = useStore(storeCtx.store, (s) => s.updateWorkspaceConfig);
+  const updateWorkspaceState = useStore(storeCtx.store, (s) => s.updateWorkspaceState);
+
+  const toolbarCtx = useMemo<WorkspaceToolbarContext>(() => {
+    const setZoom = (z: number): void => {
+      updateWorkspaceView(workspaceId, { ...record.view, zoom: z });
+    };
+    return {
+      workspaceId,
+      instrumentName: record.instrumentName,
+      hasUndo: instrument.undo != null,
+      canUndo: undoBindings?.canUndo ?? false,
+      canRedo: undoBindings?.canRedo ?? false,
+      undo: undoBindings?.undo ?? (() => {}),
+      redo: undoBindings?.redo ?? (() => {}),
+      zoom: record.view.zoom,
+      setZoom,
+      zoomIn: () => setZoom(record.view.zoom * 1.25),
+      zoomOut: () => setZoom(record.view.zoom * 0.8),
+      resetZoom: () => setZoom(1),
+      hasCanvas: instrument.canvas != null,
+      savedSnapshots: lab.savedSnapshots.filter((s) => s.workspaceId === workspaceId),
+      saveSnapshot: (name) => lab.saveSnapshot(workspaceId, name),
+      loadSnapshot: (snapshotId) => lab.loadSnapshot(workspaceId, snapshotId),
+      clone: () => lab.cloneWorkspace(workspaceId),
+      reset: () => lab.resetWorkspace(workspaceId),
+      close: () => lab.closeWorkspace(workspaceId),
+      isLastWorkspace,
+    };
+  }, [workspaceId, record, instrument, lab, isLastWorkspace, updateWorkspaceView, undoBindings]);
+
+  const sidebarCtx = useMemo<WorkspaceSidebarContext>(
+    () => ({
+      workspaceId,
+      instrumentName: record.instrumentName,
+      configFields: instrument.configSchema?.() ?? [],
+      config: record.config,
+      setConfig: (key, value) => {
+        const prevConfig = record.config as Record<string, unknown>;
+        if (process.env.NODE_ENV !== 'production' && !(key in prevConfig)) {
+          console.warn(
+            `[labkit] setConfig: unknown key "${key}" for instrument "${record.instrumentName}"`,
+          );
+        }
+        updateWorkspaceConfig(workspaceId, key as never, value as never);
+        if (instrument.onConfigChange) {
+          const nextConfig = { ...prevConfig, [key]: value };
+          const nextState = instrument.onConfigChange(nextConfig, prevConfig, record.state);
+          updateWorkspaceState(workspaceId, nextState as never);
+        }
+      },
+    }),
+    [workspaceId, record, instrument, updateWorkspaceConfig, updateWorkspaceState],
+  );
+
+  const statusCtx: WorkspaceStatusBarContext = {
+    workspaceId,
+    instrumentName: record.instrumentName,
+    zoom: record.view.zoom,
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>): void => {
+    const mod = e.metaKey || e.ctrlKey;
+    if (!mod) return;
+    if (e.key === 'z' || e.key === 'Z') {
+      e.preventDefault();
+      if (e.shiftKey) toolbarCtx.redo();
+      else toolbarCtx.undo();
+    } else if (e.key === 's' || e.key === 'S') {
+      e.preventDefault();
+      toolbarCtx.saveSnapshot();
+    }
+  };
+
+  return (
+    <section
+      className="lk-workspace"
+      aria-label={`Workspace ${record.instrumentName}`}
+      onKeyDown={handleKeyDown}
+    >
+      <div className="lk-workspace__toolbar">
+        {toolbar ? toolbar(toolbarCtx) : <DefaultToolbar ctx={toolbarCtx} />}
+      </div>
+      <div className="lk-workspace__body">
+        <div className="lk-workspace__sidebar">
+          {sidebar ? sidebar(sidebarCtx) : <DefaultSidebar ctx={sidebarCtx} />}
+          {sidebarExtras}
+        </div>
+        <div className="lk-workspace__content">{children}</div>
+      </div>
+      <div className="lk-workspace__status">
+        {statusBar ? statusBar(statusCtx) : <DefaultStatusBar ctx={statusCtx} />}
+      </div>
+    </section>
+  );
+}

package/src/workspace/index.ts

@@ -0,0 +1,24 @@
+export type { DefaultSidebarProps } from './DefaultSidebar';
+export { DefaultSidebar } from './DefaultSidebar';
+export type { DefaultStatusBarProps } from './DefaultStatusBar';
+export { DefaultStatusBar } from './DefaultStatusBar';
+export type { DefaultToolbarProps } from './DefaultToolbar';
+export { DefaultToolbar } from './DefaultToolbar';
+export type {
+  SidebarSlot,
+  StatusBarSlot,
+  ToolbarSlot,
+  WorkspaceSidebarContext,
+  WorkspaceStatusBarContext,
+  WorkspaceToolbarContext,
+} from './slotTypes';
+export type { WorkspaceProps } from './Workspace';
+export { Workspace } from './Workspace';
+export type { WorkspaceChromeProps } from './WorkspaceChrome';
+export { WorkspaceChrome } from './WorkspaceChrome';
+export {
+  addWorkspace,
+  cloneWorkspace,
+  closeWorkspace,
+  resetWorkspace,
+} from './workspaceOps';

package/src/workspace/slotTypes.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react';
+import type { ConfigField } from '../controls/types';
+import type { SavedSnapshot } from '../state/types';
+
+export interface WorkspaceToolbarContext {
+  workspaceId: string;
+  instrumentName: string;
+  hasUndo: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  undo: () => void;
+  redo: () => void;
+  zoom: number;
+  setZoom: (z: number) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+  hasCanvas: boolean;
+  savedSnapshots: SavedSnapshot[];
+  saveSnapshot: (name?: string) => void;
+  loadSnapshot: (snapshotId: string) => void;
+  clone: () => void;
+  reset: () => void;
+  close: () => void;
+  isLastWorkspace: boolean;
+}
+
+export interface WorkspaceSidebarContext {
+  workspaceId: string;
+  instrumentName: string;
+  configFields: ConfigField[];
+  config: unknown;
+  setConfig: (key: string, value: unknown) => void;
+}
+
+export interface WorkspaceStatusBarContext {
+  workspaceId: string;
+  instrumentName: string;
+  zoom: number;
+}
+
+export type ToolbarSlot = (ctx: WorkspaceToolbarContext) => ReactNode;
+export type SidebarSlot = (ctx: WorkspaceSidebarContext) => ReactNode;
+export type StatusBarSlot = (ctx: WorkspaceStatusBarContext) => ReactNode;

package/src/workspace/workspaceOps.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import type { WorkspaceRecord } from '../state/types';
+import { addWorkspace, cloneWorkspace, closeWorkspace, resetWorkspace } from './workspaceOps';
+
+interface CounterState {
+  count: number;
+}
+interface CounterConfig {
+  step: number;
+}
+
+const counter: Instrument<CounterState, CounterConfig> = {
+  name: 'Counter',
+  defaultConfig: () => ({ step: 1 }),
+  initialState: (config) => ({ count: 0 * config.step }),
+  render: () => null,
+};
+
+const counterWithCanvas: Instrument<CounterState, CounterConfig> = {
+  ...counter,
+  name: 'CounterCanvas',
+  canvas: {
+    layers: [],
+    initialView: { zoom: 2, pan: { x: 5, y: 7 } },
+  },
+};
+
+const instruments: Instrument[] = [counter as Instrument, counterWithCanvas as Instrument];
+
+function head<T>(arr: T[]): T {
+  const first = arr[0];
+  if (first === undefined) throw new Error('expected non-empty array');
+  return first;
+}
+
+describe('addWorkspace', () => {
+  it('appends a new record using defaultConfig and initialState', () => {
+    const out = addWorkspace([], instruments, 'Counter');
+    expect(out).toHaveLength(1);
+    expect(out[0]?.instrumentName).toBe('Counter');
+    expect(out[0]?.config).toEqual({ step: 1 });
+    expect(out[0]?.state).toEqual({ count: 0 });
+  });
+
+  it('assigns a unique id', () => {
+    const a = addWorkspace([], instruments, 'Counter');
+    const b = addWorkspace(a, instruments, 'Counter');
+    expect(b).toHaveLength(2);
+    expect(b[0]?.id).not.toBe(b[1]?.id);
+  });
+
+  it('uses canvas.initialView when present', () => {
+    const out = addWorkspace([], instruments, 'CounterCanvas');
+    expect(out[0]?.view).toEqual({ zoom: 2, pan: { x: 5, y: 7 } });
+  });
+
+  it('defaults view when canvas absent', () => {
+    const out = addWorkspace([], instruments, 'Counter');
+    expect(out[0]?.view).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });
+  });
+
+  it('throws when instrumentName is unknown', () => {
+    expect(() => addWorkspace([], instruments, 'Missing')).toThrow();
+  });
+
+  it('does not mutate input array', () => {
+    const arr: WorkspaceRecord[] = [];
+    addWorkspace(arr, instruments, 'Counter');
+    expect(arr).toHaveLength(0);
+  });
+});
+
+describe('cloneWorkspace', () => {
+  it('inserts clone immediately after source with new id', () => {
+    const a = addWorkspace([], instruments, 'Counter');
+    const sourceId = head(a).id;
+    const cloned = cloneWorkspace(a, sourceId);
+    expect(cloned).toHaveLength(2);
+    expect(cloned[0]?.id).toBe(sourceId);
+    expect(cloned[1]?.id).not.toBe(sourceId);
+    expect(cloned[1]?.instrumentName).toBe('Counter');
+  });
+
+  it('deep-copies config/state/view', () => {
+    const a = addWorkspace([], instruments, 'Counter');
+    const cloned = cloneWorkspace(a, head(a).id);
+    expect(cloned[1]?.config).not.toBe(cloned[0]?.config);
+    expect(cloned[1]?.state).not.toBe(cloned[0]?.state);
+    expect(cloned[1]?.view).not.toBe(cloned[0]?.view);
+  });
+
+  it('does not mutate input', () => {
+    const a = addWorkspace([], instruments, 'Counter');
+    const before = a.length;
+    cloneWorkspace(a, head(a).id);
+    expect(a).toHaveLength(before);
+  });
+});
+
+describe('closeWorkspace', () => {
+  it('removes the workspace with the given id', () => {
+    let arr = addWorkspace([], instruments, 'Counter');
+    arr = addWorkspace(arr, instruments, 'Counter');
+    const closed = closeWorkspace(arr, head(arr).id);
+    expect(closed).toHaveLength(1);
+    expect(closed[0]?.id).toBe(arr[1]?.id);
+  });
+
+  it('is a no-op when only one workspace remains', () => {
+    const arr = addWorkspace([], instruments, 'Counter');
+    const closed = closeWorkspace(arr, head(arr).id);
+    expect(closed).toEqual(arr);
+  });
+});
+
+describe('resetWorkspace', () => {
+  it('resets config and state to defaults; preserves instrumentName', () => {
+    const arr = addWorkspace([], instruments, 'Counter');
+    const id = head(arr).id;
+    head(arr).config = { step: 99 } as CounterConfig;
+    head(arr).state = { count: 42 } as CounterState;
+    const reset = resetWorkspace(arr, id, instruments);
+    expect(reset[0]?.config).toEqual({ step: 1 });
+    expect(reset[0]?.state).toEqual({ count: 0 });
+    expect(reset[0]?.instrumentName).toBe('Counter');
+  });
+
+  it('resets view to canvas.initialView when present', () => {
+    const arr = addWorkspace([], instruments, 'CounterCanvas');
+    head(arr).view = { zoom: 9, pan: { x: 9, y: 9 } };
+    const reset = resetWorkspace(arr, head(arr).id, instruments);
+    expect(reset[0]?.view).toEqual({ zoom: 2, pan: { x: 5, y: 7 } });
+  });
+
+  it('does not mutate input', () => {
+    const arr = addWorkspace([], instruments, 'Counter');
+    head(arr).config = { step: 99 } as CounterConfig;
+    resetWorkspace(arr, head(arr).id, instruments);
+    expect((arr[0]?.config as CounterConfig).step).toBe(99);
+  });
+});

package/src/workspace/workspaceOps.ts

@@ -0,0 +1,78 @@
+import type { Instrument } from '../instrument/types';
+import type { WorkspaceRecord } from '../state/types';
+
+const DEFAULT_VIEW = { zoom: 1, pan: { x: 0, y: 0 } } as const;
+
+function findInstrument(instruments: Instrument[], name: string): Instrument {
+  const found = instruments.find((i) => i.name === name);
+  if (!found) {
+    throw new Error(`[labkit] Unknown instrument: "${name}"`);
+  }
+  return found;
+}
+
+function initialView(instrument: Instrument): WorkspaceRecord['view'] {
+  return instrument.canvas?.initialView
+    ? structuredClone(instrument.canvas.initialView)
+    : { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
+}
+
+export function addWorkspace(
+  workspaces: WorkspaceRecord[],
+  instruments: Instrument[],
+  instrumentName: string,
+): WorkspaceRecord[] {
+  const instrument = findInstrument(instruments, instrumentName);
+  const config = instrument.defaultConfig();
+  const state = instrument.initialState(config);
+  const record: WorkspaceRecord = {
+    id: crypto.randomUUID(),
+    instrumentName,
+    config,
+    state,
+    view: initialView(instrument),
+    undoStack: { past: [], future: [] },
+  };
+  return [...workspaces, record];
+}
+
+export function cloneWorkspace(workspaces: WorkspaceRecord[], id: string): WorkspaceRecord[] {
+  const sourceIdx = workspaces.findIndex((w) => w.id === id);
+  const source = workspaces[sourceIdx];
+  if (!source) return workspaces;
+  const clone: WorkspaceRecord = {
+    ...source,
+    id: crypto.randomUUID(),
+    config: structuredClone(source.config),
+    state: structuredClone(source.state),
+    view: structuredClone(source.view),
+    undoStack: { past: [], future: [] },
+  };
+  return [...workspaces.slice(0, sourceIdx + 1), clone, ...workspaces.slice(sourceIdx + 1)];
+}
+
+export function closeWorkspace(workspaces: WorkspaceRecord[], id: string): WorkspaceRecord[] {
+  if (workspaces.length <= 1) return workspaces;
+  const next = workspaces.filter((w) => w.id !== id);
+  return next.length === workspaces.length ? workspaces : next;
+}
+
+export function resetWorkspace(
+  workspaces: WorkspaceRecord[],
+  id: string,
+  instruments: Instrument[],
+): WorkspaceRecord[] {
+  const idx = workspaces.findIndex((w) => w.id === id);
+  const current = workspaces[idx];
+  if (!current) return workspaces;
+  const instrument = findInstrument(instruments, current.instrumentName);
+  const config = instrument.defaultConfig();
+  const state = instrument.initialState(config);
+  const reset: WorkspaceRecord = {
+    ...current,
+    config,
+    state,
+    view: initialView(instrument),
+  };
+  return [...workspaces.slice(0, idx), reset, ...workspaces.slice(idx + 1)];
+}