create-substrate 0.1.0

package/skills/canvas-2d/SKILL.md

@@ -0,0 +1,132 @@
+# 2D canvas
+
+Guide to building spatial 2D tools with Substrate — shape editors, diagram builders, whiteboard apps, and Figma-like design surfaces.
+
+## When to use this surface
+
+Use a 2D canvas when the app involves objects on an infinite pannable/zoomable plane: design tools, diagram editors, whiteboard apps, map builders, node graphs, or any tool where users place, select, and manipulate flat shapes and elements.
+
+## Surface setup
+
+This is Substrate's default surface. The `DesignCanvas` component provides a full 2D rendering pipeline out of the box.
+
+### Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/design-canvas
+```
+
+This pulls in the canvas renderer, hit-test system, interaction hooks, transform utilities, and all required stores.
+
+### Mount
+
+```tsx
+import { DesignCanvas } from "@/registry/substrate/canvas/design-canvas"
+
+export default function PlaygroundPage() {
+	return (
+		<div className="h-screen w-screen bg-canvas">
+			<DesignCanvas />
+		</div>
+	)
+}
+```
+
+## Architecture
+
+The 2D canvas uses a layered pipeline:
+
+```
+Pure renderer functions (canvas/renderer.ts)
+  → useCanvasRenderer (rAF loop with dirty flag)
+    → useCanvasInteraction (state machine for pointer events)
+      → useCanvasDrag (ref-based drag tracking, no re-renders)
+        → useCanvasTransform (screen ↔ world coordinate conversion)
+          → useHitTest (spatial queries)
+            → useDocumentStore (element CRUD + undo/redo)
+```
+
+### Rendering
+
+The renderer uses the Canvas 2D API directly — no React reconciliation in the render loop. Renderer functions are pure: they take a context, camera, and element data, and draw. The `useCanvasRenderer` hook runs a `requestAnimationFrame` loop that only repaints when `markDirty()` has been called.
+
+### Coordinate systems
+
+- **Screen space** — pixel coordinates relative to the canvas element
+- **World space** — infinite canvas coordinates, affected by camera pan/zoom
+
+Always convert pointer events to world space before hit-testing or element manipulation. Use `screenToWorld()` and `worldToScreen()` from `useCanvasTransform`.
+
+### State
+
+`useDocumentStore` holds the element map, element order, selection set, and history stack. All mutations go through store actions. Call `pushSnapshot()` before any mutation to enable undo/redo.
+
+## Wiring to Substrate chrome
+
+### Toolbar
+
+The default tool set for a 2D canvas:
+
+| Tool      | Purpose                       | Shortcut |
+| --------- | ----------------------------- | -------- |
+| Select    | Click/drag to select elements | V        |
+| Hand      | Pan the canvas                | H        |
+| Rectangle | Draw rectangles               | R        |
+| Ellipse   | Draw ellipses                 | O        |
+| Line      | Draw lines                    | L        |
+| Text      | Place text elements           | T        |
+| Frame     | Draw frame containers         | F        |
+
+### Panels
+
+See the [composing panels](./composing-panels.md) skill for full details. In summary:
+
+- **Left panel** — layers list (render order, visibility toggles, selection)
+- **Right panel** — properties inspector (transform, fill, stroke, opacity, type-specific properties)
+
+### Interactions
+
+See the [wire interactions](./wire-interactions.md) skill for the full state machine. Key patterns:
+
+- Click to select, shift-click to multi-select
+- Drag on empty space with select tool → marquee selection
+- Drag on selected element → move
+- Drag on resize handle → resize
+- Drag with shape tool → create new element
+- Middle-click or hand tool → pan
+
+## Extending the canvas
+
+### Custom elements
+
+To add a new element type (e.g. star, arrow, image), follow the [create custom tool](./create-custom-tool.md) skill. The pipeline is: type definition → factory → renderer → hit-test → interaction → shortcut → cursor → toolbar.
+
+### Custom rendering
+
+For specialised visuals (gradients, patterns, blend modes, filters), modify the renderer functions in `canvas/renderer.ts`. Each element type has its own render case — add drawing logic there.
+
+### Canvas overlays
+
+For UI elements that sit on top of the canvas (selection indicators, context menus, floating labels), render them as absolutely positioned DOM elements rather than drawing them on the canvas. Convert world positions to screen positions for placement.
+
+## Theming
+
+The canvas background is driven by the `--canvas` CSS variable, read at render time via `getComputedStyle`. Grid dots use `--canvas-foreground`. See the [theming](./theming.md) skill for the full token table.
+
+## What to build
+
+Some examples of what this surface enables:
+
+- **Design tool** — shape creation, styling, alignment, export (the default Substrate experience)
+- **Diagram editor** — nodes and connectors with auto-routing, swimlanes, labels
+- **Whiteboard** — freeform drawing, sticky notes, image placement, real-time collaboration
+- **Map builder** — tile-based or freeform map editor for games or floor plans
+- **Node graph** — visual programming interface with typed ports and connections
+- **Wireframe tool** — UI component blocks with snap-to-grid and responsive breakpoints
+
+## Related reference skills
+
+- **substrate-canvas** — full catalogue of spatial hooks (useViewport, useSelection, useDragReorder) and utilities (snapToGrid, boundingBox, math)
+- **substrate-scaffold** — Toolbar, Panel, StatusBar, ZoomControls for the app shell
+- **substrate-controls** — NumberInput, Slider, ColourPicker, ActionControls for property panes
+- **substrate-interaction** — useUndoable, useClipboard, createKeyboardShortcuts, LayerList

package/skills/composing-panels/SKILL.md

@@ -0,0 +1,309 @@
+# Composing panels
+
+Guide to building property panels, layer lists, and inspector UIs using Substrate's panel component system.
+
+## Component hierarchy
+
+Substrate's panel system is a composition of four components:
+
+```
+Panel (side panel shell — left or right)
+  └── Pane (collapsible content section)
+        ├── PaneHeader
+        │     ├── PaneLabel (section title)
+        │     └── PaneAction (header button)
+        └── Action (form field row)
+              ├── ActionLabel
+              └── ActionControls
+                    └── Slider, input, colour picker, etc.
+```
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/panel
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/pane
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/action
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/slider
+```
+
+## Panel positioning
+
+```tsx
+import { Panel } from "@/registry/substrate/components/panel"
+
+{
+	/* Left panel — layers, tool options */
+}
+;<Panel position="left">{/* Panes go here */}</Panel>
+
+{
+	/* Right panel — properties inspector */
+}
+;<Panel position="right">{/* Panes go here */}</Panel>
+```
+
+Panels are absolutely positioned and sized via CSS. They sit alongside the canvas in the playground layout.
+
+## Building a properties inspector
+
+A typical properties panel reads from `useDocumentStore` and writes back via `updateElement`:
+
+```tsx
+"use client"
+
+import { useDocumentStore } from "@/registry/substrate/stores/document-store"
+import {
+	Pane,
+	PaneHeader,
+	PaneLabel,
+	PaneAction,
+} from "@/registry/substrate/components/pane"
+import {
+	Action,
+	ActionLabel,
+	ActionControls,
+} from "@/registry/substrate/components/action"
+import { Slider } from "@/registry/substrate/components/slider"
+
+export function PropertiesPanel() {
+	const selectedIds = useDocumentStore((s) => s.selectedIds)
+	const elements = useDocumentStore((s) => s.elements)
+	const updateElement = useDocumentStore((s) => s.updateElement)
+	const pushSnapshot = useDocumentStore((s) => s.pushSnapshot)
+
+	// Single selection only for properties
+	if (selectedIds.size !== 1) return null
+	const element = elements[[...selectedIds][0]]
+	if (!element) return null
+
+	const handleChange = (changes: Record<string, unknown>) => {
+		pushSnapshot()
+		updateElement(element.id, changes)
+	}
+
+	return (
+		<>
+			{/* Position and size */}
+			<Pane>
+				<PaneHeader>
+					<PaneLabel>Transform</PaneLabel>
+				</PaneHeader>
+				<Action>
+					<ActionLabel>X</ActionLabel>
+					<ActionControls>
+						<input
+							type="number"
+							value={Math.round(element.x)}
+							onChange={(e) => handleChange({ x: Number(e.target.value) })}
+							className="w-full bg-transparent text-xs tabular-nums"
+						/>
+					</ActionControls>
+				</Action>
+				<Action>
+					<ActionLabel>Y</ActionLabel>
+					<ActionControls>
+						<input
+							type="number"
+							value={Math.round(element.y)}
+							onChange={(e) => handleChange({ y: Number(e.target.value) })}
+							className="w-full bg-transparent text-xs tabular-nums"
+						/>
+					</ActionControls>
+				</Action>
+				<Action>
+					<ActionLabel>W</ActionLabel>
+					<ActionControls>
+						<input
+							type="number"
+							value={Math.round(element.width)}
+							onChange={(e) => handleChange({ width: Number(e.target.value) })}
+							className="w-full bg-transparent text-xs tabular-nums"
+						/>
+					</ActionControls>
+				</Action>
+				<Action>
+					<ActionLabel>H</ActionLabel>
+					<ActionControls>
+						<input
+							type="number"
+							value={Math.round(element.height)}
+							onChange={(e) => handleChange({ height: Number(e.target.value) })}
+							className="w-full bg-transparent text-xs tabular-nums"
+						/>
+					</ActionControls>
+				</Action>
+			</Pane>
+
+			{/* Opacity */}
+			<Pane>
+				<PaneHeader>
+					<PaneLabel>Opacity</PaneLabel>
+				</PaneHeader>
+				<Action>
+					<ActionLabel>{Math.round(element.opacity * 100)}%</ActionLabel>
+					<ActionControls>
+						<Slider
+							value={[element.opacity * 100]}
+							onValueChange={([v]) => handleChange({ opacity: v / 100 })}
+							max={100}
+							step={1}
+						/>
+					</ActionControls>
+				</Action>
+			</Pane>
+		</>
+	)
+}
+```
+
+## Building a layers panel
+
+A layers panel lists elements in render order (bottom to top) and lets users select, reorder, and toggle visibility:
+
+```tsx
+"use client"
+
+import { useDocumentStore } from "@/registry/substrate/stores/document-store"
+import {
+	Pane,
+	PaneHeader,
+	PaneLabel,
+} from "@/registry/substrate/components/pane"
+
+export function LayersPanel() {
+	const elements = useDocumentStore((s) => s.elements)
+	const elementOrder = useDocumentStore((s) => s.elementOrder)
+	const selectedIds = useDocumentStore((s) => s.selectedIds)
+	const select = useDocumentStore((s) => s.select)
+	const updateElement = useDocumentStore((s) => s.updateElement)
+
+	return (
+		<Pane>
+			<PaneHeader>
+				<PaneLabel>Layers</PaneLabel>
+			</PaneHeader>
+			<div className="flex flex-col-reverse">
+				{elementOrder.map((id) => {
+					const el = elements[id]
+					if (!el) return null
+					return (
+						<button
+							key={id}
+							onClick={(e) => select([id], e.shiftKey)}
+							data-selected={selectedIds.has(id) || undefined}
+							className="flex items-center gap-2 px-2 py-1 text-xs rounded hover:bg-accent data-[selected]:bg-accent"
+						>
+							<span className="truncate">{el.name}</span>
+							<button
+								onClick={(e) => {
+									e.stopPropagation()
+									updateElement(id, { visible: !el.visible })
+								}}
+								className="ml-auto opacity-50 hover:opacity-100"
+							>
+								{el.visible ? "👁" : "—"}
+							</button>
+						</button>
+					)
+				})}
+			</div>
+		</Pane>
+	)
+}
+```
+
+## Wiring panels to the store
+
+Use `usePanelStore` to control panel visibility:
+
+```tsx
+import { usePanelStore } from "@/registry/substrate/stores/panel-store"
+
+const leftPanel = usePanelStore((s) => s.leftPanel)
+const rightPanel = usePanelStore((s) => s.rightPanel)
+const toggleLeft = usePanelStore((s) => s.toggleLeft)
+const toggleRight = usePanelStore((s) => s.toggleRight)
+```
+
+Then conditionally render:
+
+```tsx
+{
+	leftPanel && (
+		<Panel position="left">
+			<LayersPanel />
+		</Panel>
+	)
+}
+
+{
+	rightPanel && (
+		<Panel position="right">
+			<PropertiesPanel />
+		</Panel>
+	)
+}
+```
+
+## Creating custom panes
+
+Follow the compound component pattern:
+
+1. **Wrap in `<Pane>`** for consistent spacing
+2. **Use `<PaneHeader>` + `<PaneLabel>`** for the section title
+3. **Use `<PaneAction>`** for header buttons (add, remove, toggle)
+4. **Use `<Action>` + `<ActionLabel>` + `<ActionControls>`** for each property row
+5. **Read from `useDocumentStore`** with granular selectors
+6. **Call `pushSnapshot()` before mutations** to enable undo/redo
+7. **Use `updateElement(id, changes)`** to write back
+
+## Patterns
+
+### Conditional panes by element type
+
+Show different properties based on the selected element's type:
+
+```tsx
+{
+	element.type === "rectangle" && (
+		<Pane>
+			<PaneHeader>
+				<PaneLabel>Corner radius</PaneLabel>
+			</PaneHeader>
+			<Action>
+				<ActionControls>
+					<Slider
+						value={[element.cornerRadius]}
+						onValueChange={([v]) => handleChange({ cornerRadius: v })}
+						max={100}
+					/>
+				</ActionControls>
+			</Action>
+		</Pane>
+	)
+}
+```
+
+### Multi-selection
+
+When multiple elements are selected, show shared properties or a summary:
+
+```tsx
+if (selectedIds.size > 1) {
+	return (
+		<Pane>
+			<PaneHeader>
+				<PaneLabel>{selectedIds.size} elements selected</PaneLabel>
+			</PaneHeader>
+			{/* Show shared opacity, alignment buttons, etc. */}
+		</Pane>
+	)
+}
+```
+
+## Related reference skills
+
+- **substrate-scaffold** — full catalogue of Panel, Pane, CollapsiblePane, PaneHeader, and layout components
+- **substrate-controls** — full catalogue of ActionControls, NumberInput, Slider, NumberSlider, Select, Toggle, ColourPicker, and the data-slot composition pattern
+- **substrate-interaction** — HistoryControls (auto-positioned in PaneHeader), LayerList, TreeList

