@weasel-js/labkit 0.1.0

package/dist/theme-interstellar.css

@@ -0,0 +1,25 @@
+.lk-theme-interstellar {
+  --lk-bg: #0a0a14;
+  --lk-bg-elevated: rgba(20, 20, 36, 0.55);
+  --lk-bg-canvas: #02020a;
+  --lk-border: rgba(255, 255, 255, 0.14);
+  --lk-divider: rgba(255, 255, 255, 0.08);
+  --lk-glass-blur: 12px;
+  --lk-text: #e8e8f0;
+  --lk-text-muted: #a8a8c0;
+  --lk-text-disabled: #5a5a78;
+  --lk-accent: #b08adb;
+  --lk-accent-hover: #c6a3ee;
+  --lk-focus-ring: rgba(176, 138, 219, 0.45);
+  --lk-swatch-green: #2fdd18;
+  --lk-swatch-pink: #ff5885;
+  --lk-swatch-cyan: #00dfff;
+  --lk-swatch-gold: #dcb700;
+  --lk-swatch-amber: #ff8c00;
+  --lk-swatch-violet: #a497ff;
+  --lk-swatch-mint: #00e7af;
+  --lk-swatch-sky: #00b8ff;
+  --lk-swatch-orange: #ff6b00;
+  --lk-swatch-magenta: #ff6eff;
+  --lk-space-nebula: radial-gradient(ellipse 60% 80% at 18% 30%, rgba(150, 80, 200, 0.22), transparent 70%), radial-gradient(ellipse 55% 90% at 78% 70%, rgba(220, 100, 140, 0.18), transparent 65%), radial-gradient(ellipse 50% 70% at 50% 50%, rgba(60, 110, 200, 0.18), transparent 75%), radial-gradient(ellipse at center, #0a0a18 0%, #02020a 100%);
+}

package/dist/theme-light.css

@@ -0,0 +1,13 @@
+.lk-theme-light {
+  --lk-bg: #fafaf7;
+  --lk-bg-elevated: #ffffff;
+  --lk-bg-canvas: #f0ebe2;
+  --lk-border: #c9bba5;
+  --lk-divider: rgba(0, 0, 0, 0.08);
+  --lk-text: #2a2018;
+  --lk-text-muted: #6b5c4a;
+  --lk-text-disabled: #a89b85;
+  --lk-accent: #a86f3c;
+  --lk-accent-hover: #c2854f;
+  --lk-focus-ring: rgba(168, 111, 60, 0.35);
+}

package/dist/ui/layers/index.d.ts

@@ -0,0 +1,42 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface LayerStackItem {
+    /** Stable id used for keys, onRemove, onReorder. Numeric to match
+     *  common id-from-nextId conventions; string ids also work. */
+    id: number | string;
+    /** Short kind label rendered in the header when no primary select
+     *  is hoisted (e.g. "shadow", "stroke"). */
+    kind: string;
+    /** When present, hoist this select into the card header so the user
+     *  can switch mode/shape without expanding. */
+    primaryValue?: string;
+    primaryOptions?: string[];
+    /** Accent CSS color used as the left border / index-badge fill. */
+    accent?: string;
+    /** Optional badge text rendered before the primary control
+     *  (e.g. tail index "1", "2", "3"). When omitted a drag handle
+     *  glyph renders in its place. */
+    badge?: string;
+    /** Initial expanded state. Defaults to true for newly-added items. */
+    defaultExpanded?: boolean;
+}
+interface LayerStackProps {
+    title: string;
+    items: LayerStackItem[];
+    /** Kinds the user can add via the header palette. */
+    paletteKinds: string[];
+    onAdd: (kind: string) => void;
+    onRemove: (id: number | string) => void;
+    onReorder: (orderedIds: Array<number | string>) => void;
+    onPrimaryChange: (id: number | string, nextValue: string) => void;
+    /** Render the body controls for each item. */
+    renderBody: (item: LayerStackItem) => ReactNode;
+    /** Hide the title + palette row (used when an outer wrap renders its
+     *  own head — see speech-balloons Tails panel). */
+    hideHead?: boolean;
+}
+declare function LayerStack({ title, items, paletteKinds, onAdd, onRemove, onReorder, onPrimaryChange, renderBody, hideHead, }: LayerStackProps): react_jsx_runtime.JSX.Element;
+
+export { LayerStack };
+export type { LayerStackItem, LayerStackProps };

package/dist/ui/layers/index.js

@@ -0,0 +1,5 @@
+export { LayerStack } from '../../chunk-SD3HDXR7.js';
+import '../../chunk-6FO7G5BB.js';
+import '../../chunk-B5ZUYRKN.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/ui/layers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/undo/index.d.ts

@@ -0,0 +1,30 @@
+export { U as UndoCapability } from '../_dts/index-C6Yze7sQ.js';
+import 'react';
+import '../_dts/types-Si4Fw-1F.js';
+
+type EventListener = () => void;
+interface EventBus {
+    on(event: string, listener: EventListener): () => void;
+    emit(event: string): void;
+    clear(): void;
+}
+declare function createEventBus(): EventBus;
+
+interface UndoStack {
+    past: unknown[];
+    future: unknown[];
+}
+declare function emptyStack(): UndoStack;
+declare function pushSnapshot(stack: UndoStack, snapshot: unknown, maxDepth: number): UndoStack;
+declare function undo(stack: UndoStack, current: unknown): {
+    stack: UndoStack;
+    snapshot: unknown;
+} | null;
+declare function redo(stack: UndoStack, current: unknown): {
+    stack: UndoStack;
+    snapshot: unknown;
+} | null;
+declare function clearUndo(_stack: UndoStack): UndoStack;
+
+export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo };
+export type { EventBus, EventListener, UndoStack };

