create-substrate 0.1.0

package/skills/data-visualisation/SKILL.md

@@ -0,0 +1,228 @@
+# Data visualisation
+
+Guide to building interactive data exploration tools with Substrate — charts, graphs, dashboards, and visual analytics playgrounds.
+
+## When to use this surface
+
+Use a data visualisation surface when the app involves exploring, filtering, and presenting data visually: dashboard builders, chart editors, data exploration tools, analytics playgrounds, or any tool where users interact with visual representations of datasets.
+
+## Surface setup
+
+Data visualisation tools combine a **chart surface** (where visualisations render) with **data controls** (filters, axis selectors, aggregation options). The rendering engine is typically a charting library layered over SVG or Canvas.
+
+### Dependencies
+
+```bash
+npm install recharts d3
+npm install -D @types/d3
+```
+
+Recharts handles the common chart types (line, bar, area, pie, scatter) with a React-friendly API. D3 provides lower-level control for custom visualisations. Use both — Recharts for standard charts, D3 for anything bespoke.
+
+### Layout
+
+Data visualisation tools often work best with a flexible layout:
+
+```
+┌──────────┬────────────────────────┬──────────┐
+│          │                        │          │
+│  Left    │   Chart surface        │  Right   │
+│  panel   │   (visualisation)      │  panel   │
+│          │                        │          │
+│  Data    │                        │  Chart   │
+│  sources │                        │  config  │
+│  Filters │                        │  Style   │
+│          │                        │          │
+└──────────┴────────────────────────┴──────────┘
+                 [ Toolbar ]
+```
+
+For dashboard builders, the surface area might contain multiple chart tiles arranged in a grid — in that case, the surface acts more like a 2D canvas where chart widgets are the "elements".
+
+## Store architecture
+
+### Data store
+
+```ts
+interface DataState {
+  datasets: Record<string, Dataset>
+  activeDatasetId: string | null
+  filters: Filter[]
+  computedData: Record[] | null  // Filtered + transformed data
+}
+
+interface Dataset {
+  id: string
+  name: string
+  source: "upload" | "url" | "inline"
+  rawData: Record<string, unknown>[]
+  columns: ColumnDef[]
+}
+
+interface ColumnDef {
+  key: string
+  label: string
+  type: "number" | "string" | "date" | "boolean"
+}
+
+interface Filter {
+  id: string
+  column: string
+  operator: "eq" | "gt" | "lt" | "gte" | "lte" | "contains" | "between"
+  value: unknown
+}
+```
+
+### Chart store
+
+```ts
+interface ChartState {
+  charts: ChartConfig[]
+  selectedChartId: string | null
+}
+
+interface ChartConfig {
+  id: string
+  type: "line" | "bar" | "area" | "pie" | "scatter" | "radar" | "custom"
+  title: string
+  xAxis: string           // Column key
+  yAxis: string[]         // One or more column keys
+  groupBy?: string        // Column key for series grouping
+  aggregation?: "sum" | "avg" | "count" | "min" | "max"
+  colorScheme: string[]
+  position?: { x: number; y: number; width: number; height: number }  // For dashboard layout
+}
+```
+
+## Chart surface
+
+### Single chart mode
+
+For a focused exploration tool, the chart fills the surface area:
+
+```tsx
+"use client"
+
+import { ResponsiveContainer, LineChart, Line, XAxis, YAxis, Tooltip, CartesianGrid } from "recharts"
+
+export function ChartSurface() {
+  const data = useDataStore((s) => s.computedData)
+  const chart = useChartStore((s) => s.charts[0])
+
+  if (!data || !chart) return <EmptyState />
+
+  return (
+    <div className="absolute inset-0 flex items-center justify-center bg-canvas p-8">
+      <ResponsiveContainer width="100%" height="100%">
+        <LineChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey={chart.xAxis} />
+          <YAxis />
+          <Tooltip />
+          {chart.yAxis.map((key, i) => (
+            <Line key={key} dataKey={key} stroke={chart.colorScheme[i]} />
+          ))}
+        </LineChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}
+```
+
+### Dashboard mode
+
+For a dashboard builder, the surface contains a grid of chart tiles. Each tile is a chart config rendered at a specific position. Use the 2D canvas interaction patterns (drag to move, resize handles) for layout editing, but render each tile as a React component with Recharts inside.
+
+## Wiring to Substrate chrome
+
+### Toolbar
+
+| Tool | Purpose | Shortcut |
+|---|---|---|
+| Select | Select chart tiles (dashboard mode) | V |
+| Add chart | Insert a new chart widget | A |
+| Pan | Pan the dashboard canvas | H |
+| Zoom | Zoom to fit / zoom level | Cmd+0 |
+| Export | Export as PNG/SVG/PDF | Cmd+E |
+
+In single-chart mode, the toolbar might switch between chart types instead.
+
+### Left panel — data
+
+- **Dataset pane** — list loaded datasets, import CSV/JSON, paste data
+- **Columns pane** — show available columns with type badges, drag to assign axes
+- **Filters pane** — active filter list, add/remove filters with operator dropdowns and value inputs
+
+### Right panel — chart configuration
+
+- **Chart type pane** — visual selector for chart type (icons for line, bar, area, pie, etc.)
+- **Axes pane** — X axis column, Y axis columns (multi-select), group-by column
+- **Aggregation pane** — how to aggregate grouped data (sum, average, count)
+- **Style pane** — colour scheme selector, show/hide grid, legend position, label formatting
+
+## Data loading
+
+### CSV upload
+
+Use the HTML file input to accept CSVs, parse with PapaParse or a simple parser:
+
+```ts
+import Papa from "papaparse"
+
+function handleFileUpload(file: File) {
+  Papa.parse(file, {
+    header: true,
+    dynamicTyping: true,
+    complete: (results) => {
+      dataStore.addDataset({
+        name: file.name,
+        rawData: results.data,
+        columns: inferColumns(results.data),
+      })
+    },
+  })
+}
+```
+
+### Column type inference
+
+Scan the first N rows to infer column types (number, string, date). Store these on the `ColumnDef` so the UI can offer appropriate filter operators and chart axis options.
+
+## Interaction patterns
+
+### Axis assignment
+
+Let users drag column names from the data panel onto drop zones on the chart (X axis, Y axis, colour/group). This is a drag-and-drop interaction between panels and the surface.
+
+### Brushing and linking
+
+In dashboard mode, selecting a data range on one chart can filter the data for all other charts. This is managed through the filter store — a brush interaction adds a temporary filter that all charts respond to.
+
+### Tooltip and crosshair
+
+Recharts provides built-in tooltips. For custom tooltips, read the active data point and render a positioned DOM element over the chart surface.
+
+## Theming
+
+Charts should read from CSS variables for consistency with the Substrate theme:
+
+- Chart background → `bg-canvas`
+- Grid lines → derive from `--border` or `--canvas-foreground`
+- Text/labels → `--foreground` or `--muted-foreground`
+- Colour schemes → define as an array of CSS variables or provide sensible defaults
+
+## What to build
+
+Some examples of what this surface enables:
+
+- **Data explorer** — upload a CSV, choose chart type, filter and group interactively
+- **Dashboard builder** — multiple chart widgets on a grid, drag to rearrange, shared filters
+- **Analytics playground** — connect to a live data source, real-time updating charts
+- **Comparison tool** — side-by-side charts with linked brushing
+- **Chart editor** — design a single publication-quality chart with fine-grained style controls
+
+## Related reference skills
+
+- **substrate-scaffold** — Toolbar, Panel, StatusBar, DocumentTabs for the app shell
+- **substrate-controls** — Select, NumberInput, Slider, ColourPicker for chart configuration
+- **substrate-feedback** — Toast, EmptyState, CommandPalette for data loading feedback

