create-substrate 0.1.0

package/skills/substrate-canvas/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: substrate-canvas
+description: "Spatial hooks and utilities for Substrate canvas surfaces: viewport (pan/zoom), selection, drag reorder, snapping, bounding box, coordinate maths, and hit testing. Use when building or extending a 2D/3D spatial surface. Triggers on: viewport, pan, zoom, snap to grid, bounding box, hit test, coordinate transform, canvas interaction, spatial, drag."
+user-invocable: true
+---
+
+# Substrate canvas
+
+Canvas utilities handle everything spatial – viewport transforms, coordinate systems, snapping, bounding box computation, and hit testing. These are the building blocks for any surface where users interact with positioned objects.
+
+## When to use this skill
+
+Use the canvas skill when you need to:
+
+- Add pan/zoom to a surface
+- Implement snap-to-grid or smart edge snapping
+- Compute bounding boxes for selection or zoom-to-fit
+- Convert between screen and world coordinates
+- Build or extend hit testing
+- Add spatial selection (click, shift-click, marquee)
+
+For the app shell around the surface, see **substrate-scaffold**.
+For non-spatial interaction (undo, clipboard, shortcuts), see **substrate-interaction**.
+
+---
+
+## Hooks
+
+### useViewport
+
+`registry/substrate/hooks/use-viewport.ts`
+
+Generic pan/zoom state. Surface-agnostic – works for 2D canvas, node editors, or any pannable area.
+
+**Returns**: `viewport` (x, y, zoom), `toWorld`, `toScreen`, `pan`, `zoomToPoint`, `zoomIn`, `zoomOut`, `resetZoom`, `zoomToFit`, `handleWheel`
+
+**When to use**: Any surface that needs panning and zooming. Wire `handleWheel` to the container's `onWheel`, use `toWorld`/`toScreen` for coordinate transforms.
+
+**Connects to**: `ZoomControls` (substrate-scaffold) reads `viewport.zoom` and calls `zoomIn`/`zoomOut`/`resetZoom`.
+
+```tsx
+const { viewport, handleWheel, zoomToFit } = useViewport({
+  minZoom: 0.1,
+  maxZoom: 10,
+})
+```
+
+---
+
+### useSelection
+
+`registry/substrate/hooks/use-selection.ts`
+
+Multi-select with modifier key support: plain click, ⌘-click toggle, shift-click range.
+
+**Returns**: `selectedIds`, `select`, `setSelection`, `selectAll`, `deselectAll`, `isSelected`
+
+**When to use**: Layer lists, node selections, element picking – any context where the user selects from a list or spatial layout.
+
+**Connects to**: `LayerList` and `TreeList` (substrate-interaction) for list-based selection. Canvas hit-testing for spatial selection.
+
+---
+
+### useDragReorder
+
+`registry/substrate/hooks/use-drag-reorder.ts`
+
+Pointer-based list reordering using pointer capture. Calculates drop index from drag distance.
+
+**Returns**: `getDragItemProps`, `dragIndex`, `dropIndex`, `isDragging`
+
+**When to use**: Reorderable layer lists, timeline tracks, node port ordering.
+
+**Connects to**: `LayerList` (substrate-interaction) for visual layer reordering.
+
+---
+
+### Canvas-specific hooks
+
+These hooks are tightly coupled to the 2D canvas surface and its stores:
+
+| Hook | File | Purpose |
+| --- | --- | --- |
+| `useCanvasTransform` | `hooks/use-canvas-transform.ts` | Screen ↔ world coordinate conversion using `document-store` camera |
+| `useCanvasRenderer` | `hooks/use-canvas-renderer.ts` | Canvas 2D rendering loop with dirty flag and rAF |
+| `useCanvasDrag` | `hooks/use-canvas-drag.ts` | Pointer-based drag tracking (start/move/end) |
+| `useCanvasInteraction` | `hooks/use-canvas-interaction.ts` | Orchestrates tool-specific behaviour (select, create, pan) |
+| `useHitTest` | `hooks/use-hit-test.ts` | Point-in-element and handle hit detection |
+| `useKeyboardShortcuts` | `hooks/use-keyboard-shortcuts.ts` | Canvas-specific keyboard bindings |
+
+These are typically used together inside a `DesignCanvas` or similar surface component. See **substrate-surfaces** for how they compose.
+
+---
+
+## Utilities
+
+### snapToGrid / snapToGuides
+
+`registry/substrate/lib/snap.ts`
+
+Grid snapping and smart edge snapping.
+
+| Function | Purpose |
+| --- | --- |
+| `snapToGrid(point, gridSize, options?)` | Snap a point to nearest grid intersection |
+| `snapValueToGrid(value, gridSize, origin?)` | Snap a single number to grid |
+| `snapToGuides(point, guides, options?)` | Snap to nearby guide lines (edges, centres) within a threshold |
+| `guidesFromBounds(boundsList, exclude?)` | Generate alignment guides from sibling element bounds |
+
+**When to use**: Object placement and resizing. Call `snapToGrid` during move/resize interactions. Use `guidesFromBounds` + `snapToGuides` for Figma-style smart alignment lines.
+
+```ts
+// During element drag
+const guides = guidesFromBounds(siblingBounds, draggedBounds)
+const { point, snappedGuides } = snapToGuides(newPosition, guides)
+// Render snappedGuides as alignment lines
+```
+
+---
+
+### boundingBox
+
+`registry/substrate/lib/bounding-box.ts`
+
+Bounding box computation and spatial queries.
+
+| Function | Purpose |
+| --- | --- |
+| `boundingBox(items)` | Union bounds of multiple Bounds |
+| `boundingBoxFromPoints(points)` | Bounds from an array of Points |
+| `expandBounds(bounds, padding)` | Expand uniformly |
+| `expandBoundsBy(bounds, { top, right, bottom, left })` | Expand per-side |
+| `containsPoint(bounds, point)` | Point-in-bounds test |
+| `containsBounds(a, b)` | Does A fully contain B? |
+| `boundsCenter(bounds)` | Centre point |
+| `intersectBounds(a, b)` | Intersection or null |
+
+**When to use**: Zoom-to-fit (compute union bounds → pass to `useViewport.zoomToFit`), marquee selection (test which elements intersect the selection rectangle), alignment distribution.
+
+---
+
+### math
+
+`registry/substrate/lib/math.ts`
+
+Core geometry functions.
+
+| Function | Purpose |
+| --- | --- |
+| `rotatePoint(point, center, angleDeg)` | Rotate a point around a centre |
+| `boundsCenter(bounds)` | Centre of a bounding box |
+| `pointInBounds(point, bounds)` | Hit test |
+| `pointInEllipseBounds(point, bounds)` | Ellipse hit test |
+| `boundsOverlap(a, b)` | Overlap test |
+| `normalizeBounds(start, end)` | Normalise a drag rectangle |
+| `screenToWorld(point, camera)` / `worldToScreen(point, camera)` | Coordinate transforms |
+| `clamp(value, min, max)` | Numeric clamp |
+| `distance(a, b)` | Euclidean distance |
+
+---
+
+## Stores
+
+### document-store
+
+`registry/substrate/stores/document-store.ts`
+
+Central store for the 2D canvas surface – elements, selection, camera, history.
+
+### tool-store
+
+`registry/substrate/stores/tool-store.ts`
+
+Active tool state. Read by both the surface (to change interaction mode) and the toolbar (to highlight the active tool).
+
+---
+
+## Recommended patterns
+
+### Adding snap-to-grid to an existing surface
+
+1. Import `snapToGrid` from `lib/snap`
+2. In your drag handler, snap the position before applying it:
+   ```ts
+   const snapped = snapToGrid(worldPosition, gridSize)
+   updateElement(id, { x: snapped.x, y: snapped.y })
+   ```
+3. Optionally add a `Toggle` in the toolbar for enabling/disabling snap
+
+### Zoom-to-fit selection
+
+```ts
+const selected = elements.filter((el) => selectedIds.has(el.id))
+const bounds = boundingBox(selected)
+if (bounds) zoomToFit(expandBounds(bounds, 40))
+```
+
+### Smart alignment snapping
+
+```ts
+const siblings = elements.filter((el) => !selectedIds.has(el.id))
+const guides = guidesFromBounds(siblings.map(toBounds))
+const { point, snappedGuides } = snapToGuides(dragPos, guides, { threshold: 5 })
+// Render snappedGuides as thin blue lines
+```
+
+---
+
+## Cross-references
+
+| Need | Skill |
+| --- | --- |
+| Zoom controls and status bar | **substrate-scaffold** |
+| Layer list, tree list for structure panels | **substrate-interaction** |
+| Controls inside property panes | **substrate-controls** |
+| Surface architecture and rendering | **substrate-surfaces** |
+| Node editor specifics | **substrate-nodes** |

