create-substrate 0.1.5 → 0.2.0

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.