@weasel-js/labkit 0.1.0

package/src/primitives/Toolbar.less

@@ -0,0 +1,43 @@
+.lk-toolbar {
+  display: flex;
+  align-items: center;
+  gap: var(--lk-spacing-sm);
+  padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+  background: var(--lk-bg-elevated);
+  border-bottom: 1px solid var(--lk-border);
+  min-height: calc(var(--lk-control-height) + 2 * var(--lk-spacing-xs));
+}
+
+.lk-toolbar-title {
+  font-weight: 600;
+  color: var(--lk-text);
+  margin-right: var(--lk-spacing-sm);
+}
+
+.lk-toolbar-spacer {
+  flex: 1;
+}
+
+.lk-toolbar-button {
+  height: var(--lk-control-height);
+  padding: 0 var(--lk-spacing-sm);
+  font-size: var(--lk-font-size);
+  color: var(--lk-text);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--lk-radius);
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: var(--lk-bg);
+    border-color: var(--lk-border);
+  }
+  &:focus-visible {
+    outline: 2px solid var(--lk-focus-ring);
+    outline-offset: 1px;
+  }
+  &:disabled {
+    color: var(--lk-text-disabled);
+    cursor: not-allowed;
+  }
+}

package/src/primitives/Toolbar.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Toolbar } from './Toolbar';
+
+const meta: Meta<typeof Toolbar> = {
+  title: 'labkit/Primitives/Toolbar',
+  component: Toolbar,
+};
+export default meta;
+
+type Story = StoryObj<typeof Toolbar>;
+
+export const Default: Story = {
+  render: () => (
+    <Toolbar>
+      <Toolbar.Title>My Workspace</Toolbar.Title>
+      <Toolbar.Button onClick={() => {}}>Undo</Toolbar.Button>
+      <Toolbar.Button onClick={() => {}}>Redo</Toolbar.Button>
+      <Toolbar.Spacer />
+      <Toolbar.Button onClick={() => {}}>Save</Toolbar.Button>
+    </Toolbar>
+  ),
+};
+
+export const WithDisabled: Story = {
+  render: () => (
+    <Toolbar>
+      <Toolbar.Title>Empty workspace</Toolbar.Title>
+      <Toolbar.Button onClick={() => {}} disabled>
+        Undo
+      </Toolbar.Button>
+      <Toolbar.Button onClick={() => {}} disabled>
+        Redo
+      </Toolbar.Button>
+    </Toolbar>
+  ),
+};

package/src/primitives/Toolbar.test.tsx