package/skills/substrate-controls/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: substrate-controls
+description: "Substrate input and selection primitives: number input, slider, number slider, select, toggle, text area, colour picker, easing curve editor, swatch palette, and action controls. Use when building property editors, parameter forms, or any interactive control surface. Triggers on: input, slider, select, toggle, colour picker, swatch, easing, action controls, property editor, form control."
+user-invocable: true
+---
+
+# Substrate controls
+
+Controls are the interactive inputs and selectors that live inside panes, toolbars, and action groups. They follow the `data-slot` composition pattern – parent containers (ActionControls, Toolbar, PaneHeader) style children automatically via CSS selectors.
+
+## When to use this skill
+
+Use the controls skill when you need to:
+
+- Add a property input to a pane (e.g. width, height, rotation, opacity)
+- Build a colour selection UI
+- Create a parameter group with labels and inline controls
+- Wire an easing curve editor into an animation panel
+- Understand how ActionControls composes child controls
+
+For the pane containers that hold controls, see **substrate-scaffold**.
+For selection, undo, and clipboard behaviour, see **substrate-interaction**.
+
+---
+
+## The data-slot composition pattern
+
+This is the core design pattern of Substrate controls. Parent components style children by matching `data-slot` attributes – no prop drilling required.
+
+### ActionControls (the key container)
+
+`registry/substrate/components/action.tsx`
+
+A horizontal row that auto-styles its children:
+
+| Child slot       | Styling applied                      |
+| ---------------- | ------------------------------------ |
+| `number-input`   | Strips border, sets `bg-transparent` |
+| `select-trigger` | Strips border, sets `bg-transparent` |
+| `colour-swatch`  | `size-4`, removes border             |
+| `slider`         | Removes border                       |
+
+**Exports**: `ActionControls`, `ActionLabel`, `ActionSeparator`
+
+**Typical use**: Group a label + one or more controls on a single row inside a pane.
+
+```tsx
+<ActionControls>
+	<ActionLabel>Width</ActionLabel>
+	<NumberInput value={width} onChange={setWidth} min={0} />
+</ActionControls>
+```
+
+### How it works
+
+ActionControls applies Tailwind `**:data-[slot=...]` selectors in its className. When you drop a `NumberInput` (which renders `data-slot="number-input"`) inside, it automatically loses its border and gains transparent background – creating a seamless inline look.
+
+The same pattern is used by **Toolbar** (compaction) and **PaneHeader** (auto-positioning HistoryControls).
+
+---
+
+## Components in this domain
+
+### NumberInput
+
+`registry/substrate/components/number-input.tsx`
+
+Scrub-to-adjust number field. Supports label, suffix, min/max, step/shiftStep, precision, and pointer-lock scrubbing.
+
+**Props**: `value`, `onChange`, `onStart`, `label`, `suffix`, `min`, `max`, `step`, `shiftStep`, `precision`, `disabled`
+
+**When to use**: Any numeric property – dimensions, position, rotation, opacity, font size. Use `onStart` to push an undo snapshot before the value changes.
+
+---
+
+### Slider
+
+`registry/substrate/components/slider.tsx`
+
+Range slider built on Radix Slider. Single value or range (two thumbs).
+
+**When to use**: Bounded continuous values where a visual track helps – opacity, volume, zoom level.
+
+---
+
+### NumberSlider
+
+`registry/substrate/components/number-slider.tsx`
+
+Compound of Slider + NumberInput on a single row. The slider fills available space, the input is a fixed `w-18`.
+
+**Props**: Same as NumberInput plus all Slider range props.
+
+**When to use**: When you want both a slider for quick scrubbing and a precise numeric input – e.g. opacity, blur radius.
+
+---
+
+### Select
+
+`registry/substrate/components/select.tsx`
+
+Dropdown built on Radix Select. Compact `h-7` trigger.
+
+**Exports**: `Select`, `SelectTrigger`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator`, `SelectValue`
+
+**When to use**: Enum-style choices – blend mode, font family, alignment, export format. Renders `data-slot="select-trigger"` for ActionControls awareness.
+
+---
+
+### Toggle
+
+`registry/substrate/components/toggle.tsx`
+
+Binary toggle button built on Radix Toggle. `h-7 min-w-7 px-2`. Accent styling when pressed.
+
+**When to use**: On/off features – snap to grid, show guides, lock aspect ratio, bold/italic.
+
+---
+
+### TextArea
+
+`registry/substrate/components/text-area.tsx`
+
+Auto-resizing textarea with `minRows` / `maxRows`. Shares border/bg styling with NumberInput.
+
+**When to use**: Multi-line text – element content, descriptions, notes, code snippets.
+
+---
+
+### ColourPicker
+
+`registry/substrate/components/colour-picker.tsx`
+
+HSV colour picker with hex/RGB inputs and opacity slider. The swatch trigger renders `data-slot="colour-swatch"` for slot-aware composition.
+
+**When to use**: Fill, stroke, background, text colour – any colour property.
+
+---
+
+### SwatchPalette
+
+`registry/substrate/components/swatch-palette.tsx`
+
+Grid of colour swatches. Exports `MATERIAL_COLOURS` (24) and `TAILWIND_COLOURS` (16) presets.
+
+**Props**: `colours`, `columns` (default 8), `selected`, `onSelect`
+
+**When to use**: Quick colour selection from a predefined palette. Often paired with ColourPicker.
+
+---
+
+### EasingCurveEditor
+
+`registry/substrate/components/easing-curve-editor.tsx`
+
+Cubic bezier editor with draggable control points and real-time preview.
+
+**When to use**: Animation easing configuration. Typically inside a CollapsiblePane in an animation surface's right panel.
+
+---
+
+## Recommended combinations
+
+### Property pane for a shape
+
+```tsx
+<CollapsiblePane>
+	<CollapsiblePaneHeader>
+		<CollapsiblePaneLabel>Transform</CollapsiblePaneLabel>
+		<HistoryControls />
+	</CollapsiblePaneHeader>
+	<CollapsiblePaneContent className="space-y-1">
+		<ActionControls>
+			<ActionLabel>X</ActionLabel>
+			<NumberInput value={x} onChange={setX} onStart={pushSnapshot} />
+			<ActionSeparator />
+			<ActionLabel>Y</ActionLabel>
+			<NumberInput value={y} onChange={setY} onStart={pushSnapshot} />
+		</ActionControls>
+		<ActionControls>
+			<ActionLabel>W</ActionLabel>
+			<NumberInput value={w} onChange={setW} min={0} onStart={pushSnapshot} />
+			<ActionSeparator />
+			<ActionLabel>H</ActionLabel>
+			<NumberInput value={h} onChange={setH} min={0} onStart={pushSnapshot} />
+		</ActionControls>
+		<ActionControls>
+			<ActionLabel>Rotation</ActionLabel>
+			<NumberInput
+				value={r}
+				onChange={setR}
+				suffix="°"
+				onStart={pushSnapshot}
+			/>
+		</ActionControls>
+	</CollapsiblePaneContent>
+</CollapsiblePane>
+```
+
+### Opacity control
+
+```tsx
+<ActionControls>
+	<ActionLabel>Opacity</ActionLabel>
+	<NumberSlider
+		value={opacity}
+		onChange={setOpacity}
+		min={0}
+		max={100}
+		suffix="%"
+	/>
+</ActionControls>
+```
+
+### Colour + blend mode row
+
+```tsx
+<ActionControls>
+	<ColourPicker value={fill} onChange={setFill} />
+	<Select value={blendMode} onValueChange={setBlendMode}>
+		<SelectTrigger>
+			<SelectValue />
+		</SelectTrigger>
+		<SelectContent>
+			<SelectItem value="normal">Normal</SelectItem>
+			<SelectItem value="multiply">Multiply</SelectItem>
+			<SelectItem value="screen">Screen</SelectItem>
+		</SelectContent>
+	</Select>
+</ActionControls>
+```
+
+---
+
+## Cross-references
+
+| Need                                  | Skill                     |
+| ------------------------------------- | ------------------------- |
+| Pane and panel containers             | **substrate-scaffold**    |
+| Undo support (onStart → pushSnapshot) | **substrate-interaction** |
+| Animation easing in timeline surfaces | **substrate-surfaces**    |
+| Node property panels                  | **substrate-nodes**       |

package/skills/substrate-feedback/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: substrate-feedback
+description: "Substrate status, communication, and discovery components: toast, progress bar, badge, empty state, shortcut overlay, command palette, context menu, and popover. Use when showing feedback, status indicators, contextual menus, or discoverability aids. Triggers on: toast, notification, progress, loading, empty state, badge, command palette, context menu, popover, shortcut help, keyboard shortcuts display."
+user-invocable: true
+---
+
+# Substrate feedback
+
+Feedback components handle communication with the user – notifications, status indicators, contextual actions, and discoverability features.
+
+## When to use this skill
+
+Use the feedback skill when you need to:
+
+- Show success/error/undo notifications
+- Display loading or progress
+- Show empty states when there's no content
+- Add a command palette (⌘K) for quick actions
+- Build right-click context menus
+- Show a keyboard shortcuts overlay
+- Use popovers for inline detail views
+- Add status badges to elements
+
+For structural layout (toolbar, panels), see **substrate-scaffold**.
+For interactive controls (inputs, sliders), see **substrate-controls**.
+
+---
+
+## Components
+
+### Toast
+
+`registry/substrate/components/toast.tsx`
+
+Thin wrapper around Sonner. Exports a `toast` function with convenience methods.
+
+| Method | Duration | Use case |
+| --- | --- | --- |
+| `toast(message)` | 4s | General notification |
+| `toast.success(message)` | 3s | Confirmation (saved, exported) |
+| `toast.error(message)` | 6s | Error with longer reading time |
+| `toast.warning(message)` | 5s | Caution |
+| `toast.info(message)` | 4s | Informational |
+| `toast.undo(message, onUndo)` | 6s | Action with undo option |
+| `toast.dismiss(id?)` | — | Programmatic dismiss |
+
+**When to use**: After async operations (save, export, publish), destructive actions (delete with undo), errors. Use `toast.undo` for delete operations to give users a recovery path.
+
+```ts
+toast.undo("Layer deleted", () => restoreLayer(id))
+```
+
+---
+
+### ProgressBar
+
+`registry/substrate/components/progress-bar.tsx`
+
+Thin bar (h-1.5) with determinate and indeterminate modes.
+
+**Props**: `value`, `max` (default 100), `indeterminate`
+
+**When to use**: File uploads, export progress, batch operations. Use `indeterminate` when duration is unknown. Place at the top of a panel or inside a pane.
+
+---
+
+### Badge
+
+`registry/substrate/components/badge.tsx`
+
+Small label with 4 variants: `default`, `secondary`, `outline`, `muted`.
+
+**When to use**: Element type indicators (in layer lists), node categories, status labels (draft/published), keyboard shortcut hints.
+
+---
+
+### EmptyState
+
+`registry/substrate/components/empty-state.tsx`
+
+Centred placeholder for empty panels or lists.
+
+**Exports**: `EmptyState`, `EmptyStateIcon`, `EmptyStateTitle`, `EmptyStateDescription`, `EmptyStateAction`
+
+**When to use**: Empty layer lists, empty canvas, no search results, first-run experience.
+
+```tsx
+<EmptyState>
+  <EmptyStateIcon><RiStackLine /></EmptyStateIcon>
+  <EmptyStateTitle>No layers yet</EmptyStateTitle>
+  <EmptyStateDescription>
+    Draw a shape on the canvas to get started
+  </EmptyStateDescription>
+</EmptyState>
+```
+
+---
+
+### CommandPalette
+
+`registry/substrate/components/command-palette.tsx`
+
+⌘K-triggered command launcher using cmdk + Radix Dialog.
+
+**Exports**: `CommandPalette`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`
+
+**When to use**: Quick access to any action – tool switching, file operations, element creation, settings. Especially useful in node editors ("Add Node → Blur") and complex apps with many features.
+
+**Recommended groups**: Tools, Actions, Create, Recent, Settings.
+
+---
+
+### ContextMenu
+
+`registry/substrate/components/context-menu.tsx`
+
+Right-click menu built on Radix ContextMenu. Supports submenus.
+
+**Exports**: `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuSeparator`, `ContextMenuLabel`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`
+
+**When to use**: Right-click on canvas elements, layer items, node cards, tabs. Show contextual actions (copy, paste, delete, group, bring to front) with keyboard shortcut hints.
+
+**Connects to**: `createKeyboardShortcuts` (substrate-interaction) – use `formatShortcut` to render shortcut hints in menu items.
+
+---
+
+### ShortcutOverlay
+
+`registry/substrate/components/shortcut-overlay.tsx`
+
+Full-screen overlay listing all keyboard shortcuts, triggered by `?` key.
+
+**Props**: `groups` – array of `{ label, shortcuts: { label, keys }[] }`
+
+**When to use**: Discoverability aid. One per app. Pass the same shortcut groups registered with `createKeyboardShortcuts`.
+
+---
+
+### Popover
+
+`registry/substrate/components/popover.tsx`
+
+Floating panel built on Radix Popover. Optional arrow.
+
+**Exports**: `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverClose`
+
+**When to use**: Inline details, settings, colour pickers, property editors that don't warrant a full panel.
+
+---
+
+## Recommended patterns
+
+### Delete with undo
+
+```ts
+function handleDelete(ids: string[]) {
+  const snapshot = getElements(ids)
+  pushSnapshot()
+  removeElements(ids)
+  toast.undo(`${ids.length} element${ids.length > 1 ? "s" : ""} deleted`, () => {
+    restoreElements(snapshot)
+  })
+}
+```
+
+### Context menu with shortcuts
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>{children}</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem onSelect={copy}>
+      Copy <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem onSelect={paste}>
+      Paste <ContextMenuShortcut>⌘V</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuSub>
+      <ContextMenuSubTrigger>Arrange</ContextMenuSubTrigger>
+      <ContextMenuSubContent>
+        <ContextMenuItem onSelect={bringToFront}>Bring to front</ContextMenuItem>
+        <ContextMenuItem onSelect={sendToBack}>Send to back</ContextMenuItem>
+      </ContextMenuSubContent>
+    </ContextMenuSub>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+### Command palette with tool switching
+
+```tsx
+<CommandPalette>
+  <CommandInput placeholder="Search actions…" />
+  <CommandList>
+    <CommandGroup heading="Tools">
+      <CommandItem onSelect={() => setTool("select")}>
+        <RiCursorLine /> Select
+        <CommandShortcut>V</CommandShortcut>
+      </CommandItem>
+      <CommandItem onSelect={() => setTool("rectangle")}>
+        <RiRectangleLine /> Rectangle
+        <CommandShortcut>R</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandPalette>
+```
+
+---
+
+## Cross-references
+
+| Need | Skill |
+| --- | --- |
+| Keyboard shortcut registration | **substrate-interaction** |
+| Toolbar and status bar for badges | **substrate-scaffold** |
+| Node editor command palette groups | **substrate-nodes** |
+| Empty state in layer/tree lists | **substrate-interaction** |