create-substrate 0.1.6 → 0.2.0

package/dist/utils/detect-pm.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect-pm.js","sourceRoot":"","sources":["../../src/utils/detect-pm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAIhC,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAkB;IAClD,OAAO,GAAG,EAAE,UAAU,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAkB,EAAE,MAAc;IAC9D,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,WAAW,MAAM,EAAE,CAAA;IAC5C,OAAO,GAAG,EAAE,IAAI,MAAM,EAAE,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"detect-pm.js","sourceRoot":"","sources":["../../src/utils/detect-pm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAIhC,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,KAAK,CAAA;AAC/D,CAAC;AAED,kFAAkF;AAClF,uEAAuE;AACvE,MAAM,UAAU,2BAA2B,CACzC,YAAgC,OAAO,CAAC,GAAG,CAAC,qBAAqB;IAEjE,MAAM,IAAI,GAAG,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACpD,OAAO,IAAI,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACrD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAkB;IAClD,OAAO,GAAG,EAAE,UAAU,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAkB,EAAE,MAAc;IAC9D,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,WAAW,MAAM,EAAE,CAAA;IAC5C,OAAO,GAAG,EAAE,IAAI,MAAM,EAAE,CAAA;AAC1B,CAAC"}

package/dist/utils/package-info.d.ts

@@ -0,0 +1,5 @@
+export declare const PACKAGE_ROOT: string;
+export declare const VERSION: string;
+export declare const CLI_RANGE: string;
+export declare function agentsSection(): string;
+//# sourceMappingURL=package-info.d.ts.map

package/dist/utils/package-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-info.d.ts","sourceRoot":"","sources":["../../src/utils/package-info.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,YAAY,QAA4D,CAAA;AAErF,eAAO,MAAM,OAAO,EAAE,MAEb,CAAA;AAKT,eAAO,MAAM,SAAS,QAA6C,CAAA;AAInE,wBAAgB,aAAa,IAAI,MAAM,CAGtC"}

package/dist/utils/package-info.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Both src/utils and dist/utils sit two levels below the package root
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8")).version;
+// The CLI version the generated project depends on. Keep in step with
+// packages/cli/package.json when it gains a new minor version.
+// SUBSTRATE_CLI_SPEC points it at a local tarball for testing before publish.
+export const CLI_RANGE = process.env.SUBSTRATE_CLI_SPEC ?? "^0.2.0";
+// Agent guidance shared with `substrate-kit init`; copied here by
+// scripts/sync-skills.mjs, with markers so `init` can refresh it later.
+export function agentsSection() {
+    const body = readFileSync(join(PACKAGE_ROOT, "templates", "agents-section.md"), "utf-8").trimEnd();
+    return `<!-- substrate:start -->\n${body}\n<!-- substrate:end -->\n`;
+}
+//# sourceMappingURL=package-info.js.map

