create-substrate 0.1.0

package/skills/theming/SKILL.md

@@ -0,0 +1,117 @@
+# Theming Substrate
+
+Guide to customising the visual appearance of Substrate's canvas, UI chrome, and elements.
+
+## How theming works
+
+Substrate uses a CSS variable fallback chain (Tailwind v4) so you can override specific tokens without redefining everything. The pattern is:
+
+```css
+/* @theme inline block */
+--color-canvas: var(--canvas, var(--color-background));
+```
+
+Set `--canvas` to override the canvas background; if unset, it falls back to `--color-background`.
+
+## 1. Substrate tokens
+
+Substrate defines its own semantic tokens that fall back to standard shadcn tokens:
+
+| Tailwind class | CSS variable | Fallback | Used by |
+|---|---|---|---|
+| `bg-canvas` | `--color-canvas` → `--canvas` | `--color-background` | Canvas background |
+| `text-canvas-foreground` | `--color-canvas-foreground` → `--canvas-foreground` | `--color-foreground-muted` | Canvas grid dots |
+| `bg-panel` | `--color-panel` → `--panel` | `--color-card` | Panel background |
+| `text-panel-foreground` | `--color-panel-foreground` → `--panel-foreground` | `--color-card-foreground` | Panel text |
+
+Override the short-form variables in your `:root` and `.dark` blocks:
+
+```css
+:root {
+  /* Canvas */
+  --canvas: oklch(.97 0.0 0);
+  --canvas-foreground: oklch(0.556 0 0);
+  /* Panels */
+  --panel: oklch(1 0 0);
+  --panel-foreground: oklch(0.145 0 0);
+}
+
+.dark {
+  --canvas: oklch(17.764% 0.00002 271.152);
+  --canvas-foreground: oklch(0.708 0 0);
+  --panel: oklch(0.205 0 0);
+  --panel-foreground: oklch(0.985 0 0);
+}
+```
+
+## 2. Standard shadcn tokens
+
+The toolbar, slider, and tooltip still use standard shadcn tokens:
+
+### Key tokens per component
+
+- **Toolbar** — `bg-background`, `border`, `shadow-lg` for the container; `hover:bg-muted`, `aria-checked:bg-accent` for toggles
+- **Panel** — `bg-panel`, `text-panel-foreground`, `border-border`
+- **Pane** — `bg-panel` for action buttons, inherits `panel-foreground` for text
+- **Slider** — track uses `bg-accent`, thumb uses `bg-foreground`
+- **Tooltip** — inverted: `bg-foreground`, `text-background`
+
+## 3. Canvas rendering
+
+The canvas background is now driven by the `--canvas` CSS variable, read at render time via `getComputedStyle`. This means it automatically responds to light/dark mode and custom themes.
+
+Grid dots, selection UI, and other renderer constants are still hardcoded in `canvas/renderer.ts`:
+
+### Grid
+
+Look for the grid rendering function. Key values:
+
+- Grid line colour (default: light grey)
+- Grid spacing (default: 20px world units)
+- Major grid line interval
+
+### Selection UI
+
+- Selection box stroke colour (default: blue `#3b82f6`)
+- Resize handle fill/stroke
+- Marquee selection fill (semi-transparent blue)
+
+### Element defaults
+
+New element colours are set in `lib/element-factory.ts`. Each factory function defines default `fill` and `stroke` values.
+
+## 3. Component-level overrides with `cn()`
+
+Every Substrate component accepts `className` and spreads it via `cn()`. You can override specific styles per-instance:
+
+```tsx
+<Toolbar className="rounded-lg bg-zinc-900 border-zinc-800">
+  {/* Dark toolbar variant */}
+</Toolbar>
+
+<Panel position="left" className="w-72 bg-zinc-950">
+  {/* Wider, darker panel */}
+</Panel>
+```
+
+## 4. Cursor customisation
+
+Cursors are mapped in `design-canvas.tsx`'s `CURSOR_MAP`. You can swap these for custom cursor URLs:
+
+```ts
+const CURSOR_MAP: Record<string, string> = {
+  select: "default",
+  hand: "grab",
+  rectangle: "url(/cursors/crosshair.svg) 12 12, crosshair",
+  // ...
+}
+```
+
+## 5. Dark mode
+
+Substrate UI components automatically respect dark mode when using `next-themes` or a `.dark` class on the document. The canvas renderer needs manual dark mode handling — check a CSS variable or a store flag and swap your colour constants accordingly.
+
+## Related reference skills
+
+- **substrate-nodes** — port type CSS variables (7 port colours + 4 node chrome vars) follow the same fallback chain
+- **substrate-controls** — ColourPicker, SwatchPalette for colour selection in property panes

package/skills/wire-interactions/SKILL.md

