@substrate-kit/cli 0.1.1 → 0.2.0

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
@@ -70,15 +67,15 @@ Every playground follows the same layout pattern — surface in the centre, opti
 ```tsx
 "use client"
 
-import { Panel } from "@/registry/substrate/components/panel"
+import { Panel } from "@/components/substrate/panel"
 import {
 	Toolbar,
 	ToolbarToggleGroup,
 	ToolbarToggle,
 	ToolbarSeparator,
-} from "@/registry/substrate/components/toolbar"
-import { usePanelStore } from "@/registry/substrate/stores/panel-store"
-import { useToolStore } from "@/registry/substrate/stores/tool-store"
+} from "@/components/substrate/toolbar"
+import { usePanelStore } from "@/stores/substrate/panel-store" // npx substrate-kit add panel-store
+import { useToolStore } from "@/stores/substrate/tool-store"
 
 export default function PlaygroundPage() {
 	const leftPanel = usePanelStore((s) => s.leftPanel)
@@ -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.
 

package/skills/substrate-interaction/SKILL.md

@@ -45,7 +45,7 @@ function handleMove(id: string, x: number, y: number) {
 }
 ```
 
-**Connects to**: `HistoryControls` component, `NumberInput.onStart` (push snapshot before scrub), `createKeyboardShortcuts` (⌘Z / ⌘⇧Z).
+**Connects to**: `NumberInput.onStart` (push snapshot before scrub), `createKeyboardShortcuts` (⌘Z / ⌘⇧Z). The 2D canvas does not use this hook: `useDocumentStore` has its own history (`pushSnapshot`, `undo`, `redo`) that covers elements and their order, not the camera, so pan and zoom survive an undo. Call `pushSnapshot()` before every mutation you want to be undoable, including property edits.
 
 ---
 
@@ -139,7 +139,7 @@ formatShortcut({ key: "z", meta: true, shift: true }) // → "⌘+Shift+Z"
 
 Undo/redo button pair. Renders `data-slot="history-controls"` for auto-positioning in PaneHeader and Toolbar.
 
-**Props**: `canUndo`, `canRedo`, `onUndo`, `onRedo`
+**Props**: `size` (`"sm"` or `"md"`). It takes no undo callbacks: it reads `past`/`future` and calls `undo`/`redo` on `useDocumentStore`, so it works with the canvas store out of the box. For any other undo stack (`useUndoable`), build your own pair of buttons from `canUndo`/`undo`/`canRedo`/`redo`.
 
 **Typical placement**:
 - Inside `PaneHeader` – auto-positioned to the right via `**:data-[slot=history-controls]:ml-auto`
@@ -157,7 +157,9 @@ Flat layer panel with selection, visibility, lock, rename, and reorder.
 
 **Features**:
 - `LayerItem` supports `selected`, `hovered`, `depth` props
-- `LayerName` enables double-click inline rename
+- `LayerName` takes the name as `children` and enables double-click inline rename via `onRename`
+- `LayerVisibilityToggle` and `LayerLockToggle` are controlled: `visible`/`onVisibleChange` and `locked`/`onLockedChange`
+- Sorting is not built in: spread `useDragReorder`'s `getDragItemProps` on each `LayerItem`
 - `LayerActions` are hidden by default, visible on row hover
 - `LayerVisibilityToggle` and `LayerLockToggle` use eye/lock icons
 
@@ -199,8 +201,8 @@ Hierarchical tree with expand/collapse, depth indentation, and icons.
 │  → apply to store                               │
 ├─────────────────────────────────────────────────┤
 │  HistoryControls (in PaneHeader or Toolbar)     │
-│  → reads canUndo/canRedo                        │
-│  → calls onUndo/onRedo                          │
+│  → reads past/future from useDocumentStore      │
+│  → calls the store's undo/redo                  │
 ├─────────────────────────────────────────────────┤
 │  NumberInput.onStart                             │
 │  → pushSnapshot before scrub begins             │
