@substrate-kit/cli 0.1.2 → 0.2.0

package/docs/utilities/bounding-box.mdx

@@ -0,0 +1,76 @@
+---
+title: Bounding box
+description: Compute union bounds, intersections, and containment checks.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/bounding-box
+```
+
+## Usage
+
+```ts
+import {
+  boundingBox,
+  expandBounds,
+  containsPoint,
+  intersectBounds,
+} from "@/lib/substrate/bounding-box"
+
+// Union of multiple element bounds
+const union = boundingBox([
+  { x: 0, y: 0, width: 100, height: 50 },
+  { x: 80, y: 30, width: 60, height: 40 },
+])
+// → { x: 0, y: 0, width: 140, height: 70 }
+
+// Add padding
+const padded = expandBounds(union!, 20)
+// → { x: -20, y: -20, width: 180, height: 110 }
+
+// Hit testing
+containsPoint(union!, { x: 50, y: 25 }) // → true
+
+// Intersection
+intersectBounds(
+  { x: 0, y: 0, width: 100, height: 100 },
+  { x: 50, y: 50, width: 100, height: 100 },
+)
+// → { x: 50, y: 50, width: 50, height: 50 }
+```
+
+## Functions
+
+### `boundingBox(items)`
+
+Computes the union bounding box of an array of `Bounds`. Returns `null` if the array is empty.
+
+### `boundingBoxFromPoints(points)`
+
+Computes the bounding box from an array of `Point` values. Returns `null` if the array is empty.
+
+### `expandBounds(bounds, padding)`
+
+Expands a bounding box by `padding` pixels on every side. Negative values contract.
+
+### `expandBoundsBy(bounds, { top?, right?, bottom?, left? })`
+
+Expands with independent padding per side.
+
+### `containsPoint(bounds, point)`
+
+Returns `true` if the point lies inside the bounds.
+
+### `containsBounds(a, b)`
+
+Returns `true` if bounds `a` fully contains bounds `b`.
+
+### `boundsCenter(bounds)`
+
+Returns the centre `{ x, y }` of a bounding box.
+
+### `intersectBounds(a, b)`
+
+Returns the intersection of two bounds, or `null` if they don't overlap.

package/docs/utilities/keyboard-shortcuts.mdx

@@ -0,0 +1,64 @@
+---
+title: createKeyboardShortcuts
+description: Declarative keyboard shortcut registration replacing switch statements.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/keyboard-shortcuts
+```
+
+## Usage
+
+```tsx
+import {
+  createKeyboardShortcuts,
+  formatShortcut,
+} from "@/lib/substrate/keyboard-shortcuts"
+
+// Register shortcuts – returns a dispose function
+const dispose = createKeyboardShortcuts([
+  { key: "z", meta: true, handler: undo, label: "Undo", group: "Edit" },
+  { key: "z", meta: true, shift: true, handler: redo, label: "Redo", group: "Edit" },
+  { key: "Delete", handler: deleteSelected, label: "Delete", group: "Edit" },
+  { key: "a", meta: true, handler: selectAll, label: "Select all", group: "Selection" },
+  { key: "0", meta: true, handler: resetZoom, label: "Reset zoom", group: "View" },
+])
+
+// Later, when unmounting:
+dispose()
+```
+
+## Features
+
+Each shortcut entry declares the key and modifiers it responds to. The first matching shortcut wins – so more specific shortcuts (e.g. ⌘+Shift+Z) should be listed before less specific ones (⌘+Z).
+
+By default, shortcuts are ignored when focus is inside an `<input>`, `<textarea>`, or `contentEditable` element. Set `ignoreInputs: false` on a specific entry to override this.
+
+The `formatShortcut` helper converts an entry into a human-readable string for display in toolbars and overlays – e.g. `{ key: "z", meta: true, shift: true }` becomes `"⌘+Shift+Z"`.
+
+## API
+
+### `createKeyboardShortcuts(shortcuts, options?)`
+
+Returns a dispose function that removes the event listener.
+
+### ShortcutEntry
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `key` | `string` | — | The key value (e.g. `"z"`, `"Delete"`, `"ArrowUp"`) |
+| `meta` | `boolean` | `false` | Require ⌘/Ctrl |
+| `ctrl` | `boolean` | `false` | Require Ctrl specifically |
+| `shift` | `boolean` | `false` | Require Shift |
+| `alt` | `boolean` | `false` | Require Alt/Option |
+| `handler` | `(e: KeyboardEvent) => void` | — | Callback |
+| `preventDefault` | `boolean` | `true` | Call `e.preventDefault()` |
+| `ignoreInputs` | `boolean` | `true` | Skip when focus is in an input |
+| `label` | `string` | — | Human-readable label for UI |
+| `group` | `string` | — | Group name for UI |
+
+### `formatShortcut(shortcut)`
+
+Returns a formatted string like `"⌘+Shift+Z"` or `"Alt+↑"`.