@@ -0,0 +1,155 @@
+# Wire interactions
+
+Guide to connecting canvas pointer events, drag state, keyboard shortcuts, and the interaction state machine in Substrate.
+
+## Architecture overview
+
+Substrate's interaction system is a layered pipeline:
+
+```
+Pointer events (DOM)
+  → useCanvasInteraction (state machine)
+    → useCanvasDrag (drag tracking)
+    → useCanvasTransform (coordinate conversion)
+    → useHitTest (what's under the cursor)
+    → useDocumentStore (mutations)
+    → markDirty() → useCanvasRenderer (repaint)
+
+Keyboard events (DOM)
+  → useKeyboardShortcuts
+    → useToolStore (tool switching)
+    → useDocumentStore (delete, undo/redo, select all, duplicate)
+    → useCanvasTransform (zoom)
+```
+
+## The interaction state machine
+
+`useCanvasInteraction` is the central orchestrator. It manages an `InteractionMode`:
+
+| Mode | Triggered by | During move | On release |
+|---|---|---|---|
+| `idle` | Default state | Update hover, cursor | — |
+| `panning` | Middle-click, or hand tool drag | Update camera via `setCamera` | Return to idle |
+| `creating` | Drag with shape tool on empty canvas | Preview element dimensions | Commit new element to store |
+| `moving` | Drag on selected element | Update element positions | Commit positions |
+| `resizing` | Drag on resize handle | Update element bounds | Commit bounds |
+| `marquee_selecting` | Drag on empty canvas with select tool | Draw selection rectangle | Select contained elements |
+
+### Pointer down logic
+
+```
+1. Convert screen point → world point (useCanvasTransform)
+2. Check for resize handle hit (useHitTest)
+   → Yes: start "resizing" drag
+3. Check for element hit (useHitTest)
+   → Yes + already selected: start "moving" drag
+   → Yes + not selected: select it, start "moving" drag
+   → Yes + shift held: toggle selection
+4. No hit + shape tool active: start "creating" drag
+5. No hit + select tool: start "marquee_selecting" drag
+6. Middle button or hand tool: start "panning" drag
+```
+
+### Pointer move logic
+
+```
+1. If not dragging: update hover state via hit-test, return
+2. Convert to world coordinates
+3. Update drag state (useCanvasDrag.updateDrag)
+4. Based on drag type:
+   - "pan": update camera
+   - "create": preview element (stored on drag ref, rendered by renderer)
+   - "move": update element positions (delta from start)
+   - "resize": update element bounds respecting handle position
+   - "marquee": update selection rectangle
+5. Call markDirty() to trigger repaint
+```
+
+### Pointer up logic
+
+```
+1. End drag (useCanvasDrag.endDrag)
+2. Based on drag type:
+   - "create": push snapshot, add element to store, select it, reset tool to select
+   - "move"/"resize": push snapshot (positions already updated during drag)
+   - "marquee": select all elements within the marquee bounds
+   - "pan": nothing to commit
+```
+
+## Coordinate system
+
+Substrate uses two coordinate systems:
+
+- **Screen space** — pixel coordinates relative to the canvas element
+- **World space** — the infinite canvas coordinate system, affected by camera pan and zoom
+
+`useCanvasTransform` provides:
+
+- `screenToWorld(point)` — convert screen → world
+- `worldToScreen(point)` — convert world → screen
+- `pan(dx, dy)` — move camera
+- `zoomToPoint(point, delta)` — zoom centred on a point
+
+Always convert pointer event coordinates to world space before doing hit-testing or element manipulation.
+
+## The drag state machine
+
+`useCanvasDrag` tracks the current drag operation via a ref (not React state — avoids re-renders during high-frequency pointer moves):
+
+```ts
+interface DragInfo {
+  type: DragType           // "create" | "move" | "resize" | "marquee" | "pan"
+  startWorld: Point        // Where the drag began (world space)
+  startScreen: Point       // Where the drag began (screen space)
+  currentWorld: Point      // Current position (updated on every move)
+  currentScreen: Point
+  handle?: HandlePosition  // Which resize handle, if resizing
+  elementStartPositions?: Record<string, { x, y, width, height }>  // Snapshot for move/resize
+}
+```
+
+## Adding a custom interaction
+
+To add a new interaction pattern:
+
+1. **Define the mode** — add to `InteractionMode` in `types.ts` if it's a new state
+2. **Entry condition** — add detection in the pointer down handler
+3. **During drag** — add a case in pointer move
+4. **Completion** — add a case in pointer up
+5. **Always call `markDirty()`** after any visual change
+6. **Always call `pushSnapshot()`** before committing mutations (for undo/redo)
+
+## Keyboard shortcuts
+
+`useKeyboardShortcuts` listens globally on `window`. It:
+
+- Skips events when an input/textarea is focused
+- Supports modifier combinations (`meta+key`, `shift+key`)
+- Supports temporary tool switching (hold Space for hand tool, release to restore)
+
+To add a shortcut:
+
+```ts
+// In the handleKeyDown callback
+case "your-key": {
+  e.preventDefault()
+  // Your action
+  return
+}
+```
+
+For modifier combinations, check `meta` (which is `e.metaKey || e.ctrlKey` for cross-platform):
+
+```ts
+if (meta && e.key.toLowerCase() === "k") {
+  e.preventDefault()
+  // Cmd+K action
+  return
+}
+```
+
+## Related reference skills
+
+- **substrate-interaction** — full catalogue of useUndoable, useClipboard, createKeyboardShortcuts (declarative replacement for switch statements), and formatShortcut
+- **substrate-canvas** — useViewport, useSelection, useDragReorder, snap, boundingBox
+- **substrate-feedback** — CommandPalette (⌘K), ShortcutOverlay (?), ContextMenu, Toast (for delete-with-undo)