@@ -0,0 +1,65 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { Toolbar } from './Toolbar';
+
+describe('Toolbar', () => {
+  test('renders children in a horizontal toolbar', () => {
+    const { container } = render(
+      <Toolbar>
+        <Toolbar.Title>My Lab</Toolbar.Title>
+        <Toolbar.Button onClick={() => {}}>Save</Toolbar.Button>
+      </Toolbar>,
+    );
+    expect(screen.getByText('My Lab')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument();
+    expect((container.firstChild as HTMLElement).className).toBe('lk-toolbar');
+  });
+
+  test('Title uses lk-toolbar-title class', () => {
+    const { container } = render(
+      <Toolbar>
+        <Toolbar.Title>X</Toolbar.Title>
+      </Toolbar>,
+    );
+    expect(container.querySelector('.lk-toolbar-title')).not.toBeNull();
+  });
+
+  test('Spacer fills available space', () => {
+    const { container } = render(
+      <Toolbar>
+        <Toolbar.Title>L</Toolbar.Title>
+        <Toolbar.Spacer />
+        <span>R</span>
+      </Toolbar>,
+    );
+    expect(container.querySelector('.lk-toolbar-spacer')).not.toBeNull();
+  });
+
+  test('Button passes onClick and disabled', () => {
+    let clicked = false;
+    render(
+      <Toolbar>
+        <Toolbar.Button
+          onClick={() => {
+            clicked = true;
+          }}
+        >
+          Go
+        </Toolbar.Button>
+      </Toolbar>,
+    );
+    screen.getByRole('button', { name: 'Go' }).click();
+    expect(clicked).toBe(true);
+  });
+
+  test('Button respects disabled', () => {
+    render(
+      <Toolbar>
+        <Toolbar.Button onClick={() => {}} disabled>
+          X
+        </Toolbar.Button>
+      </Toolbar>,
+    );
+    expect(screen.getByRole('button', { name: 'X' })).toBeDisabled();
+  });
+});

package/src/primitives/Toolbar.tsx

@@ -0,0 +1,44 @@
+import type { MouseEventHandler, ReactNode } from 'react';
+
+export interface ToolbarProps {
+  children: ReactNode;
+}
+
+export function Toolbar({ children }: ToolbarProps) {
+  return <div className="lk-toolbar">{children}</div>;
+}
+
+interface TitleProps {
+  children: ReactNode;
+}
+function Title({ children }: TitleProps) {
+  return <span className="lk-toolbar-title">{children}</span>;
+}
+
+interface ButtonProps {
+  children: ReactNode;
+  onClick: MouseEventHandler<HTMLButtonElement>;
+  disabled?: boolean;
+  title?: string;
+}
+function Button({ children, onClick, disabled, title }: ButtonProps) {
+  return (
+    <button
+      type="button"
+      className="lk-toolbar-button"
+      onClick={onClick}
+      disabled={disabled}
+      title={title}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Spacer() {
+  return <span className="lk-toolbar-spacer" aria-hidden="true" />;
+}
+
+Toolbar.Title = Title;
+Toolbar.Button = Button;
+Toolbar.Spacer = Spacer;

package/src/primitives/fpsAverage.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from 'vitest';
+import { rollingAverage } from './fpsAverage';
+
+describe('rollingAverage', () => {
+  test('returns the input when only one sample', () => {
+    expect(rollingAverage([60])).toBe(60);
+  });
+
+  test('averages multiple samples', () => {
+    expect(rollingAverage([30, 60, 90])).toBe(60);
+  });
+
+  test('returns 0 for empty array', () => {
+    expect(rollingAverage([])).toBe(0);
+  });
+
+  test('rounds to nearest integer', () => {
+    expect(rollingAverage([59, 60, 61])).toBe(60);
+    expect(rollingAverage([58, 59, 61])).toBe(59);
+  });
+});

package/src/primitives/fpsAverage.ts

@@ -0,0 +1,5 @@
+export function rollingAverage(samples: readonly number[]): number {
+  if (samples.length === 0) return 0;
+  const sum = samples.reduce((acc, n) => acc + n, 0);
+  return Math.round(sum / samples.length);
+}

package/src/primitives/index.ts

@@ -0,0 +1,9 @@
+export { FpsMeter } from './FpsMeter';
+export type { ScaleIndicatorProps } from './ScaleIndicator';
+export { ScaleIndicator } from './ScaleIndicator';
+export type { SidebarProps } from './Sidebar';
+export { Sidebar } from './Sidebar';
+export type { StatusBarProps } from './StatusBar';
+export { StatusBar } from './StatusBar';
+export type { ToolbarProps } from './Toolbar';
+export { Toolbar } from './Toolbar';

package/src/state/SingletonExperiment.test.tsx

@@ -0,0 +1,101 @@
+import { act, render, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createMemoryAdapter } from './adapters';
+import { SingletonExperimentProvider } from './SingletonExperiment';
+import { useExperimentState } from './useExperimentState';
+
+interface Config {
+  width: number;
+  bg: string;
+}
+interface State {
+  zoom: number;
+}
+
+describe('SingletonExperimentProvider', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('exposes config and state via useExperimentState', () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <SingletonExperimentProvider<State, Config>
+        id="test"
+        initialConfig={{ width: 100, bg: '#000' }}
+        initialState={{ zoom: 1 }}
+        storage={createMemoryAdapter()}
+        storageKey="test"
+      >
+        {children}
+      </SingletonExperimentProvider>
+    );
+    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    expect(result.current.config).toEqual({ width: 100, bg: '#000' });
+    expect(result.current.state).toEqual({ zoom: 1 });
+  });
+
+  it('persists config changes to storage', () => {
+    vi.useFakeTimers();
+    const storage = createMemoryAdapter();
+    const Probe = () => {
+      const h = useExperimentState<State, Config>();
+      return (
+        <button type="button" onClick={() => h.setConfig('width', 200)}>
+          go
+        </button>
+      );
+    };
+    const { getByText } = render(
+      <SingletonExperimentProvider<State, Config>
+        id="test"
+        initialConfig={{ width: 100, bg: '#000' }}
+        initialState={{ zoom: 1 }}
+        storage={storage}
+        storageKey="test"
+      >
+        <Probe />
+      </SingletonExperimentProvider>,
+    );
+    act(() => {
+      getByText('go').click();
+    });
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    // createLabStore uses labStorageKey which prefixes with "lk:"
+    const raw = storage.read('lk:test:workspaces');
+    expect(raw).toBeTruthy();
+    expect(raw).toContain('"width":200');
+  });
+
+  it('rehydrates from storage on mount', () => {
+    const storage = createMemoryAdapter();
+    // createLabStore uses labStorageKey which prefixes with "lk:"
+    storage.write(
+      'lk:test:workspaces',
+      JSON.stringify([
+        {
+          id: 'test',
+          instrumentName: '__singleton__',
+          config: { width: 999, bg: '#fff' },
+          state: { zoom: 2 },
+          view: { zoom: 1, pan: { x: 0, y: 0 } },
+        },
+      ]),
+    );
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <SingletonExperimentProvider<State, Config>
+        id="test"
+        initialConfig={{ width: 100, bg: '#000' }}
+        initialState={{ zoom: 1 }}
+        storage={storage}
+        storageKey="test"
+      >
+        {children}
+      </SingletonExperimentProvider>
+    );
+    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    expect(result.current.config).toEqual({ width: 999, bg: '#fff' });
+    expect(result.current.state).toEqual({ zoom: 2 });
+  });
+});