package/docs/utilities/snap.mdx

@@ -0,0 +1,73 @@
+---
+title: Snap
+description: Grid snapping and smart edge snapping for canvas surfaces.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/snap
+```
+
+## Usage
+
+### Grid snapping
+
+```ts
+import { snapToGrid, snapValueToGrid } from "@/lib/substrate/snap"
+
+snapToGrid({ x: 37, y: 63 }, 10)
+// → { x: 40, y: 60 }
+
+snapToGrid({ x: 37, y: 63 }, 10, { origin: { x: 5, y: 5 } })
+// → { x: 35, y: 65 }
+
+snapValueToGrid(37, 10) // → 40
+```
+
+### Guide snapping
+
+```ts
+import { snapToGuides, guidesFromBounds } from "@/lib/substrate/snap"
+
+// Generate guides from sibling elements
+const guides = guidesFromBounds(otherElements.map((el) => el.bounds))
+
+// Snap the dragged element's position
+const result = snapToGuides(dragPosition, guides, { threshold: 5 })
+
+result.point // → snapped { x, y }
+result.snappedGuides // → which guides were hit (for rendering snap lines)
+```
+
+## Functions
+
+### `snapToGrid(point, gridSize, options?)`
+
+Rounds a point to the nearest grid intersection. An optional `origin` shifts the grid.
+
+### `snapValueToGrid(value, gridSize, origin?)`
+
+Snaps a single number to the nearest grid line.
+
+### `snapToGuides(point, guides, options?)`
+
+Snaps a point to nearby guide lines. Each axis snaps independently – only if a guide is within the `threshold` distance (default 5px). Returns the snapped point and an array of matched guides, which is useful for rendering alignment lines.
+
+### `guidesFromBounds(boundsList, exclude?)`
+
+Generates alignment guides from an array of bounding boxes. Creates six guides per box – left edge, horizontal centre, right edge, top edge, vertical centre, bottom edge. Pass the element being dragged as `exclude` to avoid self-snapping.
+
+## Types
+
+```ts
+type Guide = {
+  axis: "x" | "y"
+  value: number
+}
+
+type SnapResult = {
+  point: Point
+  snappedGuides: Guide[]
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@substrate-kit/cli",
-	"version": "0.1.2",
-	"description": "Scaffold interactive canvas playgrounds with Substrate primitives",
+	"version": "0.2.0",
+	"description": "Add Substrate components, skills and docs to a project, with an MCP server for agents",
 	"type": "module",
 	"bin": {
 		"substrate-kit": "./dist/index.js"
@@ -9,8 +9,8 @@
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsx src/index.ts",
-		"prepack": "cp ../../registry.json registry.json && npm run build",
-		"prepublishOnly": "npm --prefix ../.. run release:check"
+		"prepack": "node ../../scripts/bundle-cli-assets.mjs && npm run build",
+		"prepublishOnly": "node ../../scripts/release-stamp.mjs verify"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.28.0",
@@ -26,6 +26,8 @@
 	"files": [
 		"dist",
 		"skills",
+		"templates",
+		"docs",
 		"registry.json",
 		".claude-plugin"
 	],

package/registry.json

@@ -32,7 +32,7 @@
       "name": "math",
       "type": "registry:lib",
       "title": "Math",
-      "description": "Geometry helpers — rotate point, bounds checking, ellipse hit test, screen/world coordinate conversion, normalize bounds, distance, and clamping.",
+      "description": "Geometry helpers — rotate point, bounds checking, ellipse hit test, screen/world coordinate conversion, normalize bounds, distance, clamping, plus rotation and handle maths: rotated bounds, snap angle, and resizing a rotated box.",
       "author": "George Drury <info@georgedrury.co.uk>",
       "categories": [
         "substrate",
@@ -120,7 +120,8 @@
         "zustand"
       ],
       "registryDependencies": [
-        "https://substrate.georgedrury.co.uk/r/types"
+        "https://substrate.georgedrury.co.uk/r/types",
+        "https://substrate.georgedrury.co.uk/r/id"
       ],
       "meta": {
         "lineage": [
@@ -239,7 +240,8 @@
         "canvas"
       ],
       "registryDependencies": [
-        "https://substrate.georgedrury.co.uk/r/types"
+        "https://substrate.georgedrury.co.uk/r/types",
+        "https://substrate.georgedrury.co.uk/r/math"
       ],
       "meta": {
         "lineage": [
@@ -326,7 +328,8 @@
       "registryDependencies": [
         "https://substrate.georgedrury.co.uk/r/types",
         "https://substrate.georgedrury.co.uk/r/math",
-        "https://substrate.georgedrury.co.uk/r/document-store"
+        "https://substrate.georgedrury.co.uk/r/document-store",
+        "https://substrate.georgedrury.co.uk/r/bounding-box"
       ],
       "meta": {
         "lineage": [
@@ -489,7 +492,9 @@
         "https://substrate.georgedrury.co.uk/r/tool-store",
         "https://substrate.georgedrury.co.uk/r/use-canvas-renderer",
         "https://substrate.georgedrury.co.uk/r/use-canvas-interaction",
-        "https://substrate.georgedrury.co.uk/r/use-keyboard-shortcuts"
+        "https://substrate.georgedrury.co.uk/r/use-keyboard-shortcuts",
+        "https://substrate.georgedrury.co.uk/r/document-store",
+        "https://substrate.georgedrury.co.uk/r/types"
       ],
       "cssVars": {
         "theme": {
@@ -1480,7 +1485,7 @@
       "name": "layer-list",
       "type": "registry:ui",
       "title": "Layer List",
-      "description": "Sortable layer panel with visibility and lock toggles, icons, and context menu support. Compound component pattern.",
+      "description": "Layer panel with selection, visibility and lock toggles, icons and inline rename. Compound component pattern; pair with use-drag-reorder to sort and context-menu for right-click actions.",
       "categories": [
         "substrate",
         "ui",
@@ -1981,6 +1986,269 @@
         }
       ],
       "author": "George Drury <info@georgedrury.co.uk>"
+    },
+    {
+      "name": "spring",
+      "type": "registry:lib",
+      "title": "Spring",
+      "description": "Spring physics utilities: convert time-based springs (duration, bounce) to stiffness, damping and mass, and sample their progress over time.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "lib",
+        "animation"
+      ],
+      "meta": {
+        "lineage": [
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/lib/spring.ts",
+          "type": "registry:lib",
+          "target": "lib/substrate/spring.ts"
+        }
+      ]
+    },
+    {
+      "name": "spring-editor",
+      "type": "registry:ui",
+      "title": "Spring Editor",
+      "description": "Spring curve preview with duration and bounce, or stiffness, damping and mass sliders. Used for spring transitions in animation tools.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "ui",
+        "animation"
+      ],
+      "cssVars": {
+        "theme": {
+          "color-spring-curve": "var(--spring-curve, var(--color-primary))"
+        },
+        "light": {},
+        "dark": {}
+      },
+      "meta": {
+        "example": "<SpringEditor value={{ type: \"spring\", visualDuration: 0.3, bounce: 0.2 }} onChange={setSpring} />",
+        "lineage": [
+          {
+            "name": "DialKit",
+            "href": "https://github.com/joshpuckett/dialkit"
+          },
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/components/spring-editor.tsx",
+          "type": "registry:ui",
+          "target": "components/substrate/spring-editor.tsx"
+        }
+      ],
+      "registryDependencies": [
+        "https://substrate.georgedrury.co.uk/r/action",
+        "https://substrate.georgedrury.co.uk/r/number-slider",
+        "https://substrate.georgedrury.co.uk/r/toggle-group",
+        "https://substrate.georgedrury.co.uk/r/spring"
+      ]
+    },
+    {
+      "name": "xy-pad",
+      "type": "registry:ui",
+      "title": "XY Pad",
+      "description": "Two-dimensional pad for setting two values at once by dragging or with the arrow keys. Used for offsets, positions and paired parameters.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "ui",
+        "form"
+      ],
+      "cssVars": {
+        "theme": {
+          "color-xy-pad-handle": "var(--xy-pad-handle, var(--color-primary))"
+        },
+        "light": {},
+        "dark": {}
+      },
+      "meta": {
+        "example": "<XYPad value={offset} onChange={setOffset} x={{ min: -50, max: 50, step: 1 }} y={{ min: -50, max: 50, step: 1 }} />",
+        "lineage": [
+          {
+            "name": "DialKit",
+            "href": "https://github.com/joshpuckett/dialkit"
+          },
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/components/xy-pad.tsx",
+          "type": "registry:ui",
+          "target": "components/substrate/xy-pad.tsx"
+        }
+      ]
+    },
+    {
+      "name": "image-picker",
+      "type": "registry:ui",
+      "title": "Image Picker",
+      "description": "Thumbnail grid for choosing an image from a list, with upload and drag-and-drop. Uploads become data URLs.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "ui",
+        "form"
+      ],
+      "cssVars": {
+        "theme": {
+          "color-image-picker-selection": "var(--image-picker-selection, var(--color-primary))"
+        },
+        "light": {},
+        "dark": {}
+      },
+      "meta": {
+        "example": "<ImagePicker value={image} onChange={setImage} options={[\"/a.jpg\", \"/b.jpg\"]} />",
+        "lineage": [
+          {
+            "name": "DialKit",
+            "href": "https://github.com/joshpuckett/dialkit"
+          },
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/components/image-picker.tsx",
+          "type": "registry:ui",
+          "target": "components/substrate/image-picker.tsx"
+        }
+      ],
+      "dependencies": [
+        "@remixicon/react"
+      ]
+    },
+    {
+      "name": "controls",
+      "type": "registry:ui",
+      "title": "Controls",
+      "description": "Config-driven control panels — describe parameters as an object with useControls and render them with Controls, built on DialKit's store.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "ui",
+        "form"
+      ],
+      "dependencies": [
+        "dialkit",
+        "@remixicon/react"
+      ],
+      "meta": {
+        "example": "const values = useControls(\"Card\", { radius: [24, 0, 64], visible: true })\n<Panel><Controls /></Panel>",
+        "lineage": [
+          {
+            "name": "DialKit",
+            "href": "https://github.com/joshpuckett/dialkit"
+          },
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/components/controls.tsx",
+          "type": "registry:ui",
+          "target": "components/substrate/controls.tsx"
+        },
+        {
+          "path": "registry/substrate/hooks/use-controls.ts",
+          "type": "registry:hook",
+          "target": "hooks/substrate/use-controls.ts"
+        },
+        {
+          "path": "registry/substrate/lib/controls-shortcuts.ts",
+          "type": "registry:lib",
+          "target": "lib/substrate/controls-shortcuts.ts"
+        }
+      ],
+      "registryDependencies": [
+        "https://substrate.georgedrury.co.uk/r/pane",
+        "https://substrate.georgedrury.co.uk/r/collapsible-pane",
+        "https://substrate.georgedrury.co.uk/r/action",
+        "https://substrate.georgedrury.co.uk/r/number-slider",
+        "https://substrate.georgedrury.co.uk/r/number-input",
+        "https://substrate.georgedrury.co.uk/r/toggle",
+        "https://substrate.georgedrury.co.uk/r/select",
+        "https://substrate.georgedrury.co.uk/r/colour-picker",
+        "https://substrate.georgedrury.co.uk/r/text-area",
+        "https://substrate.georgedrury.co.uk/r/easing-curve-editor",
+        "https://substrate.georgedrury.co.uk/r/toggle-group",
+        "https://substrate.georgedrury.co.uk/r/spring-editor",
+        "https://substrate.georgedrury.co.uk/r/xy-pad",
+        "https://substrate.georgedrury.co.uk/r/image-picker",
+        "https://substrate.georgedrury.co.uk/r/spring",
+        "https://substrate.georgedrury.co.uk/r/popover"
+      ]
+    },
+    {
+      "name": "controls-timeline",
+      "type": "registry:ui",
+      "title": "Controls Timeline",
+      "description": "Animation clips defined in code with useControlsTimeline, tuned in a timeline editor: scrub, move and resize clips, and edit their values. Built on DialKit's headless timeline.",
+      "author": "George Drury <info@georgedrury.co.uk>",
+      "categories": [
+        "substrate",
+        "ui",
+        "animation"
+      ],
+      "dependencies": [
+        "dialkit",
+        "@remixicon/react"
+      ],
+      "cssVars": {
+        "theme": {
+          "color-timeline-clip": "var(--timeline-clip, var(--color-primary))"
+        },
+        "light": {},
+        "dark": {}
+      },
+      "meta": {
+        "example": "const timeline = useControlsTimeline(\"Card\", { enter: { at: 0, duration: 0.6, from: { y: 24 }, to: { y: 0 } } })\n<ControlsTimeline />",
+        "lineage": [
+          {
+            "name": "DialKit",
+            "href": "https://github.com/joshpuckett/dialkit"
+          },
+          {
+            "name": "Substrate"
+          }
+        ]
+      },
+      "files": [
+        {
+          "path": "registry/substrate/components/controls-timeline.tsx",
+          "type": "registry:ui",
+          "target": "components/substrate/controls-timeline.tsx"
+        },
+        {
+          "path": "registry/substrate/hooks/use-controls-timeline.ts",
+          "type": "registry:hook",
+          "target": "hooks/substrate/use-controls-timeline.ts"
+        }
+      ],
+      "registryDependencies": [
+        "https://substrate.georgedrury.co.uk/r/controls",
+        "https://substrate.georgedrury.co.uk/r/popover"
+      ]
     }
   ]
 }

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