@@ -231,7 +233,14 @@ Hierarchical tree with expand/collapse, depth indentation, and icons.
 ```tsx
 function LayerPanel() {
   const { selectedIds, select, isSelected } = useSelection({ items: elementIds })
-  const { getDragItemProps } = useDragReorder({ items: elements, onReorder: reorderElements })
+  const setElementOrder = useDocumentStore((s) => s.setElementOrder)
+  const { getDragItemProps } = useDragReorder({
+    items: elements,
+    onReorder: (next) => {
+      pushSnapshot()
+      setElementOrder(next.map((el) => el.id))
+    },
+  })
 
   return (
     <LayerList>
@@ -244,21 +253,21 @@ function LayerPanel() {
               {...getDragItemProps(i)}
             >
               <LayerIcon colour={el.fill?.color} />
-              <LayerName value={el.name} onRename={(name) => updateElement(el.id, { name })} />
+              <LayerName onRename={(name) => updateElement(el.id, { name })}>{el.name}</LayerName>
               <LayerActions>
                 <LayerVisibilityToggle
                   visible={el.visible}
-                  onToggle={() => updateElement(el.id, { visible: !el.visible })}
+                  onVisibleChange={(visible) => updateElement(el.id, { visible })}
                 />
                 <LayerLockToggle
                   locked={el.locked}
-                  onToggle={() => updateElement(el.id, { locked: !el.locked })}
+                  onLockedChange={(locked) => updateElement(el.id, { locked })}
                 />
               </LayerActions>
             </LayerItem>
           </ContextMenuTrigger>
           <ContextMenuContent>
-            <ContextMenuItem onSelect={() => duplicateElement(el.id)}>
+            <ContextMenuItem onSelect={() => duplicateElements([el.id])}>
               Duplicate <ContextMenuShortcut>⌘D</ContextMenuShortcut>
             </ContextMenuItem>
             <ContextMenuItem onSelect={() => deleteElement(el.id)}>

package/skills/substrate-scaffold/SKILL.md

@@ -39,9 +39,9 @@ Floating bottom bar. Renders tool buttons, separators, and groups. Uses `data-sl
 | `slider` / `slider-track` | h-6 |
 | `history-controls` | gap-0 |
 
-**Exports**: `Toolbar`, `ToolbarButton`, `ToolbarSeparator`, `ToolbarGroup`
+**Exports**: `Toolbar`, `ToolbarToggleGroup`, `ToolbarToggle`, `ToolbarSeparator`, `ToolbarDropdown`
 
-**Typical use**: One per playground, positioned at the bottom. Connect each `ToolbarButton` to `useToolStore` for active-tool state.
+**Typical use**: One per playground, positioned at the bottom. Put the tool buttons in a `ToolbarToggleGroup` of `ToolbarToggle`s and connect it to `useToolStore` for active-tool state.
 
 **Related**: substrate-controls (for inputs inside the toolbar), substrate-interaction (for keyboard shortcuts bound to tools)
 
@@ -181,11 +181,11 @@ Breadcrumbs show the path into nested node groups. Right panel shows properties
 <div className="flex h-screen flex-col">
   <DocumentTabList>{/* tabs */}</DocumentTabList>
   <div className="flex flex-1 overflow-hidden">
-    <Panel side="left">{/* layers/tree */}</Panel>
+    <Panel position="left">{/* layers/tree */}</Panel>
     <div className="relative flex-1">
       <Surface />{/* central area */}
     </div>
-    <Panel side="right">{/* property panes */}</Panel>
+    <Panel position="right">{/* property panes */}</Panel>
   </div>
   <StatusBar>{/* metadata */}</StatusBar>
   <Toolbar>{/* tools */}</Toolbar>

package/skills/theming/SKILL.md