package/src/state/SingletonExperiment.tsx

@@ -0,0 +1,52 @@
+import { type ReactNode, useRef } from 'react';
+import { LabStoreProvider, WorkspaceIdProvider } from './context';
+import { createLabStore, type LabStore } from './store';
+import type { StorageAdapter } from './types';
+
+const SINGLETON_INSTRUMENT = '__singleton__';
+
+export interface SingletonExperimentProviderProps<TS, TC> {
+  /** Stable id for the synthetic workspace; also doubles as the
+   *  WorkspaceIdContext value. */
+  id: string;
+  initialConfig: TC;
+  initialState: TS;
+  storage: StorageAdapter;
+  storageKey: string;
+  children: ReactNode;
+}
+
+/**
+ * One-workspace `<Lab>` substitute for single-screen experiments. Mounts
+ * a `LabStoreProvider` + `WorkspaceIdProvider` with one synthetic
+ * workspace, so `useExperimentState` works without going through the
+ * full `<Lab instruments={...}>` runtime.
+ */
+export function SingletonExperimentProvider<TS, TC>({
+  id,
+  initialConfig,
+  initialState,
+  storage,
+  storageKey,
+  children,
+}: SingletonExperimentProviderProps<TS, TC>) {
+  const storeRef = useRef<LabStore | null>(null);
+  if (storeRef.current === null) {
+    const store = createLabStore({ storageKey, storage });
+    if (!store.getState().workspaces.some((w) => w.id === id)) {
+      store.getState().addWorkspace({
+        id,
+        instrumentName: SINGLETON_INSTRUMENT,
+        config: initialConfig,
+        state: initialState,
+        view: { zoom: 1, pan: { x: 0, y: 0 } },
+      });
+    }
+    storeRef.current = store;
+  }
+  return (
+    <LabStoreProvider store={storeRef.current}>
+      <WorkspaceIdProvider workspaceId={id}>{children}</WorkspaceIdProvider>
+    </LabStoreProvider>
+  );
+}

