@weasel-js/labkit 0.1.0

package/src/lab/WorkspaceGrid.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { WorkspaceGrid } from './WorkspaceGrid';
+
+const meta: Meta<typeof WorkspaceGrid> = {
+  title: 'labkit/Lab/WorkspaceGrid',
+  component: WorkspaceGrid,
+};
+export default meta;
+
+type Story = StoryObj<typeof WorkspaceGrid>;
+
+const Tile = ({ children }: { children: React.ReactNode }) => (
+  <div
+    style={{
+      background: 'var(--lk-bg-elevated)',
+      border: '1px solid var(--lk-border)',
+      borderRadius: 'var(--lk-radius)',
+      padding: 'var(--lk-spacing-md)',
+      minHeight: 120,
+      display: 'grid',
+      placeItems: 'center',
+    }}
+  >
+    {children}
+  </div>
+);
+
+export const OneTile: Story = {
+  render: () => (
+    <div style={{ height: 400 }}>
+      <WorkspaceGrid>
+        <Tile>1</Tile>
+      </WorkspaceGrid>
+    </div>
+  ),
+};
+
+export const ThreeTiles: Story = {
+  render: () => (
+    <div style={{ height: 400 }}>
+      <WorkspaceGrid>
+        <Tile>1</Tile>
+        <Tile>2</Tile>
+        <Tile>3</Tile>
+      </WorkspaceGrid>
+    </div>
+  ),
+};
+
+export const SevenTiles: Story = {
+  render: () => (
+    <div style={{ height: 600 }}>
+      <WorkspaceGrid>
+        {Array.from({ length: 7 }).map((_, i) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: static demo list
+          <Tile key={i}>{i + 1}</Tile>
+        ))}
+      </WorkspaceGrid>
+    </div>
+  ),
+};

package/src/lab/WorkspaceGrid.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { WorkspaceGrid } from './WorkspaceGrid';
+
+describe('WorkspaceGrid', () => {
+  test('renders all children', () => {
+    render(
+      <WorkspaceGrid>
+        <div>one</div>
+        <div>two</div>
+        <div>three</div>
+      </WorkspaceGrid>,
+    );
+    expect(screen.getByText('one')).toBeInTheDocument();
+    expect(screen.getByText('two')).toBeInTheDocument();
+    expect(screen.getByText('three')).toBeInTheDocument();
+  });
+
+  test('sets CSS custom properties for grid dimensions based on child count', () => {
+    const { container } = render(
+      <WorkspaceGrid>
+        <div>a</div>
+        <div>b</div>
+        <div>c</div>
+      </WorkspaceGrid>,
+    );
+    const grid = container.firstChild as HTMLElement;
+    expect(grid.style.getPropertyValue('--lk-grid-cols')).toBe('2');
+    expect(grid.style.getPropertyValue('--lk-grid-rows')).toBe('2');
+  });
+
+  test('uses lk-workspace-grid class', () => {
+    const { container } = render(
+      <WorkspaceGrid>
+        <div />
+      </WorkspaceGrid>,
+    );
+    expect((container.firstChild as HTMLElement).className).toBe('lk-workspace-grid');
+  });
+});

package/src/lab/WorkspaceGrid.tsx

@@ -0,0 +1,20 @@
+import { Children, type CSSProperties, type ReactNode } from 'react';
+import { gridDims } from './gridDims';
+
+export interface WorkspaceGridProps {
+  children: ReactNode;
+}
+
+export function WorkspaceGrid({ children }: WorkspaceGridProps) {
+  const count = Children.count(children);
+  const { cols, rows } = gridDims(count);
+  const style = {
+    '--lk-grid-cols': String(cols),
+    '--lk-grid-rows': String(rows),
+  } as CSSProperties;
+  return (
+    <div className="lk-workspace-grid" style={style}>
+      {children}
+    </div>
+  );
+}