package/skills/create-custom-tool/SKILL.md

@@ -0,0 +1,157 @@
+# Create a custom tool
+
+End-to-end guide for adding a new canvas tool to Substrate — from type definition through to toolbar entry and keyboard shortcut.
+
+## Overview
+
+A tool in Substrate touches these files:
+
+1. **`types.ts`** — add to the `ToolType` union
+2. **`lib/element-factory.ts`** — add a factory function (if the tool creates elements)
+3. **`canvas/renderer.ts`** — add rendering logic
+4. **`canvas/hit-test.ts`** — add hit-testing (if clickable)
+5. **`hooks/use-canvas-interaction.ts`** — handle pointer events for the tool
+6. **`hooks/use-keyboard-shortcuts.ts`** — bind a key
+7. **`canvas/design-canvas.tsx`** — add cursor mapping
+8. **Toolbar** — add a toggle in your page
+
+## Step 1: Define the type
+
+In `types.ts`, extend the `ToolType` union:
+
+```ts
+export type ToolType =
+  | "select"
+  | "hand"
+  | "rectangle"
+  | "ellipse"
+  | "line"
+  | "text"
+  | "frame"
+  | "your-tool"   // ← add here
+```
+
+If the tool creates a new element type, also extend `ElementType` and create a corresponding interface:
+
+```ts
+export type ElementType = "rectangle" | "ellipse" | "text" | "line" | "frame" | "your-element"
+
+export interface YourElement extends BaseElement {
+  type: "your-element"
+  // Custom properties
+  someProperty: number
+}
+
+export type DesignElement =
+  | RectangleElement
+  | EllipseElement
+  | TextElement
+  | LineElement
+  | FrameElement
+  | YourElement
+```
+
+## Step 2: Element factory (if creating elements)
+
+In `lib/element-factory.ts`, add a factory:
+
+```ts
+export function createYourElement(x: number, y: number, width: number, height: number): YourElement {
+  return {
+    id: generateId(),
+    type: "your-element",
+    name: "Your Element",
+    x, y, width, height,
+    rotation: 0,
+    opacity: 1,
+    fill: { type: "solid", color: "#6366f1", opacity: 1 },
+    stroke: null,
+    locked: false,
+    visible: true,
+    someProperty: 42,
+  }
+}
+```
+
+## Step 3: Renderer
+
+In `canvas/renderer.ts`, add a rendering case. The renderer uses the Canvas 2D API directly:
+
+```ts
+case "your-element": {
+  ctx.save()
+  // Transform, draw, restore
+  ctx.restore()
+  break
+}
+```
+
+## Step 4: Hit-test (if clickable)
+
+In `canvas/hit-test.ts`, add detection logic in the `hitTestElement` function:
+
+```ts
+case "your-element":
+  return pointInBounds(localPoint, { x: 0, y: 0, width: el.width, height: el.height })
+```
+
+## Step 5: Interaction hook
+
+In `hooks/use-canvas-interaction.ts`, handle the tool in the pointer event state machine. The key areas are:
+
+- **`onPointerDown`** — detect what was clicked, start the appropriate drag type
+- **`onPointerMove`** — update drag state, preview creation
+- **`onPointerUp`** — finalise the action (create element, commit move, etc.)
+
+For a creation tool, the pattern matches the existing rectangle/ellipse flow — start a "create" drag on pointer down, preview during move, commit on pointer up.
+
+## Step 6: Keyboard shortcut
+
+In `hooks/use-keyboard-shortcuts.ts`, add a key binding in the switch statement:
+
+```ts
+case "y": setTool("your-tool"); return
+```
+
+## Step 7: Cursor
+
+In `canvas/design-canvas.tsx`, add to `CURSOR_MAP`:
+
+```ts
+const CURSOR_MAP: Record<string, string> = {
+  // ...existing entries
+  "your-tool": "crosshair",
+}
+```
+
+## Step 8: Toolbar entry
+
+In your playground page, add a toggle:
+
+```tsx
+<ToolbarToggle value="your-tool" tooltip="Your Tool" shortcut="Y">
+  <YourIcon className="size-4" />
+</ToolbarToggle>
+```
+
+## Tools that don't create elements
+
+Not every tool creates elements. For tools like a measurement tool, colour picker, or zoom tool:
+
+- Skip steps 2 (factory) and 4 (hit-test for new element type)
+- In the interaction hook, handle the tool's pointer events directly (e.g. measure distance between pointer down and up)
+- Store any tool-specific state in a dedicated Zustand store if needed
+
+## Testing your tool
+
+1. Select the tool from the toolbar or press its shortcut key
+2. Verify the cursor changes
+3. Test the full interaction cycle: pointer down → move → up
+4. Check undo/redo works correctly (ensure `pushSnapshot()` is called before mutations)
+5. Verify the element renders and can be selected/moved/resized
+
+## Related reference skills
+
+- **substrate-canvas** — useViewport, snap, boundingBox, hit testing, coordinate maths
+- **substrate-scaffold** — Toolbar (for adding your tool button), StatusBar
+- **substrate-interaction** — createKeyboardShortcuts (for binding a shortcut key), useUndoable