package/src/state/adapters.test.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  createMemoryAdapter,
+  localStorageAdapter,
+  noneAdapter,
+  sessionStorageAdapter,
+  urlHashAdapter,
+} from './adapters';
+
+describe('localStorageAdapter', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('writes and reads a value', () => {
+    localStorageAdapter.write('k', 'v');
+    expect(localStorageAdapter.read('k')).toBe('v');
+  });
+
+  it('returns null for missing key', () => {
+    expect(localStorageAdapter.read('missing')).toBeNull();
+  });
+
+  it('deletes a key', () => {
+    localStorageAdapter.write('k', 'v');
+    localStorageAdapter.delete?.('k');
+    expect(localStorageAdapter.read('k')).toBeNull();
+  });
+
+  it('handles QuotaExceededError gracefully', () => {
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementationOnce(() => {
+      throw new DOMException('QuotaExceeded', 'QuotaExceededError');
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(() => localStorageAdapter.write('k', 'v')).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('sessionStorageAdapter', () => {
+  beforeEach(() => sessionStorage.clear());
+
+  it('writes and reads a value', () => {
+    sessionStorageAdapter.write('k', 'v');
+    expect(sessionStorageAdapter.read('k')).toBe('v');
+  });
+});
+
+describe('urlHashAdapter', () => {
+  beforeEach(() => {
+    window.location.hash = '';
+  });
+
+  it('writes and reads back through the hash', () => {
+    urlHashAdapter.write('any-key', 'hello world');
+    expect(urlHashAdapter.read('any-key')).toBe('hello world');
+  });
+
+  it('returns null when hash is empty', () => {
+    expect(urlHashAdapter.read('any-key')).toBeNull();
+  });
+
+  it('uses replaceState (not pushState)', () => {
+    const spy = vi.spyOn(window.history, 'replaceState');
+    urlHashAdapter.write('k', 'v');
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('createMemoryAdapter', () => {
+  it('two instances are isolated', () => {
+    const a = createMemoryAdapter();
+    const b = createMemoryAdapter();
+    a.write('k', 'from-a');
+    expect(b.read('k')).toBeNull();
+  });
+
+  it('delete removes the key', () => {
+    const m = createMemoryAdapter();
+    m.write('k', 'v');
+    m.delete?.('k');
+    expect(m.read('k')).toBeNull();
+  });
+});
+
+describe('noneAdapter', () => {
+  it('read always returns null', () => {
+    expect(noneAdapter.read('anything')).toBeNull();
+  });
+
+  it('write is a no-op', () => {
+    expect(() => noneAdapter.write('k', 'v')).not.toThrow();
+  });
+});

package/src/state/adapters.ts

@@ -0,0 +1,102 @@
+import { decodeUrlHash, encodeUrlHash } from './helpers';
+import type { StorageAdapter } from './types';
+
+export const localStorageAdapter: StorageAdapter = {
+  read: (key) => {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  write: (key, value) => {
+    try {
+      localStorage.setItem(key, value);
+    } catch (e) {
+      console.warn('[labkit] localStorage write failed:', e);
+    }
+  },
+  delete: (key) => {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      /* ignore */
+    }
+  },
+};
+
+export const sessionStorageAdapter: StorageAdapter = {
+  read: (key) => {
+    try {
+      return sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  write: (key, value) => {
+    try {
+      sessionStorage.setItem(key, value);
+    } catch (e) {
+      console.warn('[labkit] sessionStorage write failed:', e);
+    }
+  },
+  delete: (key) => {
+    try {
+      sessionStorage.removeItem(key);
+    } catch {
+      /* ignore */
+    }
+  },
+};
+
+const URL_HASH_GUARD = typeof window !== 'undefined';
+
+function readHashMap(): Record<string, string> {
+  if (!URL_HASH_GUARD) return {};
+  const raw = decodeUrlHash(window.location.hash.replace(/^#/, ''));
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+function writeHashMap(map: Record<string, string>): void {
+  if (!URL_HASH_GUARD) return;
+  const encoded = encodeUrlHash(JSON.stringify(map));
+  window.history.replaceState(null, '', `#${encoded}`);
+}
+
+export const urlHashAdapter: StorageAdapter = {
+  read: (key) => readHashMap()[key] ?? null,
+  write: (key, value) => {
+    const map = readHashMap();
+    map[key] = value;
+    writeHashMap(map);
+  },
+  delete: (key) => {
+    const map = readHashMap();
+    delete map[key];
+    writeHashMap(map);
+  },
+};
+
+export function createMemoryAdapter(): StorageAdapter {
+  const store = new Map<string, string>();
+  return {
+    read: (key) => store.get(key) ?? null,
+    write: (key, value) => {
+      store.set(key, value);
+    },
+    delete: (key) => {
+      store.delete(key);
+    },
+  };
+}
+
+export const noneAdapter: StorageAdapter = {
+  read: () => null,
+  write: () => {},
+  delete: () => {},
+};

package/src/state/context.tsx

@@ -0,0 +1,42 @@
+import { createContext, type ReactElement, type ReactNode, useContext } from 'react';
+import { useStore } from 'zustand/react';
+import type { LabStore } from './store';
+import type { LabStoreState } from './types';
+
+type LabStoreCtx = { store: LabStore } | null;
+
+export const LabStoreContext = createContext<LabStoreCtx>(null);
+
+export function LabStoreProvider({
+  store,
+  children,
+}: {
+  store: LabStore;
+  children: ReactNode;
+}): ReactElement {
+  return <LabStoreContext.Provider value={{ store }}>{children}</LabStoreContext.Provider>;
+}
+
+export function useLabStore(): LabStoreState & ReturnType<LabStore['getState']> {
+  const ctx = useContext(LabStoreContext);
+  if (!ctx) throw new Error('[labkit] useLabStore must be used inside <LabStoreProvider>');
+  return useStore(ctx.store);
+}
+
+export const WorkspaceIdContext = createContext<string | null>(null);
+
+export function WorkspaceIdProvider({
+  workspaceId,
+  children,
+}: {
+  workspaceId: string;
+  children: ReactNode;
+}): ReactElement {
+  return <WorkspaceIdContext.Provider value={workspaceId}>{children}</WorkspaceIdContext.Provider>;
+}
+
+export function useWorkspaceId(): string {
+  const id = useContext(WorkspaceIdContext);
+  if (!id) throw new Error('[labkit] useWorkspaceId must be used inside <WorkspaceIdProvider>');
+  return id;
+}