package/src/lab/gridDims.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'vitest';
+import { gridDims } from './gridDims';
+
+describe('gridDims', () => {
+  test('returns 1x1 for 0 or 1', () => {
+    expect(gridDims(0)).toEqual({ cols: 1, rows: 1 });
+    expect(gridDims(1)).toEqual({ cols: 1, rows: 1 });
+  });
+
+  test('returns 2x1 for 2', () => {
+    expect(gridDims(2)).toEqual({ cols: 2, rows: 1 });
+  });
+
+  test('returns 2x2 for 3 or 4', () => {
+    expect(gridDims(3)).toEqual({ cols: 2, rows: 2 });
+    expect(gridDims(4)).toEqual({ cols: 2, rows: 2 });
+  });
+
+  test('returns 3x2 for 5 or 6', () => {
+    expect(gridDims(5)).toEqual({ cols: 3, rows: 2 });
+    expect(gridDims(6)).toEqual({ cols: 3, rows: 2 });
+  });
+
+  test('returns 3x3 for 9', () => {
+    expect(gridDims(9)).toEqual({ cols: 3, rows: 3 });
+  });
+
+  test('returns 4x4 for 16', () => {
+    expect(gridDims(16)).toEqual({ cols: 4, rows: 4 });
+  });
+
+  test('returns 4x4 for 13 (sqrt rounds up to 4)', () => {
+    expect(gridDims(13)).toEqual({ cols: 4, rows: 4 });
+  });
+});

package/src/lab/gridDims.ts

@@ -0,0 +1,11 @@
+export interface GridDims {
+  cols: number;
+  rows: number;
+}
+
+export function gridDims(count: number): GridDims {
+  if (count <= 1) return { cols: 1, rows: 1 };
+  const cols = Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  return { cols, rows };
+}

package/src/lab/index.ts

@@ -0,0 +1,10 @@
+export type { GridDims } from './gridDims';
+export { gridDims } from './gridDims';
+export type { LabProps } from './Lab';
+export { Lab } from './Lab';
+export type { LabContextValue } from './LabContext';
+export { LabContext, useLabContext } from './LabContext';
+export type { LabShellProps, LabTheme } from './LabShell';
+export { LabShell } from './LabShell';
+export type { WorkspaceGridProps } from './WorkspaceGrid';
+export { WorkspaceGrid } from './WorkspaceGrid';

package/src/layers/AGENTS.md