@@ -113,9 +113,15 @@ const CURSOR_MAP: Record<string, string> = {
 }
 ```
 
-## 5. Dark mode
+## 5. Light and 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.
+Every Substrate component works in both themes. Colours come from tokens, and the theme is chosen by a `.dark` class on `<html>`: light values live in `:root`, dark values in `.dark`.
+
+Projects made with `create-substrate` follow the system theme through a small script in `index.html`. To force a theme, remove that script and either set `class="dark"` on `<html>` or leave it off. To add a switch, toggle that class yourself (or use `next-themes` in a Next.js app).
+
+Canvas-drawn parts follow the theme too: the design canvas reads `--canvas` and `--canvas-foreground`, the easing curve editor draws in its text colour, and both repaint when the theme changes. In your own canvas code, read colours with `getComputedStyle` at draw time instead of hardcoding them, and use mid-tones for defaults that must read on both backgrounds.
+
+When writing a component, use tokens (`bg-panel`, `text-muted-foreground`, `bg-foreground/10`) and check it in both themes. Avoid `bg-background` for a control's track or well: it matches the page in light mode and disappears.
 
 ## Related reference skills
 

package/skills/wire-interactions/SKILL.md

@@ -39,6 +39,7 @@ Keyboard events (DOM)
 | `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 |
+| `rotating` | Drag on the rotate handle above a single selection | Turn the element about its centre (hold Shift to snap to 15°) | Commit rotation |
 | `marquee_selecting` | Drag on empty canvas with select tool | Draw selection rectangle | Select contained elements |
 
 ### Pointer down logic
@@ -66,7 +67,8 @@ Keyboard events (DOM)
    - "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
+   - "resize": update element bounds with `resizeBounds`, which respects the handle and the element's rotation
+   - "rotate": set `rotation` from the pointer's angle around the element centre
    - "marquee": update selection rectangle
 5. Call markDirty() to trigger repaint
 ```
@@ -77,7 +79,7 @@ Keyboard events (DOM)
 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)
+   - "move"/"resize"/"rotate": nothing to push; the snapshot was taken when the drag first moved, so a click without a drag leaves no undo step
    - "marquee": select all elements within the marquee bounds
    - "pan": nothing to commit
 ```
@@ -104,12 +106,13 @@ Always convert pointer event coordinates to world space before doing hit-testing
 
 ```ts
 interface DragInfo {
-  type: DragType           // "create" | "move" | "resize" | "marquee" | "pan"
+  type: DragType           // "create" | "move" | "resize" | "rotate" | "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
+  rotate?: { id, center, startAngle, startRotation }  // Set for a rotate drag
   elementStartPositions?: Record<string, { x, y, width, height }>  // Snapshot for move/resize
 }
 ```

package/templates/agents-section.md