package/skills/image-generation/SKILL.md

@@ -0,0 +1,211 @@
+# Image generation
+
+Guide to building prompt-driven image creation tools with Substrate — generation controls, preview surfaces, galleries, and parameter tuning.
+
+## When to use this surface
+
+Use an image generation surface when the app involves AI-generated visuals: text-to-image tools, style transfer, inpainting/outpainting editors, texture generators, or any workflow where users iterate on generated images through prompts and parameters.
+
+## Surface setup
+
+The image generation surface replaces the spatial canvas with a preview area and generation controls. The rendering engine is an API (such as fal.ai, Replicate, or a local Stable Diffusion endpoint) rather than a canvas or 3D renderer.
+
+### Dependencies
+
+```bash
+npm install @fal-ai/client
+```
+
+For other providers, install their SDK instead. The architecture is provider-agnostic — wrap the API call in a generation function and swap providers without changing the UI.
+
+### Environment
+
+Store API keys in `.env.local`:
+
+```
+FAL_KEY=your-key-here
+```
+
+Create a server action or API route to proxy generation requests — never expose keys to the client.
+
+## Architecture
+
+Unlike spatial canvases, image generation is **request/response** rather than **continuous rendering**. The core loop is:
+
+```
+User adjusts parameters (prompt, model, seed, etc.)
+  → Trigger generation (server action / API route)
+    → Show loading state in preview
+      → Display result in preview area
+        → Optionally save to gallery/history
+```
+
+### Generation store
+
+Create a Zustand store for generation state:
+
+```ts
+interface GenerationState {
+  prompt: string
+  negativePrompt: string
+  model: string
+  parameters: Record<string, number | string | boolean>
+  isGenerating: boolean
+  currentImage: string | null
+  history: GenerationResult[]
+  error: string | null
+}
+
+interface GenerationResult {
+  id: string
+  prompt: string
+  imageUrl: string
+  parameters: Record<string, number | string | boolean>
+  timestamp: number
+  seed: number
+}
+```
+
+Actions: `setPrompt`, `setParameter`, `generate`, `saveToHistory`, `loadFromHistory`.
+
+### Server action
+
+```ts
+"use server"
+
+import { fal } from "@fal-ai/client"
+
+export async function generateImage(params: GenerationParams) {
+  const result = await fal.subscribe("fal-ai/flux/schnell", {
+    input: {
+      prompt: params.prompt,
+      image_size: params.size,
+      num_inference_steps: params.steps,
+      seed: params.seed,
+    },
+  })
+  return result.data
+}
+```
+
+## Layout
+
+The image generation layout differs from the spatial canvas layout:
+
+```
+┌──────────┬────────────────────────┬──────────┐
+│          │                        │          │
+│  Left    │   Preview surface      │  Right   │
+│  panel   │   (generated image)    │  panel   │
+│          │                        │          │
+│  History │                        │  Params  │
+│  Gallery │                        │  Prompt  │
+│          │                        │          │
+└──────────┴────────────────────────┴──────────┘
+                 [ Toolbar ]
+```
+
+### Preview surface
+
+A simple container that displays the current image with zoom/pan controls:
+
+```tsx
+export function PreviewSurface() {
+  const currentImage = useGenerationStore((s) => s.currentImage)
+  const isGenerating = useGenerationStore((s) => s.isGenerating)
+
+  return (
+    <div className="absolute inset-0 flex items-center justify-center bg-canvas">
+      {isGenerating && <LoadingSpinner />}
+      {currentImage && (
+        <img
+          src={currentImage}
+          alt="Generated image"
+          className="max-h-full max-w-full object-contain"
+        />
+      )}
+      {!currentImage && !isGenerating && (
+        <p className="text-canvas-foreground text-sm">
+          Enter a prompt and generate
+        </p>
+      )}
+    </div>
+  )
+}
+```
+
+## Wiring to Substrate chrome
+
+### Toolbar
+
+The toolbar serves a different purpose here — mode switching and actions rather than spatial tools:
+
+| Action | Purpose | Shortcut |
+|---|---|---|
+| Generate | Trigger image generation | Cmd+Enter |
+| Compare | Side-by-side with previous | C |
+| Zoom to fit | Reset preview zoom | Cmd+0 |
+| Save | Download current image | Cmd+S |
+| Copy prompt | Copy prompt to clipboard | Cmd+Shift+C |
+
+### Left panel — history and gallery
+
+Show a scrollable grid of previously generated images. Clicking one loads it into the preview and restores its parameters. Use the Pane component for the container.
+
+### Right panel — generation controls
+
+Use Pane/Action/Slider to build parameter controls:
+
+- **Prompt pane** — textarea for the prompt, optional negative prompt
+- **Model pane** — dropdown to select the model/checkpoint
+- **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.
+
+## Interaction patterns
+
+### Prompt editing
+
+Use a textarea in the right panel. Bind Cmd+Enter globally to trigger generation — this is the primary interaction, equivalent to pressing play.
+
+### Seed management
+
+Show the current seed in the parameters pane. Provide a "randomise" button and a "lock" toggle. When locked, regenerating uses the same seed — useful for iterating on prompt wording while keeping composition stable.
+
+### Image comparison
+
+When the user presses C or selects compare mode, show the current and previous image side by side or with a slider divider. This helps evaluate prompt changes.
+
+### Inpainting extension
+
+For more advanced tools, the preview surface can include a canvas overlay for painting masks:
+
+1. Add a "mask" tool to the toolbar
+2. When active, overlay a transparent canvas on the preview image
+3. Let the user paint white (inpaint) regions
+4. Send the mask alongside the prompt to the API
+5. Use the same `useCanvasDrag` pattern for brush strokes
+
+This is where the 2D canvas skill and image generation skill intersect.
+
+## Theming
+
+The preview surface uses `bg-canvas` for its background. The generation controls in the right panel inherit panel theming. No special theming considerations beyond the standard Substrate tokens.
+
+## What to build
+
+Some examples of what this surface enables:
+
+- **Prompt studio** — iterate on prompts with parameter controls, build a gallery of results
+- **Texture generator** — generate tileable textures with specific material properties
+- **Character designer** — generate character variations, save favourites, export sprite sheets
+- **Mood board builder** — generate images for different themes, arrange in a gallery layout
+- **Inpainting editor** — upload an image, mask regions, regenerate specific areas
+
+## Related reference skills
+
+- **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
+- **substrate-canvas** — useViewport for inpainting canvas pan/zoom