@@ -0,0 +1,65 @@
+# Layers — Agent Guide
+
+The `src/layers/` directory implements the `<LayerList>` UI used by the `layers` instrument capability.
+
+## Files
+
+| File | Role |
+|---|---|
+| `LayerList.tsx` | Layer toggle/reorder list (sidebar widget) |
+| `LayerList.less` | Row styling, drag handle, pinned-row variant |
+
+## Props
+
+```ts
+interface LayerListProps {
+  layers: LayerDescriptor[];                    // { id, label, alwaysOn? }
+  visibility: Record<string, boolean>;          // missing key → visible
+  onReorder: (newOrder: LayerDescriptor[]) => void;
+  onToggle: (id: string, visible: boolean) => void;
+  className?: string;
+}
+```
+
+`LayerDescriptor` lives in `src/instrument/types.ts`.
+
+## How it integrates
+
+The instrument declares layer ids:
+
+```ts
+layers: { ids: ['grid', 'plants'] }
+```
+
+`Workspace.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
+
+There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the workspace assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
+
+## `alwaysOn` semantics
+
+Setting `alwaysOn: true` on a `LayerDescriptor` does two things:
+
+1. The row renders with a 🔒 badge instead of a drag handle and visibility checkbox.
+2. The row is excluded from reorder operations — pinned rows always sort to the bottom of the rendered list.
+
+This is intended for legend/HUD layers that should never be toggled off. Visibility for pinned rows is **not** read from the `visibility` prop; they always render.
+
+## Drag handle customization
+
+The drag handle is a button with text content `⋮⋮` and class `lk-layer-list__handle`. Its row height is hardcoded to `28px` for delta computation (`moveDrag` in `LayerList.tsx`). If you change row height in CSS, update the `rowHeight` constant to match.
+
+Pointer capture is acquired on `pointerdown` and released on `pointerup`, so dragging works across the document without requiring window-level listeners.
+
+## Empty state
+
+If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Workspace already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
+
+## When to fork
+
+Fork this component if you need:
+- Multi-select reorder (current implementation is single-row)
+- Right-click context menu
+- Layer groups or nesting
+- Solo/mute UI common in DAW-style apps
+
+The implementation is small (~100 lines) and self-contained — only depends on `LayerDescriptor` from instrument types.

package/src/layers/LayerList.less

@@ -0,0 +1,53 @@
+.lk-layer-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: var(--lk-spacing-sm, 8px);
+}
+
+.lk-layer-list__empty {
+  color: var(--lk-color-text-muted, #888);
+  font-size: var(--lk-font-size-sm, 12px);
+  font-style: italic;
+}
+
+.lk-layer-list__row {
+  display: flex;
+  align-items: center;
+  gap: var(--lk-spacing-sm, 8px);
+  padding: 4px 6px;
+  border-radius: 3px;
+  user-select: none;
+}
+
+.lk-layer-list__row:hover {
+  background: var(--lk-color-hover, rgba(0, 0, 0, 0.04));
+}
+
+.lk-layer-list__row--dragging {
+  background: var(--lk-color-active, rgba(0, 0, 0, 0.08));
+  opacity: 0.7;
+}
+
+.lk-layer-list__row--pinned {
+  opacity: 0.7;
+}
+
+.lk-layer-list__handle {
+  cursor: grab;
+  color: var(--lk-color-text-muted, #888);
+  font-family: monospace;
+}
+
+.lk-layer-list__handle:active {
+  cursor: grabbing;
+}
+
+.lk-layer-list__lock {
+  color: var(--lk-color-text-muted, #888);
+}
+
+.lk-layer-list__label {
+  flex: 1;
+  font-size: var(--lk-font-size-sm, 12px);
+}

package/src/layers/LayerList.test.tsx

@@ -0,0 +1,49 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { LayerDescriptor } from '../instrument/types';
+import { LayerList } from './LayerList';
+
+describe('<LayerList>', () => {
+  it('renders one row per layer', () => {
+    const layers: LayerDescriptor[] = [
+      { id: 'a', label: 'A' },
+      { id: 'b', label: 'B' },
+    ];
+    const { container } = render(
+      <LayerList
+        layers={layers}
+        visibility={{ a: true, b: true }}
+        onReorder={vi.fn()}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(container.querySelectorAll('.lk-layer-list__row')).toHaveLength(2);
+  });
+
+  it('renders empty state when no layers', () => {
+    render(<LayerList layers={[]} visibility={{}} onReorder={vi.fn()} onToggle={vi.fn()} />);
+    expect(screen.getByText('No layers')).toBeInTheDocument();
+  });
+
+  it('alwaysOn rows have no checkbox and show lock icon', () => {
+    const layers: LayerDescriptor[] = [{ id: 'a', label: 'A', alwaysOn: true }];
+    render(<LayerList layers={layers} visibility={{}} onReorder={vi.fn()} onToggle={vi.fn()} />);
+    expect(screen.queryByLabelText('Toggle A')).toBeNull();
+    expect(screen.getByLabelText('Always on')).toBeInTheDocument();
+  });
+
+  it('onToggle fires on checkbox click', () => {
+    const onToggle = vi.fn();
+    const layers: LayerDescriptor[] = [{ id: 'a', label: 'A' }];
+    render(
+      <LayerList
+        layers={layers}
+        visibility={{ a: true }}
+        onReorder={vi.fn()}
+        onToggle={onToggle}
+      />,
+    );
+    fireEvent.click(screen.getByLabelText('Toggle A'));
+    expect(onToggle).toHaveBeenCalledWith('a', false);
+  });
+});

package/src/layers/LayerList.tsx

@@ -0,0 +1,105 @@
+import { type PointerEvent, useRef, useState } from 'react';
+import type { LayerDescriptor } from '../instrument/types';
+
+export interface LayerListProps {
+  layers: LayerDescriptor[];
+  visibility: Record<string, boolean>;
+  onReorder: (newOrder: LayerDescriptor[]) => void;
+  onToggle: (id: string, visible: boolean) => void;
+  className?: string;
+}
+
+interface DragState {
+  pointerId: number;
+  fromIndex: number;
+  startY: number;
+}
+
+export function LayerList({ layers, visibility, onReorder, onToggle, className }: LayerListProps) {
+  const reorderable = layers.filter((l) => !l.alwaysOn);
+  const pinned = layers.filter((l) => l.alwaysOn);
+  const [dragIndex, setDragIndex] = useState<number | null>(null);
+  const dragRef = useRef<DragState | null>(null);
+
+  if (layers.length === 0) {
+    return (
+      <div className={className ? `lk-layer-list ${className}` : 'lk-layer-list'}>
+        <div className="lk-layer-list__empty">No layers</div>
+      </div>
+    );
+  }
+
+  const startDrag = (e: PointerEvent<HTMLElement>, index: number) => {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragRef.current = { pointerId: e.pointerId, fromIndex: index, startY: e.clientY };
+    setDragIndex(index);
+  };
+
+  const moveDrag = (e: PointerEvent<HTMLElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== e.pointerId) return;
+    const rowHeight = 28;
+    const delta = Math.round((e.clientY - drag.startY) / rowHeight);
+    const target = Math.min(reorderable.length - 1, Math.max(0, drag.fromIndex + delta));
+    setDragIndex(target);
+  };
+
+  const endDrag = (e: PointerEvent<HTMLElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== e.pointerId) return;
+    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+    if (dragIndex !== null && dragIndex !== drag.fromIndex) {
+      const next = [...reorderable];
+      const [moved] = next.splice(drag.fromIndex, 1);
+      if (moved) next.splice(dragIndex, 0, moved);
+      onReorder([...next, ...pinned]);
+    }
+    dragRef.current = null;
+    setDragIndex(null);
+  };
+
+  return (
+    <div className={className ? `lk-layer-list ${className}` : 'lk-layer-list'}>
+      {reorderable.map((layer, i) => {
+        const isDragging = dragIndex === i;
+        return (
+          <div
+            key={layer.id}
+            className={
+              isDragging ? 'lk-layer-list__row lk-layer-list__row--dragging' : 'lk-layer-list__row'
+            }
+          >
+            <button
+              type="button"
+              className="lk-layer-list__handle"
+              aria-label={`Reorder ${layer.label}`}
+              onPointerDown={(e) => startDrag(e, i)}
+              onPointerMove={moveDrag}
+              onPointerUp={endDrag}
+            >
+              ⋮⋮
+            </button>
+            <input
+              className="lk-layer-list__check"
+              type="checkbox"
+              checked={visibility[layer.id] !== false}
+              onChange={(e) => onToggle(layer.id, e.target.checked)}
+              aria-label={`Toggle ${layer.label}`}
+            />
+            <span className="lk-layer-list__label">{layer.label}</span>
+          </div>
+        );
+      })}
+      {pinned.map((layer) => (
+        <div key={layer.id} className="lk-layer-list__row lk-layer-list__row--pinned">
+          <span className="lk-layer-list__lock" role="img" aria-label="Always on">
+            🔒
+          </span>
+          <span className="lk-layer-list__label">{layer.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/layers/index.ts

@@ -0,0 +1,3 @@
+export type { LayerCapability, LayerDescriptor } from '../instrument/types';
+export type { LayerListProps } from './LayerList';
+export { LayerList } from './LayerList';

package/src/passthrough/weasel-canvas.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildSceneViewCommands,
+  computeFitView,
+  computeIndicatorCommand,
+  FALLBACK_FIT_VIEW,
+  MinimapCanvas,
+  renderSceneToCanvas,
+  SceneViewCanvas,
+} from './weasel-canvas';
+
+describe('weasel-canvas passthrough', () => {
+  it('re-exports detached-view components', () => {
+    for (const C of [SceneViewCanvas, MinimapCanvas]) {
+      expect(C).toBeDefined();
+      expect(['function', 'object']).toContain(typeof C);
+    }
+  });
+
+  it('re-exports scene-render helpers', () => {
+    expect(typeof buildSceneViewCommands).toBe('function');
+    expect(typeof renderSceneToCanvas).toBe('function');
+  });
+
+  it('re-exports minimap math helpers and the fit-view fallback', () => {
+    expect(typeof computeFitView).toBe('function');
+    expect(typeof computeIndicatorCommand).toBe('function');
+    expect(FALLBACK_FIT_VIEW).toBeDefined();
+  });
+});

package/src/passthrough/weasel-canvas.ts

@@ -0,0 +1,23 @@
+/**
+ * Re-exports of detached scene-view + minimap primitives from
+ * `@weasel-js/core` so consumers reach them through
+ * `@weasel-js/labkit/weasel-canvas` rather than depending on the weasel
+ * canvas package directly. This passthrough is narrow on purpose —
+ * weasel's full surface is engine-sized, and we only widen as labs
+ * demand it.
+ */
+export {
+  buildSceneViewCommands,
+  type ComputeFitViewOptions,
+  computeFitView,
+  computeIndicatorCommand,
+  FALLBACK_FIT_VIEW,
+  type IndicatorStyle,
+  MinimapCanvas,
+  type MinimapCanvasProps,
+  type MinimapFit,
+  renderSceneToCanvas,
+  SceneViewCanvas,
+  type SceneViewCanvasProps,
+  type SceneViewDrawOne,
+} from '@weasel-js/core';

package/src/passthrough/weasel-ui.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import {
+  Button,
+  Checkbox,
+  ComboBox,
+  CurveEditor,
+  chromaAt,
+  Dialog,
+  Field,
+  formatNumber,
+  Input,
+  KeyCap,
+  MINUS_SIGN,
+  NumberField,
+  oklchToHex,
+  Plot2D,
+  PointPlotter,
+  paintGradientTrack,
+  RadioGroup,
+  RangeSlider,
+  Select,
+  Sidebar,
+  Slider,
+  Switch,
+  Tabs,
+  ToolPalette,
+  useReorderDragList,
+} from './weasel-ui';
+
+describe('weasel-ui passthrough', () => {
+  it('re-exports formatNumber with MINUS_SIGN convention', () => {
+    expect(formatNumber(-3.14)).toBe(`${MINUS_SIGN}3.14`);
+  });
+
+  it('re-exports utility functions', () => {
+    expect(typeof useReorderDragList).toBe('function');
+    expect(typeof paintGradientTrack).toBe('function');
+    expect(typeof oklchToHex).toBe('function');
+    expect(typeof chromaAt).toBe('function');
+  });
+
+  it('re-exports form primitives as React components', () => {
+    for (const C of [
+      Button,
+      Checkbox,
+      ComboBox,
+      Dialog,
+      Field,
+      Input,
+      NumberField,
+      RadioGroup,
+      RangeSlider,
+      Select,
+      Slider,
+      Switch,
+      Tabs,
+    ]) {
+      expect(C).toBeDefined();
+      // React components are either plain functions or forwardRef/memo objects
+      expect(['function', 'object']).toContain(typeof C);
+    }
+  });
+
+  it('re-exports plot / curve primitives as React components', () => {
+    for (const C of [CurveEditor, Plot2D, PointPlotter]) {
+      expect(C).toBeDefined();
+      // React components are either plain functions or forwardRef/memo objects
+      expect(['function', 'object']).toContain(typeof C);
+    }
+  });
+
+  it('re-exports app-chrome primitives as React components', () => {
+    for (const C of [Sidebar, ToolPalette, KeyCap]) {
+      expect(C).toBeDefined();
+      // React components are either plain functions or forwardRef/memo objects
+      expect(['function', 'object']).toContain(typeof C);
+    }
+  });
+});