@@ -0,0 +1,41 @@
+# Substrate
+
+This project uses [Substrate](https://substrate.georgedrury.co.uk), a set of primitives for building creative tools: scaffold (toolbar, panels, panes, shortcuts), canvas and node helpers, and config-driven controls.
+
+## Use Substrate components first
+
+Components are installed into the project with the Substrate CLI, which wraps shadcn. Never run `npx shadcn@latest add` for them directly.
+
+```bash
+npx substrate-kit add panel slider toolbar   # install by name, in one call
+npx substrate-kit add                        # interactive picker
+npx substrate-kit docs <component>           # props, CSS variables, usage
+npx substrate-kit docs <component> --open    # open its docs page in the browser
+npx substrate-kit docs --list                # every component
+```
+
+Before writing a custom slider, input, panel, timeline or colour picker, check `docs --list`. If the Substrate MCP server is connected, use `search_components`, `get_component` and `get_docs` instead of the commands above, and `install_components` to install.
+
+## Tune values with Controls
+
+For parameters you want to adjust live (sizes, colours, springs, toggles), describe them as an object and render them with `Controls` instead of building a form:
+
+```tsx
+const card = useControls("Card", {
+  radius: [16, 0, 48],        // [default, min, max, step?] slider
+  colour: "#a78bfa",          // colour picker
+  visible: true,              // toggle
+  motion: { type: "spring", visualDuration: 0.3, bounce: 0.2 },
+})
+// <Panel><Controls /></Panel> renders every registered panel
+```
+
+The returned values keep the shape of the config. Panels have versions, reset, keyboard shortcuts (`shortcuts` option) and a copy button that gives an agent the tuned values to paste back in as the new defaults. Install with `npx substrate-kit add controls`, and read `docs controls` for every control type and option. Controls and the timeline are built on [DialKit](https://github.com/joshpuckett/dialkit) (MIT, by Josh Puckett), which installs as the `dialkit` dependency.
+
+## Tune animation with the timeline
+
+For motion, define clips with `useControlsTimeline` and bind `clip.current` to your UI. `ControlsTimeline` is the editor: scrub, move and resize clips, edit curves, and copy the tuned timing back as defaults. Install with `npx substrate-kit add controls-timeline`, and read `docs controls-timeline` for clip types, looping and zoom.
+
+## Skills
+
+Substrate skills are in `.claude/skills/` and `.agents/skills/`. Surface guides explain how to build each kind of tool (`scaffold-playground`, `canvas-2d`, `3d-scene`, `animation`, `image-generation`, `data-visualisation`) and workflows (`composing-panels`, `wire-interactions`, `create-custom-tool`, `theming`). Component references (`substrate-scaffold`, `substrate-controls`, `substrate-canvas`, `substrate-nodes`, `substrate-feedback`, `substrate-interaction`) say what to use. `install-components` lists everything available.

package/dist/commands/browse.d.ts

@@ -1,2 +0,0 @@
-export declare function browse(component?: string): void;
-//# sourceMappingURL=browse.d.ts.map

package/dist/commands/browse.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAKA,wBAAgB,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAiB/C"}

package/dist/commands/browse.js

@@ -1,25 +0,0 @@
-import { execSync } from "node:child_process";
-import { log } from "../utils/logger.js";
-const DOCS_BASE = "https://substrate.georgedrury.co.uk/docs/components";
-export function browse(component) {
-    const url = component
-        ? `${DOCS_BASE}/${component}`
-        : "https://substrate.georgedrury.co.uk/docs";
-    log.info(`Opening ${url}`);
-    try {
-        const platform = process.platform;
-        if (platform === "darwin") {
-            execSync(`open "${url}"`);
-        }
-        else if (platform === "win32") {
-            execSync(`start "${url}"`);
-        }
-        else {
-            execSync(`xdg-open "${url}"`);
-        }
-    }
-    catch {
-        log.error(`Could not open browser. Visit: ${url}`);
-    }
-}
-//# sourceMappingURL=browse.js.map

package/dist/commands/browse.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"browse.js","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAA;AAExC,MAAM,SAAS,GAAG,qDAAqD,CAAA;AAEvE,MAAM,UAAU,MAAM,CAAC,SAAkB;IACxC,MAAM,GAAG,GAAG,SAAS;QACpB,CAAC,CAAC,GAAG,SAAS,IAAI,SAAS,EAAE;QAC7B,CAAC,CAAC,0CAA0C,CAAA;IAC7C,GAAG,CAAC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,CAAA;IAC1B,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;QACjC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC3B,QAAQ,CAAC,SAAS,GAAG,GAAG,CAAC,CAAA;QAC1B,CAAC;aAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,QAAQ,CAAC,UAAU,GAAG,GAAG,CAAC,CAAA;QAC3B,CAAC;aAAM,CAAC;YACP,QAAQ,CAAC,aAAa,GAAG,GAAG,CAAC,CAAA;QAC9B,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,GAAG,CAAC,KAAK,CAAC,kCAAkC,GAAG,EAAE,CAAC,CAAA;IACnD,CAAC;AACF,CAAC"}

package/dist/commands/create.d.ts

@@ -1,9 +0,0 @@
-import { type PackageManager } from "../utils/detect-pm.js";
-export interface CreateOptions {
-    surface?: string;
-    skipInstall?: boolean;
-    skipGit?: boolean;
-    packageManager?: PackageManager;
-}
-export declare function create(projectName: string, options?: CreateOptions): Promise<void>;
-//# sourceMappingURL=create.d.ts.map

package/dist/commands/create.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAKA,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,uBAAuB,CAAA;AA4B9B,MAAM,WAAW,aAAa;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,wBAAsB,MAAM,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,aAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CAoGf"}