package/dist/utils/package-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-info.js","sourceRoot":"","sources":["../../src/utils/package-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAErF,MAAM,CAAC,MAAM,OAAO,GAClB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CACrE,CAAC,OAAO,CAAA;AAET,sEAAsE;AACtE,+DAA+D;AAC/D,8EAA8E;AAC9E,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,QAAQ,CAAA;AAEnE,kEAAkE;AAClE,wEAAwE;AACxE,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,mBAAmB,CAAC,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;IAClG,OAAO,6BAA6B,IAAI,4BAA4B,CAAA;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrate",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Scaffold a Substrate creative tool playground",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "prepack": "node ../../scripts/sync-skills.mjs && npm run build",
-    "prepublishOnly": "npm --prefix ../.. run release:check"
+    "prepublishOnly": "node ../../scripts/release-stamp.mjs verify"
   },
   "dependencies": {
     "chalk": "^5.4.0",
@@ -23,7 +23,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "templates"
   ],
   "keywords": [
     "substrate",

package/skills/3d-scene/SKILL.md

@@ -173,6 +173,7 @@ Some examples of what this surface enables:
 
 ## Related reference skills
 
+- **scaffold-playground** — the craft rules and the checklist to run before you say it's done
 - **substrate-scaffold** — Toolbar, Panel, StatusBar, ZoomControls for the app shell
-- **substrate-controls** — NumberInput, Slider, ColourPicker, ActionControls for property panes
+- **substrate-controls** — NumberInput, Slider, ColourPicker, ActionControls for property panes; `useControls` for tuning material, light and camera values from one config object
 - **substrate-interaction** — useUndoable, useClipboard, createKeyboardShortcuts, TreeList for scene hierarchy

package/skills/animation/SKILL.md

@@ -195,6 +195,7 @@ Some examples of what this surface enables:
 
 ## Related reference skills
 
+- **scaffold-playground** — the craft rules and the checklist to run before you say it's done
 - **substrate-scaffold** — Toolbar, Panel, StatusBar for the app shell
-- **substrate-controls** — NumberInput, Slider, EasingCurveEditor, ActionControls for keyframe properties
+- **substrate-controls** — NumberInput, Slider, EasingCurveEditor, ActionControls for keyframe properties. For tuning UI motion by eye (entrances, springs, choreography), use `useControlsTimeline` with `<ControlsTimeline />` instead of building a timeline: define clips in code, bind `clip.current` to style, then copy the tuned values back. The `timeline` component is for editing user-authored keyframes.
 - **substrate-interaction** — useUndoable, createKeyboardShortcuts, LayerList for animation layers

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

@@ -19,7 +19,7 @@ This is Substrate's default surface. The `DesignCanvas` component provides a ful
 ### Install
 
 ```bash
-npx shadcn@latest add https://substrate.georgedrury.co.uk/r/design-canvas
+npx substrate-kit add design-canvas
 ```
 
 This pulls in the canvas renderer, hit-test system, interaction hooks, transform utilities, and all required stores.
@@ -85,27 +85,88 @@ The default tool set for a 2D canvas:
 
 ### Panels
 
-See the [composing panels](./composing-panels.md) skill for full details. In summary:
+See the `composing-panels` 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:
+See the `wire-interactions` 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 on the rotate handle → rotate (Shift snaps to 15°)
 - Drag with shape tool → create new element
 - Middle-click or hand tool → pan
 
+## State, undo and persistence
+
+`useDocumentStore` holds the board: `elements`, `elementOrder` (back to front), `camera`, `showGrid`, the selection and the history.
+
+- **Undo and redo cover elements and their order only.** Pan, zoom and the grid are view state, so undoing an edit never moves the viewport.
+- **Call `pushSnapshot()` before every mutation that should be undoable,** including property edits. For a scrub or drag, snapshot once at the start (`onStart`), not on every change.
+- **Composite actions** record their own undo step: `duplicateElements(ids?)` clones the selection (or the given ids), and `setElementOrder(ids)` replaces the stacking order. Call `pushSnapshot()` yourself before `setElementOrder`.
+- **Zoom** with `useCanvasTransform`: `setZoom(zoom)` and `zoomIn`/`zoomOut` zoom around the middle of the canvas, and `zoomToFit()` frames every visible element. Wire `ZoomControls` to `setZoom` and `zoomToFit`; setting `camera.zoom` directly zooms around the world origin and drifts.
+
+To remember the board across reloads, restore before the first render and save on change:
+
+```ts
+import { useDocumentStore, type DocumentSnapshot } from "@/stores/substrate/document-store"
+
+const KEY = "my-board"
+
+// Call before the first render so the saved board is there on first paint
+export function restoreBoard(): boolean {
+  const raw = localStorage.getItem(KEY)
+  if (!raw) return false
+  try {
+    useDocumentStore.getState().loadState(JSON.parse(raw) as DocumentSnapshot)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Returns an unsubscribe function
+export function persistBoard(): () => void {
+  let timer: number | undefined
+  return useDocumentStore.subscribe((state, prev) => {
+    const changed =
+      state.elements !== prev.elements ||
+      state.elementOrder !== prev.elementOrder ||
+      state.camera !== prev.camera ||
+      state.showGrid !== prev.showGrid
+    if (!changed) return
+    window.clearTimeout(timer)
+    timer = window.setTimeout(() => {
+      const snapshot: DocumentSnapshot = {
+        elements: state.elements,
+        elementOrder: state.elementOrder,
+        camera: state.camera,
+        showGrid: state.showGrid,
+      }
+      localStorage.setItem(KEY, JSON.stringify(snapshot))
+    }, 300)
+  })
+}
+```
+
+Selection and history are not saved, which is usually what you want. Seed a starter board with `addElement` only when `restoreBoard()` returns `false`, and give the starter shapes theme-safe colours.
+
+## Current limits
+
+- **Rotation** works on a single selection: drag the round handle above it (hold Shift to snap to 15°), and the box, handles and cursors turn with the shape. Resizing a rotated shape keeps the opposite corner fixed. Several selected elements can be moved and deleted but not rotated or resized together; there is no group transform.
+- **Text:** a click with the text tool makes a 160×32 note. Text is edited through a properties panel (`textStyle.content`); there is no on-canvas editing.
+- **Hidden and locked layers** (`visible: false`, `locked: true`) are skipped by hit-testing, so they can't be selected on the canvas.
+
 ## 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.
+To add a new element type (e.g. star, arrow, image), follow the `create-custom-tool` skill. The pipeline is: type definition → factory → renderer → hit-test → interaction → shortcut → cursor → toolbar.
 
 ### Custom rendering
 
@@ -117,7 +178,7 @@ For UI elements that sit on top of the canvas (selection indicators, context men
 
 ## 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.
+The canvas background is driven by the `--canvas` CSS variable, read at render time via `getComputedStyle`. Grid dots use `--canvas-foreground`. See the `theming` skill for the full token table.
 
 ## What to build
 
@@ -132,6 +193,7 @@ Some examples of what this surface enables:
 
 ## Related reference skills
 
+- **scaffold-playground** — the craft rules and the checklist to run before you say it's done
 - **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

package/skills/composing-panels/SKILL.md

@@ -27,10 +27,7 @@ Panel (side panel shell — left or right)
 ## 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
+npx substrate-kit add panel pane action slider
 ```
 
 ## Panel positioning

package/skills/data-visualisation/SKILL.md

@@ -229,6 +229,7 @@ Some examples of what this surface enables:
 
 ## Related reference skills
 
+- **scaffold-playground** — the craft rules and the checklist to run before you say it's done
 - **substrate-scaffold** — Toolbar, Panel, StatusBar, DocumentTabs for the app shell
-- **substrate-controls** — Select, NumberInput, Slider, ColourPicker for chart configuration
+- **substrate-controls** — `useControls` for chart settings from one config object (sliders, toggles, colours, selects); Select, NumberInput, Slider, ColourPicker when composing rows by hand
 - **substrate-feedback** — Toast, EmptyState, CommandPalette for data loading feedback

package/skills/image-generation/SKILL.md

@@ -167,7 +167,7 @@ Use Pane/Action/Slider to build parameter controls:
 - **Parameters pane** — sliders for inference steps, CFG scale, seed, image size selector
 - **Style pane** (optional) — style preset buttons, LoRA weight sliders
 
-The Action/ActionLabel/ActionControls pattern works well for each parameter row.
+For this kind of local, tunable state, prefer `useControlsController` with `<Controls />` over hand-built rows: one config object gives the sliders, selects and seed field, plus reset, versions and a copy button, and `setValues` loads a saved generation (see **substrate-controls**). Use the Action/ActionLabel/ActionControls pattern when a row needs a custom layout.
 
 ## Interaction patterns
 
@@ -211,6 +211,7 @@ Some examples of what this surface enables:
 
 ## Related reference skills
 
+- **scaffold-playground** — the craft rules and the checklist to run before you say it's done
 - **substrate-scaffold** — Toolbar, Panel, StatusBar for the app shell
 - **substrate-controls** — Slider, NumberInput, TextArea, Select for generation parameters
 - **substrate-feedback** — Toast, ProgressBar for generation status, EmptyState for no results

package/skills/install-components/SKILL.md

@@ -25,8 +25,8 @@ npx substrate-kit add slider number-input toggle colour-picker
 Install every component in a category:
 
 ```bash
-npx substrate-kit add --category substrate/ui/form
-npx substrate-kit add --category substrate/ui/control
+npx substrate-kit add --category form
+npx substrate-kit add --category control
 ```
 
 Open an interactive picker (no arguments):
@@ -45,16 +45,17 @@ npx substrate-kit add --list-categories
 
 - Run from a project created with `npx create-substrate` or initialised with `npx @substrate-kit/cli init`. Both add `@substrate-kit/cli` as a dev dependency, which is what makes `npx substrate-kit` resolve. The CLI looks for `components.json` — it will error if it's missing.
 - Components land in `registry/substrate/...` and related aliases defined in `components.json`.
-- Under the hood the CLI delegates to `npx shadcn@latest add` against `https://substrate.georgedrury.co.uk/r/<name>`. Do **not** use the shadcn CLI directly — always go through `substrate-kit add` so the CLI can print theme-override hints and keep the workflow uniform.
+- Under the hood the CLI delegates to `npx shadcn@latest add` against `https://substrate.georgedrury.co.uk/r/<name>`, in one call for all the names you give it, retrying if the network drops. Do **not** use the shadcn CLI directly — always go through `substrate-kit add` so the CLI can print theme-override hints and keep the workflow uniform.
+- If the Substrate MCP server is connected, `search_components`, `get_component`, `get_docs` and `install_components` do the same jobs without a shell.
 
 ### Related CLI commands
 
 | Command | What it does |
 | --- | --- |
 | `substrate-kit add <name>` | Install one or more components |
-| `substrate-kit docs <name>` | Read component docs in the terminal |
-| `substrate-kit browse <name>` | Open component docs in the browser |
-| `substrate-kit variables <name>` | Print the theme-override CSS variables for a component |
+| `substrate-kit docs <name>` | Read component docs in the terminal: props, theme variables, usage |
+| `substrate-kit docs <name> --open` | Open the component's docs page in the browser |
+| `substrate-kit docs --list` | List every component |
 
 ---
 
@@ -62,10 +63,11 @@ npx substrate-kit add --list-categories
 
 When you catch yourself about to write a custom version of any of these, stop and run `substrate-kit add <name>` instead.
 
-### Form controls — `substrate/ui/form`
+### Form controls — `form`
 
 | Component | Command | Use for |
 | --- | --- | --- |
+| Controls | `substrate-kit add controls` | Whole parameter panels from a config object (`useControls` + `<Controls />`) — reach for this before hand-wiring rows |
 | Slider | `substrate-kit add slider` | Any range input — opacity, volume, zoom, numeric sliders |
 | Number Input | `substrate-kit add number-input` | Numeric property fields with drag-to-scrub on the label |
 | Number Slider | `substrate-kit add number-slider` | Combined slider + numeric input on one row |
@@ -73,11 +75,13 @@ When you catch yourself about to write a custom version of any of these, stop an
 | Toggle | `substrate-kit add toggle` | Binary on/off switches (snap, visibility, lock) |
 | Text Area | `substrate-kit add text-area` | Auto-resizing multi-line text input |
 
-### Higher-level controls — `substrate/ui/control`
+### Higher-level controls — `control`
 
 | Component | Command | Use for |
 | --- | --- | --- |
 | Colour Picker | `substrate-kit add colour-picker` | HSV picker with hex/RGB + opacity |
+| XY Pad | `substrate-kit add xy-pad` | Drag or arrow-key pad that sets two values at once |
+| Image Picker | `substrate-kit add image-picker` | Thumbnail grid for choosing or uploading an image |
 | Swatch Palette | `substrate-kit add swatch-palette` | Grid of preset colours |
 | Alignment Controls | `substrate-kit add alignment-controls` | Horizontal/vertical align + distribute |
 | Collapsible Pane | `substrate-kit add collapsible-pane` | Expandable section inside a panel |
@@ -85,7 +89,7 @@ When you catch yourself about to write a custom version of any of these, stop an
 | Tree List | `substrate-kit add tree-list` | Hierarchical tree with expand/collapse and drag reorder |
 | Node | `substrate-kit add node` | Card-based node with typed input/output ports |
 
-### Chrome (app shell) — `substrate/ui/chrome`
+### Chrome (app shell) — `chrome`
 
 | Component | Command | Use for |
 | --- | --- | --- |
@@ -99,7 +103,7 @@ When you catch yourself about to write a custom version of any of these, stop an
 | Status Bar | `substrate-kit add status-bar` | Bottom bar for tool/selection/zoom info |
 | Zoom Controls | `substrate-kit add zoom-controls` | Zoom in/out/reset with percentage display |
 
-### Core UI — `substrate/ui`
+### Core UI — `ui`
 
 | Component | Command | Use for |
 | --- | --- | --- |
@@ -114,20 +118,22 @@ When you catch yourself about to write a custom version of any of these, stop an
 | Progress Bar | `substrate-kit add progress-bar` | Horizontal progress indicator |
 | Toast | `substrate-kit add toast` | Notifications with undo, powered by Sonner |
 
-### Animation — `substrate/ui/animation`
+### Animation — `animation`
 
 | Component | Command | Use for |
 | --- | --- | --- |
 | Timeline | `substrate-kit add timeline` | Ruler + playhead + tracks + keyframe diamonds |
 | Easing Curve Editor | `substrate-kit add easing-curve-editor` | Draggable cubic-bezier editor |
+| Spring Editor | `substrate-kit add spring-editor` | Spring curve preview with time or physics sliders |
+| Controls Timeline | `substrate-kit add controls-timeline` | Clips defined in code, tuned in a scrubbable timeline (`useControlsTimeline` + `<ControlsTimeline />`) |
 
-### Visualisation — `substrate/ui/visualization`
+### Visualisation — `visualization`
 
 | Component | Command | Use for |
 | --- | --- | --- |
 | Gallery | `substrate-kit add gallery` | Responsive thumbnail grid with selection and actions |
 
-### 2D canvas — `substrate/canvas`
+### 2D canvas — `canvas`
 
 | Component | Command | Use for |
 | --- | --- | --- |
@@ -136,7 +142,7 @@ When you catch yourself about to write a custom version of any of these, stop an
 | Hit Test | `substrate-kit add hit-test` | Point-in-element geometry |
 | Element Factory | `substrate-kit add element-factory` | Factories for rectangle/ellipse/text/etc |
 
-### Canvas hooks — `substrate/canvas` & `substrate/hook`
+### Canvas hooks — `canvas` and `hook`
 
 | Hook | Command | Use for |
 | --- | --- | --- |
@@ -152,7 +158,7 @@ When you catch yourself about to write a custom version of any of these, stop an
 | useViewport | `substrate-kit add use-viewport` | Pan/zoom state for canvas surfaces |
 | useUndoable | `substrate-kit add use-undoable` | Lightweight undo/redo stack |
 
-### Stores — `substrate/store`
+### Stores — `store`
 
 | Store | Command | Use for |
 | --- | --- | --- |
@@ -161,7 +167,7 @@ When you catch yourself about to write a custom version of any of these, stop an
 | panel-store | `substrate-kit add panel-store` | Left/right panel visibility, open panes |
 | animation-store | `substrate-kit add animation-store` | Playback: duration, time, play/pause |
 
-### Libraries — `substrate/lib`
+### Libraries — `lib`
 
 | Lib | Command | Use for |
 | --- | --- | --- |

package/skills/scaffold-playground/SKILL.md

@@ -14,13 +14,13 @@ A Substrate playground is a creative app built from composable primitives: a **s
 
 ## Prerequisites
 
-A Next.js 14+ project with Tailwind CSS and the shadcn CLI configured. If you don't have one, run:
+A Vite or Next.js project with React and Tailwind CSS v4. If you don't have one, run:
 
 ```bash
 npx create-substrate my-playground
 ```
 
-This scaffolds a full project with dependencies, globals.css with Substrate tokens, and a starter playground page.
+This scaffolds a Vite + React project with dependencies, `globals.css` with Substrate tokens, and a starter page for the surface you pick. It asks for a name and a surface; pass `--surface <type>` (or `--yes`) when there is no terminal.
 
 To add Substrate to an existing project instead:
 
@@ -28,7 +28,7 @@ To add Substrate to an existing project instead:
 npx @substrate-kit/cli init
 ```
 
-This installs skills, CLAUDE.md, components.json, and registers the MCP server.
+This detects Vite or Next, installs the skills, adds Substrate guidance to `CLAUDE.md` and `AGENTS.md` without touching the rest of them, adds the `@substrate` registry to `components.json`, and registers the MCP server in `.mcp.json`.
 
 ## 1. Choose your surface
 
@@ -36,11 +36,12 @@ The surface is the heart of the playground — the central area where the main i
 
 | Surface            | Best for                                                  | Skill                                         |
 | ------------------ | --------------------------------------------------------- | --------------------------------------------- |
-| 2D canvas          | Shape editors, diagrams, whiteboards, node graphs         | [canvas-2d](./canvas-2d.md)                   |
-| 3D scene           | Product viewers, scene builders, shader playgrounds       | [3d-scene](./3d-scene.md)                     |
-| Animation          | Timeline editors, motion prototyping, easing explorers    | [animation](./animation.md)                   |
-| Image generation   | Prompt-driven image tools, texture generators, inpainting | [image-generation](./image-generation.md)     |
-| Data visualisation | Chart editors, dashboard builders, data explorers         | [data-visualisation](./data-visualisation.md) |
+| 2D canvas          | Shape editors, diagrams, whiteboards, node graphs         | `canvas-2d`                   |
+| 3D scene           | Product viewers, scene builders, shader playgrounds       | `3d-scene`                     |
+| Animation          | Timeline editors, motion prototyping, easing explorers    | `animation`                   |
+| Image generation   | Prompt-driven image tools, texture generators, inpainting | `image-generation`     |
+| Data visualisation | Chart editors, dashboard builders, data explorers         | `data-visualisation` |
+| Node editor        | Visual programming, shader graphs, data pipelines         | `substrate-nodes`       |
 
 Read the relevant surface skill for setup instructions, dependencies, and architecture patterns.
 
@@ -50,17 +51,13 @@ Regardless of surface type, most playgrounds use the same chrome components:
 
 ```bash
 # UI chrome
-npx shadcn@latest add https://substrate.georgedrury.co.uk/r/toolbar
-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
+npx substrate-kit add toolbar panel pane action slider
 ```
 
 For the 2D canvas surface specifically, also install:
 
 ```bash
-npx shadcn@latest add https://substrate.georgedrury.co.uk/r/design-canvas
+npx substrate-kit add design-canvas
 ```
 
 ## 3. Compose the layout
@@ -77,7 +74,7 @@ import {
 	ToolbarToggle,
 	ToolbarSeparator,
 } from "@/components/substrate/toolbar"
-import { usePanelStore } from "@/stores/substrate/panel-store"
+import { usePanelStore } from "@/stores/substrate/panel-store" // npx substrate-kit add panel-store
 import { useToolStore } from "@/stores/substrate/tool-store"
 
 export default function PlaygroundPage() {
@@ -128,10 +125,33 @@ These are surface-agnostic — they work the same whether you're building a 3D s
 ## 5. Next steps
 
 - **Build your surface** — read the surface skill for your chosen type
-- **Add property panels** — see [composing panels](./composing-panels.md)
-- **Wire keyboard shortcuts** — see [wire interactions](./wire-interactions.md)
-- **Create custom tools** — see [create custom tool](./create-custom-tool.md)
-- **Customise appearance** — see [theming](./theming.md)
+- **Add property panels** — see `composing-panels`
+- **Wire keyboard shortcuts** — see `wire-interactions`
+- **Create custom tools** — see `create-custom-tool`
+- **Customise appearance** — see `theming`
+
+## 6. Craft rules
+
+Substrate tools are dense, so the details decide whether one feels finished. Apply these to everything you build, including your own components.
+
+- **Density:** chrome controls are 28px (`h-7`) with `text-xs`. Keep that. Don't enlarge inputs or buttons to fill space; a touch layout can use `size-9` or larger instead.
+- **Transitions:** name the properties (`transition-[color,background-color,box-shadow]`), never `transition-all`. Use about 150ms. Pressable buttons get `active:scale-[0.96]`, never below 0.95. Anything that moves must respect `prefers-reduced-motion`; the starter's `globals.css` already does.
+- **Depth:** panels are separated from the canvas by a border. Floating things (toolbar, popovers, menus) use a shadow, not a border. When a rounded child sits inside a rounded parent, its radius is the parent's minus the padding between them.
+- **Both themes:** use tokens (`bg-background`, `text-foreground`, `bg-muted`, `--canvas`), never hex values, in chrome. Content drawn on the board must be visible on both the light and the dark canvas, so check starter shapes and text in both. The element factories' default ink is safe; a hard-coded navy title is invisible on dark.
+- **Changing numbers** (zoom, coordinates, counts, timers) get `tabular-nums`, so digits don't jiggle as they update.
+- **No layout shift:** reserve space for anything that loads or appears. Empty states teach: say what goes there and give the action that creates it, using `EmptyState`.
+- **Keyboard:** every tool and action has a shortcut, listed in `ShortcutOverlay`. `DesignCanvas` already installs tool keys, undo, redo, delete, duplicate, select all and zoom, so don't register those again: they would run twice.
+- **Labels:** every icon-only button has an `aria-label`. Leave focus rings visible and neutral.
+- **First paint:** restore saved state before the first render. Defaulting first and correcting afterwards flashes the wrong state.
+
+### Before you say it's done
+
+1. `npm run build` passes and the console is clean.
+2. Open it in light and dark and look at it. Starter content, text and borders must be readable in both.
+3. Make each kind of edit, then undo and redo it: move, resize, create, delete, property changes, reorder. Pan or zoom after an edit and undo again; the view must stay put.
+4. Tab through the controls, and use every shortcut you listed.
+5. Reload. The board and the zoom come back.
+6. Click-create each tool without dragging, with a long name and with many layers.
 
 ## Component reference skills
 

package/skills/substrate-canvas/SKILL.md

@@ -156,6 +156,11 @@ Core geometry functions.
 | `screenToWorld(point, camera)` / `worldToScreen(point, camera)` | Coordinate transforms |
 | `clamp(value, min, max)` | Numeric clamp |
 | `distance(a, b)` | Euclidean distance |
+| `angleBetween(from, to)` / `normalizeAngle(deg)` / `snapAngle(deg, step)` | Angle of a line, wrapped to [-180, 180), snapped to a step. Degrees, positive clockwise on screen |
+| `rotatedCorners(bounds, rotation)` / `rotatedBounds(bounds, rotation)` | The corners of a rotated box, and the axis-aligned box that contains it (for marquee, fit and alignment) |
+| `handlePosition(handle, bounds, rotation)` | Where a resize handle, or `"rotate"`, sits on a rotated box |
+| `resizeBounds(start, handle, delta, rotation)` | Resize by dragging a handle. The opposite handle stays fixed, also when rotated |
+| `HANDLE_SIZE`, `ROTATE_HANDLE_OFFSET`, `HANDLES` | Handle geometry shared by the renderer and hit-test |
 
 ---
 

package/skills/substrate-controls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Substrate input and selection primitives and config-driven panels: Controls and useControls (describe parameters as an object, get a tuning panel), the controls timeline for tuning animation clips, number input, slider, number slider, select, toggle, text area, colour picker, easing curve editor, spring editor, XY pad, image picker, swatch palette, and action controls. Use when building property editors, parameter or settings panels, tuning values by eye, or any interactive control surface. Triggers on: useControls, Controls, controls panel, tweak values, tuning, parameters, input, slider, select, toggle, colour picker, spring, easing, XY pad, swatch, action controls, property editor, form control, useControlsTimeline."
 user-invocable: true
 ---
 
@@ -61,6 +61,61 @@ The same pattern is used by **Toolbar** (compaction) and **PaneHeader** (auto-po
 
 ## Components in this domain
 
+### Controls and useControls
+
+`registry/substrate/components/controls.tsx`, `registry/substrate/hooks/use-controls.ts`
+
+Config-driven panels. Describe parameters as an object, get typed values back, and render every panel with `<Controls />`. Built on DialKit's headless store; the rows are the Substrate controls below.
+
+```tsx
+const chart = useControls("Chart", {
+	months: [12, 3, 12, 1], // [default, min, max, step]
+	grid: true,
+	colour: "#a78bfa",
+	metric: { type: "select", options: ["revenue", "users"] },
+	style: { strokeWidth: [2, 1, 6] }, // nested object = collapsible folder
+})
+
+<Panel>
+	<Controls />
+</Panel>
+```
+
+**Config types**: number tuple or bare number (NumberSlider), boolean (Toggle), string (TextArea), hex string (ColourPicker), `{ type: "select" }`, `{ type: "easing" }` (EasingCurveEditor), `{ type: "spring" }` with `visualDuration`/`bounce` or `stiffness`/`damping`/`mass` (SpringEditor; easing and spring share a row with a type switch), `{ type: "image", options }` (ImagePicker, uploads become data URLs), `{ type: "pad", x, y }` with slider-style axis tuples (XYPad, returns `{ x, y }`, positive y is up), `{ type: "action" }` with the `onAction` option, nested object (folder).
+
+**Options**: `id`, `persist`, `onAction`, `shortcuts` (by control path, e.g. `{ radius: { key: "r" }, visible: { key: "v" } }`: hold a slider's key and scroll, or `interaction: "drag"`/`"move"`; press a toggle's key). **Controls prop**: `panel` to render a single panel by name. Each panel header has a versions menu (DialKit presets), a copy button that copies the values as an agent instruction, and reset.
+
+**Setting values from code**: `useControlsController` returns `{ values, setValues, reset }` for loading saved state or presets.
+
+**Values that belong to a selection**: mount a small component with `key={selected.id}` that seeds its config from the selected item (hold it in `useState` so it is built once) and writes `useControls` values back in an effect. Only do this when nothing else edits those values while the item is selected.
+
+**When to use**: The default for any panel of tunable parameters with local state – chart settings, generation parameters, material properties. Compose the individual controls by hand instead when values live in a store with selection and undo (as in the design editor's property panes), or when a row needs a custom layout.
+
+---
+
+### ControlsTimeline and useControlsTimeline
+
+`registry/substrate/components/controls-timeline.tsx`, `registry/substrate/hooks/use-controls-timeline.ts`
+
+Animation clips defined in code, tuned in a timeline editor. Built on DialKit's headless timeline. Bind `timeline.<clip>.current` to style so the UI follows the playhead; `<ControlsTimeline />` scrubs, moves and resizes clips and edits their values in a popover.
+
+```tsx
+const timeline = useControlsTimeline("Card", {
+	enter: { at: 0, duration: 0.6, from: { y: 24, opacity: 0 }, to: { y: 0, opacity: 1 }, transition: { type: "spring", visualDuration: 0.5, bounce: 0.2 } },
+	badge: { at: 0.6, from: { scale: 0 }, steps: [{ duration: 0.2, to: { scale: 1.2 } }, { duration: 0.2, to: { scale: 1 } }] },
+	glow: { at: 1, props: { blur: { from: 0, to: 24, duration: 0.6 } } },
+}, { loop: true })
+
+<div style={{ opacity: timeline.enter.current.opacity }} />
+<ControlsTimeline />
+```
+
+**Options**: `id`, `persist`, `autoplay` (default true), `loop` (`true` or `{ from }`). **Controls**: `play`, `pause`, `replay`, `seek`.
+
+**When to use**: tuning entrance and choreography timing by eye. Once tuned, copy the values and move them into the production animation.
+
+---
+
 ### NumberInput
 
 `registry/substrate/components/number-input.tsx`
@@ -131,7 +186,7 @@ Auto-resizing textarea with `minRows` / `maxRows`. Shares border/bg styling with
 
 `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.
+Colour picker with a hex input. `value` accepts any CSS colour (hex, `oklch()`, `rgb()`, named) and `onChange` returns hex; `onStart` fires when a drag or edit begins, for undo snapshots. The swatch trigger renders `data-slot="colour-swatch"` for slot-aware composition.
 
 **When to use**: Fill, stroke, background, text colour – any colour property.