@substrate-kit/cli 0.1.1 → 0.2.0

package/docs/hooks/use-viewport.mdx

@@ -0,0 +1,75 @@
+---
+title: useViewport
+description: Pan and zoom state management for canvas surfaces.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/use-viewport
+```
+
+## Usage
+
+```tsx
+import { useViewport } from "@/hooks/substrate/use-viewport"
+
+function Canvas() {
+  const {
+    viewport,
+    handleWheel,
+    toWorld,
+    toScreen,
+    zoomIn,
+    zoomOut,
+    resetZoom,
+    zoomToFit,
+  } = useViewport({ minZoom: 0.1, maxZoom: 10 })
+
+  return (
+    <div onWheel={handleWheel} style={{ overflow: "hidden" }}>
+      <div
+        style={{
+          transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
+          transformOrigin: "0 0",
+        }}
+      >
+        {/* Canvas content */}
+      </div>
+    </div>
+  )
+}
+```
+
+## Features
+
+This is a surface-agnostic extraction of pan/zoom logic. It manages `{ x, y, zoom }` state and provides coordinate transforms between screen and world space. The `handleWheel` callback supports two modes – plain scroll for panning and Ctrl/⌘ + scroll for pinch-zoom – keeping the world point under the cursor stationary during zoom.
+
+The hook uses refs internally so that callbacks like `toWorld` and `toScreen` remain referentially stable across renders.
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `initial` | `Partial<Viewport>` | `{ x: 0, y: 0, zoom: 1 }` | Initial viewport state |
+| `minZoom` | `number` | `0.1` | Minimum zoom level |
+| `maxZoom` | `number` | `10` | Maximum zoom level |
+| `zoomFactor` | `number` | `1.2` | Multiplier for `zoomIn` / `zoomOut` |
+
+### Returns
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `viewport` | `Viewport` | Current `{ x, y, zoom }` state |
+| `setViewport` | `(v: Viewport) => void` | Set viewport directly |
+| `toWorld` | `(screenX, screenY) => Point` | Convert screen coordinates to world |
+| `toScreen` | `(worldX, worldY) => Point` | Convert world coordinates to screen |
+| `pan` | `(dx, dy) => void` | Pan by a screen-space delta |
+| `zoomToPoint` | `(screenX, screenY, zoom) => void` | Zoom keeping a screen point stationary |
+| `zoomIn` | `(screenX?, screenY?) => void` | Zoom in by `zoomFactor` |
+| `zoomOut` | `(screenX?, screenY?) => void` | Zoom out by `zoomFactor` |
+| `resetZoom` | `() => void` | Reset to `{ x: 0, y: 0, zoom: 1 }` |
+| `zoomToFit` | `(bounds, padding?) => void` | Fit a bounding box into the viewport |
+| `handleWheel` | `(e: WheelEvent) => void` | Attach to your container's `onWheel` |

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.1",
-	"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,7 +9,8 @@
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsx src/index.ts",
-		"prepack": "npm run build"
+		"prepack": "node ../../scripts/bundle-cli-assets.mjs && npm run build",
+		"prepublishOnly": "node ../../scripts/release-stamp.mjs verify"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.28.0",
@@ -25,6 +26,8 @@
 	"files": [
 		"dist",
 		"skills",
+		"templates",
+		"docs",
 		"registry.json",
 		".claude-plugin"
 	],