package/skills/scaffold-playground/SKILL.md

@@ -0,0 +1,141 @@
+# Scaffold a Substrate playground
+
+Step-by-step guide to bootstrapping a new interactive playground from Substrate primitives.
+
+## What is a Substrate playground?
+
+A Substrate playground is a creative app built from composable primitives: a **surface** (the central area where the main interaction happens), **chrome** (toolbar, panels, panes), and **stores** (Zustand state management with undo/redo). You bring the creative idea — Substrate provides the shell.
+
+## Prerequisites
+
+A Next.js 14+ project with Tailwind CSS and the shadcn CLI configured. If you don't have one, run:
+
+```bash
+npx substrate create my-playground
+```
+
+This scaffolds a full project with dependencies, globals.css with Substrate tokens, and a starter playground page.
+
+To add Substrate to an existing project instead:
+
+```bash
+npx substrate-kit init
+```
+
+This installs skills, CLAUDE.md, components.json, and registers the MCP server.
+
+## 1. Choose your surface
+
+The surface is the heart of the playground — the central area where the main interaction happens. Substrate supports several surface types:
+
+| 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) |
+
+Read the relevant surface skill for setup instructions, dependencies, and architecture patterns.
+
+## 2. Install chrome primitives
+
+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
+```
+
+For the 2D canvas surface specifically, also install:
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/design-canvas
+```
+
+## 3. Compose the layout
+
+Every playground follows the same layout pattern — surface in the centre, optional panels on left/right, toolbar floating at the bottom:
+
+```tsx
+"use client"
+
+import { Panel } from "@/registry/substrate/components/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"
+
+export default function PlaygroundPage() {
+	const leftPanel = usePanelStore((s) => s.leftPanel)
+	const rightPanel = usePanelStore((s) => s.rightPanel)
+	const activeTool = useToolStore((s) => s.activeTool)
+	const setTool = useToolStore((s) => s.setTool)
+
+	return (
+		<div className="h-screen w-screen bg-canvas">
+			{leftPanel && (
+				<Panel position="left">
+					{/* Layers, data sources, history — depends on surface type */}
+				</Panel>
+			)}
+
+			{/* Your surface goes here */}
+			{/* <DesignCanvas /> or <SceneViewport /> or <PreviewSurface /> etc. */}
+
+			{rightPanel && (
+				<Panel position="right">
+					{/* Properties, parameters, configuration — depends on surface type */}
+				</Panel>
+			)}
+
+			<Toolbar>
+				<ToolbarToggleGroup value={activeTool} onValueChange={setTool}>
+					{/* Tool toggles — depends on surface type */}
+				</ToolbarToggleGroup>
+			</Toolbar>
+		</div>
+	)
+}
+```
+
+## 4. What the chrome gives you
+
+Once scaffolded, the chrome primitives provide:
+
+- **Toolbar** — floating bottom bar with toggle groups, separators, and tooltip/shortcut hints
+- **Panels** — side panels (left/right) with visibility controlled by `usePanelStore`
+- **Panes** — collapsible sections within panels, with headers, labels, and action buttons
+- **Actions** — labelled property rows (label + controls) for building inspectors
+- **Sliders** — range inputs for numeric properties
+
+These are surface-agnostic — they work the same whether you're building a 3D scene editor or an image generation tool.
+
+## 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)
+
+## Component reference skills
+
+For a full catalogue of available components, hooks, and utilities organised by domain:
+
+| Domain | Skill | What it covers |
+| --- | --- | --- |
+| App shell | **substrate-scaffold** | Toolbar, Panel, Pane, DocumentTabs, StatusBar, ZoomControls, Breadcrumbs, Resizer |
+| Input controls | **substrate-controls** | NumberInput, Slider, NumberSlider, Select, Toggle, TextArea, ColourPicker, ActionControls |
+| Spatial primitives | **substrate-canvas** | useViewport, useSelection, snap, boundingBox, hit testing, coordinate maths |
+| Node graph | **substrate-nodes** | Node cards, typed ports, port colour theming |
+| Status and communication | **substrate-feedback** | Toast, ProgressBar, Badge, EmptyState, CommandPalette, ContextMenu, ShortcutOverlay |
+| Editing flows | **substrate-interaction** | useUndoable, useClipboard, createKeyboardShortcuts, HistoryControls, LayerList, TreeList |