package/dist/undo/index.js

@@ -0,0 +1,3 @@
+export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from '../chunk-7BKDG73Z.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/undo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@weasel-js/labkit",
+  "version": "0.1.0",
+  "description": "React widgets for building self-contained interactive lab pages",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives/index.js"
+    },
+    "./controls": {
+      "types": "./dist/controls/index.d.ts",
+      "import": "./dist/controls/index.js"
+    },
+    "./canvas": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.js"
+    },
+    "./layers": {
+      "types": "./dist/layers/index.d.ts",
+      "import": "./dist/layers/index.js"
+    },
+    "./undo": {
+      "types": "./dist/undo/index.d.ts",
+      "import": "./dist/undo/index.js"
+    },
+    "./dragdrop": {
+      "types": "./dist/dragdrop/index.d.ts",
+      "import": "./dist/dragdrop/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./weasel-ui": {
+      "types": "./dist/passthrough/weasel-ui.d.ts",
+      "import": "./dist/passthrough/weasel-ui.js"
+    },
+    "./weasel-canvas": {
+      "types": "./dist/passthrough/weasel-canvas.d.ts",
+      "import": "./dist/passthrough/weasel-canvas.js"
+    },
+    "./ui/layers": {
+      "types": "./dist/ui/layers/index.d.ts",
+      "import": "./dist/ui/layers/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./theme-light.css": "./dist/theme-light.css",
+    "./theme-interstellar.css": "./dist/theme-interstellar.css"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "earcut": "2.2.4",
+    "polygon-clipping": "^0.15.7",
+    "react-aria-components": "^1.5.0",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.12",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "@weasel-js/modes": "*",
+    "@weasel-js/ui": "*",
+    "less": "^4.2.0",
+    "rollup-plugin-dts": "^6.4.1",
+    "tsx": "^4.19.0",
+    "vitepress": "^1.6.4"
+  },
+  "scripts": {
+    "dev": "vite",
+    "dev:drag": "LABKIT_EXAMPLE=drag-lab vite",
+    "dev:weasel": "LABKIT_EXAMPLE=weasel-lab vite",
+    "build": "tsup && npm run build:dts && npm run build:css && npm run build:fonts",
+    "build:dts": "tsx scripts/build-dts.mts",
+    "build:css": "lessc src/styles.less dist/styles.css && lessc src/theme/light.less dist/theme-light.css && lessc src/theme/interstellar.less dist/theme-interstellar.css",
+    "build:fonts": "mkdir -p dist/fonts && cp src/fonts/*.woff2 dist/fonts/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke:consumer": "node scripts/smoke-consumer-bundle.mjs",
+    "lint": "biome check . && tsx scripts/check-class-prefix.ts",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}

package/src/canvas/AGENTS.md

@@ -0,0 +1,72 @@
+# Canvas — Agent Guide
+
+The `src/canvas/` directory implements the layered canvas primitive used by the `canvas` instrument capability.
+
+## Files
+
+| File | Role |
+|---|---|
+| `CanvasStack.tsx` | Layered `<canvas>` container; owns sizing, pan/zoom handlers, and per-layer canvas refs |
+| `CanvasStackContext.ts` | React context exposing the current `view` to descendants |
+| `useLayerScheduler.ts` | DPR-aware rAF scheduler; redraws dirty layers on view/state changes |
+| `usePanZoom.ts` | Pointer + wheel handlers that mutate `view` via `onViewChange` |
+| `canvasCoords.ts` | Pure `screenToWorld` / `worldToScreen` helpers |
+| `CanvasStack.less` | Container + canvas + overlay positioning |
+
+## Props (`<CanvasStack>`)
+
+```ts
+interface CanvasStackProps {
+  layers: CanvasLayerDescriptor[];      // { id, visible, render(ctx, view) }
+  view: ViewTransform;                  // { zoom, pan: { x, y } }
+  onViewChange: (v: ViewTransform) => void;
+  width?: number | string;              // default '100%'
+  height?: number | string;             // default '100%'
+  className?: string;
+  onHitTest?: (worldPos: Point) => void;  // fired on tap (no drag)
+  children?: ReactNode;                 // rendered into the overlay layer
+}
+```
+
+## How rendering works
+
+1. The container measures itself with `ResizeObserver` and reports `{width, height, dpr}`.
+2. `useLayerScheduler` watches `layers`, `view`, and `size`, and on any change schedules a single `requestAnimationFrame` redraw.
+3. Each layer's `render(ctx, view)` is called with a fresh transform: the canvas is sized to `width * dpr × height * dpr` so coordinates are in CSS pixels.
+4. Layers with `visible: false` are skipped and their canvas is `display: none` (DOM is preserved to avoid remounts).
+
+## Adding a new layer type
+
+A layer is defined by the instrument's `canvas.layers[]` (type `CanvasLayer`), then translated to a `CanvasLayerDescriptor` inside `Workspace.tsx` before being passed to `<CanvasStack>`. To add a layer, push it into `instrument.canvas.layers`:
+
+```ts
+canvas: {
+  layers: [
+    {
+      id: 'grid',
+      draw: (ctx, { state, config, zoom }) => { /* ... */ },
+    },
+  ],
+}
+```
+
+Layer order in the array = paint order (first drawn = bottom).
+
+## Overlay (children)
+
+The `children` prop renders in `.lk-canvas-stack__overlay`, which is `position: absolute; inset: 0; pointer-events: none`. Direct children re-enable pointer events. Use this for HUDs, scale indicators, or interactive overlays that don't belong in a canvas layer.
+
+## Coordinate conversions
+
+- `screenToWorld({x, y}, view)` → world coords given a CSS-pixel offset relative to the container's top-left
+- `worldToScreen({x, y}, view)` → inverse
+
+Both are pure. Pan is applied in screen space; zoom multiplies world coordinates.
+
+## Pan/zoom behavior
+
+Implemented in `usePanZoom`. Mouse-wheel zoom is anchored at the cursor; primary-button drag pans. `isDragging()` is exposed so consumers can suppress click handlers during a pan.
+
+## Testing notes
+
+JSDOM does not provide a real `CanvasRenderingContext2D`. Tests in `CanvasStack.test.tsx` rely on the scheduler's defensive checks; they do not assert pixels. For pixel testing, use Storybook's `chromatic` or visual snapshots in a real browser.

package/src/canvas/CanvasStack.less

@@ -0,0 +1,22 @@
+.lk-canvas-stack {
+  position: relative;
+  overflow: hidden;
+  background: var(--lk-color-canvas-bg, #f6f6f6);
+  touch-action: none;
+}
+
+.lk-canvas-stack__canvas {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
+.lk-canvas-stack__overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.lk-canvas-stack__overlay > * {
+  pointer-events: auto;
+}

package/src/canvas/CanvasStack.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { ScaleIndicator } from '../primitives/ScaleIndicator';
+import { CanvasStack } from './CanvasStack';
+import type { CanvasLayerDescriptor } from './useLayerScheduler';
+
+const meta: Meta<typeof CanvasStack> = {
+  title: 'labkit/Canvas/CanvasStack',
+  component: CanvasStack,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof CanvasStack>;
+
+function makeColoredLayer(id: string, color: string, x: number, y: number): CanvasLayerDescriptor {
+  return {
+    id,
+    visible: true,
+    render: (ctx, view) => {
+      ctx.fillStyle = color;
+      ctx.fillRect(
+        x * view.zoom + view.pan.x,
+        y * view.zoom + view.pan.y,
+        80 * view.zoom,
+        80 * view.zoom,
+      );
+    },
+  };
+}
+
+function Harness({ layers }: { layers: CanvasLayerDescriptor[] }) {
+  const [view, setView] = useState({ zoom: 1, pan: { x: 50, y: 50 } });
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <CanvasStack layers={layers} view={view} onViewChange={setView}>
+        <div style={{ position: 'absolute', top: 8, right: 8 }}>
+          <ScaleIndicator />
+        </div>
+      </CanvasStack>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <Harness layers={[makeColoredLayer('a', '#3a86ff', 0, 0)]} />,
+};
+
+export const MultiLayer: Story = {
+  render: () => (
+    <Harness
+      layers={[
+        makeColoredLayer('a', '#3a86ff', 0, 0),
+        makeColoredLayer('b', '#ff006e', 60, 60),
+        makeColoredLayer('c', '#ffbe0b', 120, 120),
+      ]}
+    />
+  ),
+};
+
+export const WithScaleIndicator: Story = {
+  render: () => <Harness layers={[makeColoredLayer('a', '#06d6a0', 0, 0)]} />,
+};

package/src/canvas/CanvasStack.test.tsx

@@ -0,0 +1,82 @@
+import { render } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { CanvasStack } from './CanvasStack';
+import type { CanvasLayerDescriptor } from './useLayerScheduler';
+
+beforeAll(() => {
+  // jsdom's <canvas>.getContext returns null by default; stub a minimal 2D context.
+  HTMLCanvasElement.prototype.getContext = vi.fn(() => ({
+    save: vi.fn(),
+    restore: vi.fn(),
+    setTransform: vi.fn(),
+    clearRect: vi.fn(),
+    fillRect: vi.fn(),
+    beginPath: vi.fn(),
+    arc: vi.fn(),
+    fill: vi.fn(),
+    stroke: vi.fn(),
+  })) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function makeLayers(count: number): CanvasLayerDescriptor[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `layer-${i}`,
+    visible: true,
+    render: vi.fn(),
+  }));
+}
+
+describe('<CanvasStack>', () => {
+  it('renders one canvas per layer', () => {
+    const { container } = render(
+      <CanvasStack
+        layers={makeLayers(3)}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+      />,
+    );
+    expect(container.querySelectorAll('canvas')).toHaveLength(3);
+  });
+
+  it('calls render functions for visible layers', async () => {
+    const layers = makeLayers(2);
+    render(
+      <CanvasStack
+        layers={layers}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+      />,
+    );
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+    expect(layers[0]?.render).toHaveBeenCalled();
+    expect(layers[1]?.render).toHaveBeenCalled();
+  });
+
+  it('does not call render for invisible layers', async () => {
+    const layers = makeLayers(2);
+    if (layers[1]) layers[1].visible = false;
+    render(
+      <CanvasStack
+        layers={layers}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+      />,
+    );
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+    expect(layers[0]?.render).toHaveBeenCalled();
+    expect(layers[1]?.render).not.toHaveBeenCalled();
+  });
+
+  it('renders overlay children', () => {
+    const { getByText } = render(
+      <CanvasStack
+        layers={makeLayers(1)}
+        view={{ zoom: 1, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+      >
+        <span>overlay-content</span>
+      </CanvasStack>,
+    );
+    expect(getByText('overlay-content')).toBeInTheDocument();
+  });
+});

package/src/canvas/CanvasStack.tsx

@@ -0,0 +1,108 @@
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import type { Point, ViewTransform } from '../instrument/types';
+import { CanvasStackContext } from './CanvasStackContext';
+import { screenToWorld } from './canvasCoords';
+import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
+import { usePanZoom } from './usePanZoom';
+
+export interface CanvasStackProps {
+  layers: CanvasLayerDescriptor[];
+  view: ViewTransform;
+  onViewChange: (v: ViewTransform) => void;
+  width?: number | string;
+  height?: number | string;
+  className?: string;
+  onHitTest?: (worldPos: Point) => void;
+  children?: ReactNode;
+}
+
+export function CanvasStack({
+  layers,
+  view,
+  onViewChange,
+  width = '100%',
+  height = '100%',
+  className,
+  onHitTest,
+  children,
+}: CanvasStackProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const canvasMap = useRef<Map<string, HTMLCanvasElement>>(new Map());
+  const [size, setSize] = useState({ width: 0, height: 0, dpr: 1 });
+
+  const setCanvasRef = (id: string, el: HTMLCanvasElement | null): void => {
+    if (el) canvasMap.current.set(id, el);
+    else canvasMap.current.delete(id);
+  };
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const update = () => {
+      const rect = el.getBoundingClientRect();
+      const dpr = window.devicePixelRatio ?? 1;
+      setSize((prev) => {
+        if (prev.width === rect.width && prev.height === rect.height && prev.dpr === dpr) {
+          return prev;
+        }
+        return { width: rect.width, height: rect.height, dpr };
+      });
+    };
+    update();
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const handlers = usePanZoom({ view, onViewChange });
+  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size });
+
+  const ctxValue = useMemo(() => ({ view }), [view]);
+
+  const containerStyle: CSSProperties = { width, height };
+  const canvasPx = {
+    width: Math.max(0, Math.round(size.width * size.dpr)),
+    height: Math.max(0, Math.round(size.height * size.dpr)),
+  };
+  const canvasCss: CSSProperties = {
+    width: size.width,
+    height: size.height,
+  };
+
+  const handlePointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const wasDragging = handlers.isDragging();
+    handlers.onPointerUp(e);
+    if (!wasDragging && onHitTest && containerRef.current) {
+      const rect = containerRef.current.getBoundingClientRect();
+      const screen = { x: e.clientX - rect.left, y: e.clientY - rect.top };
+      onHitTest(screenToWorld(screen, view));
+    }
+  };
+
+  return (
+    <CanvasStackContext.Provider value={ctxValue}>
+      <div
+        ref={containerRef}
+        className={className ? `lk-canvas-stack ${className}` : 'lk-canvas-stack'}
+        style={containerStyle}
+        onWheel={handlers.onWheel}
+        onPointerDown={handlers.onPointerDown}
+        onPointerMove={handlers.onPointerMove}
+        onPointerUp={handlePointerUp}
+      >
+        {layers.map((layer) => (
+          <canvas
+            key={layer.id}
+            ref={(el) => setCanvasRef(layer.id, el)}
+            className="lk-canvas-stack__canvas"
+            width={canvasPx.width}
+            height={canvasPx.height}
+            style={{ ...canvasCss, display: layer.visible ? 'block' : 'none' }}
+          />
+        ))}
+        <div className="lk-canvas-stack__overlay">{children}</div>
+      </div>
+    </CanvasStackContext.Provider>
+  );
+}

package/src/canvas/CanvasStackContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+import type { ViewTransform } from '../instrument/types';
+
+export interface CanvasStackContextValue {
+  view: ViewTransform;
+}
+
+export const CanvasStackContext = createContext<CanvasStackContextValue | null>(null);

package/src/canvas/canvasCoords.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { screenToWorld, worldToScreen } from './canvasCoords';
+
+describe('canvasCoords', () => {
+  it('identity: zoom=1 pan=0 leaves coords unchanged', () => {
+    const v = { zoom: 1, pan: { x: 0, y: 0 } };
+    expect(worldToScreen({ x: 7, y: 9 }, v)).toEqual({ x: 7, y: 9 });
+    expect(screenToWorld({ x: 7, y: 9 }, v)).toEqual({ x: 7, y: 9 });
+  });
+
+  it('zoom only scales coords', () => {
+    const v = { zoom: 2, pan: { x: 0, y: 0 } };
+    expect(worldToScreen({ x: 3, y: 4 }, v)).toEqual({ x: 6, y: 8 });
+    expect(screenToWorld({ x: 6, y: 8 }, v)).toEqual({ x: 3, y: 4 });
+  });
+
+  it('pan only translates coords', () => {
+    const v = { zoom: 1, pan: { x: 10, y: 20 } };
+    expect(worldToScreen({ x: 1, y: 2 }, v)).toEqual({ x: 11, y: 22 });
+    expect(screenToWorld({ x: 11, y: 22 }, v)).toEqual({ x: 1, y: 2 });
+  });
+
+  it('round-trip is identity', () => {
+    const v = { zoom: 1.5, pan: { x: 7, y: -3 } };
+    const p = { x: 12.34, y: 56.78 };
+    const back = screenToWorld(worldToScreen(p, v), v);
+    expect(back.x).toBeCloseTo(p.x, 10);
+    expect(back.y).toBeCloseTo(p.y, 10);
+  });
+});

package/src/canvas/canvasCoords.ts

@@ -0,0 +1,15 @@
+import type { Point, ViewTransform } from '../instrument/types';
+
+export function worldToScreen(world: Point, view: ViewTransform): Point {
+  return {
+    x: world.x * view.zoom + view.pan.x,
+    y: world.y * view.zoom + view.pan.y,
+  };
+}
+
+export function screenToWorld(screen: Point, view: ViewTransform): Point {
+  return {
+    x: (screen.x - view.pan.x) / view.zoom,
+    y: (screen.y - view.pan.y) / view.zoom,
+  };
+}

package/src/canvas/index.ts

@@ -0,0 +1,6 @@
+export type { CanvasStackProps } from './CanvasStack';
+export { CanvasStack } from './CanvasStack';
+export type { CanvasStackContextValue } from './CanvasStackContext';
+export { CanvasStackContext } from './CanvasStackContext';
+export { screenToWorld, worldToScreen } from './canvasCoords';
+export type { CanvasLayerDescriptor } from './useLayerScheduler';