create-substrate 0.1.0

package/dist/surfaces/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/surfaces/types.ts"],"names":[],"mappings":"AAeA,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC9C,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,2CAA2C,EAAE;IACpG,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,0DAA0D,EAAE;IACjH,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,qDAAqD,EAAE;IAC9G,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,mDAAmD,EAAE;IAChH,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,yCAAyC,EAAE;IAChG,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,yCAAyC,EAAE;IACzG,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,wCAAwC,EAAE;CAC1F,CAAA"}

package/dist/utils/detect-pm.d.ts

@@ -0,0 +1,5 @@
+export type PackageManager = "npm" | "pnpm" | "bun";
+export declare function detectPackageManager(cwd: string): PackageManager;
+export declare function getInstallCommand(pm: PackageManager): string;
+export declare function getRunCommand(pm: PackageManager, script: string): string;
+//# sourceMappingURL=detect-pm.d.ts.map

package/dist/utils/detect-pm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-pm.d.ts","sourceRoot":"","sources":["../../src/utils/detect-pm.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;AAEnD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAQhE;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAE5D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGxE"}

package/dist/utils/detect-pm.js

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export function detectPackageManager(cwd) {
+    if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) {
+        return "bun";
+    }
+    if (existsSync(join(cwd, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    return "npm";
+}
+export function getInstallCommand(pm) {
+    return `${pm} install`;
+}
+export function getRunCommand(pm, script) {
+    if (pm === "npm")
+        return `npm run ${script}`;
+    return `${pm} ${script}`;
+}
+//# sourceMappingURL=detect-pm.js.map

package/dist/utils/detect-pm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-pm.js","sourceRoot":"","sources":["../../src/utils/detect-pm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAIhC,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAkB;IAClD,OAAO,GAAG,EAAE,UAAU,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAkB,EAAE,MAAc;IAC9D,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,WAAW,MAAM,EAAE,CAAA;IAC5C,OAAO,GAAG,EAAE,IAAI,MAAM,EAAE,CAAA;AAC1B,CAAC"}

package/dist/utils/fs.d.ts

@@ -0,0 +1,7 @@
+export declare function ensureDir(dir: string): void;
+export declare function writeFile(filePath: string, content: string): void;
+export declare function copyDir(src: string, dest: string): void;
+export declare function exists(path: string): boolean;
+export declare function listDirs(dir: string): string[];
+export declare function resolveSkillsDir(): string;
+//# sourceMappingURL=fs.d.ts.map

package/dist/utils/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3C;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBvD;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAK9C;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAUzC"}

package/dist/utils/fs.js

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+export function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+export function writeFile(filePath, content) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, content, "utf-8");
+}
+export function copyDir(src, dest) {
+    ensureDir(dest);
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        try {
+            if (entry.isDirectory()) {
+                copyDir(srcPath, destPath);
+            }
+            else {
+                writeFileSync(destPath, readFileSync(srcPath));
+            }
+        }
+        catch {
+            // Skip files that can't be read
+        }
+    }
+}
+export function exists(path) {
+    return existsSync(path);
+}
+export function listDirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+}
+export function resolveSkillsDir() {
+    const distDir = dirname(dirname(new URL(import.meta.url).pathname));
+    const skillsDir = join(distDir, "skills");
+    if (existsSync(skillsDir))
+        return skillsDir;
+    const pkgRoot = join(distDir, "..");
+    const fallback = join(pkgRoot, "skills");
+    if (existsSync(fallback))
+        return fallback;
+    throw new Error("Could not locate bundled skills directory");
+}
+//# sourceMappingURL=fs.js.map

package/dist/utils/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACzF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACrC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAe;IACzD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC5B,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAY;IAC/C,SAAS,CAAC,IAAI,CAAC,CAAA;IACf,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,CAAC;YACH,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;YAC5B,CAAC;iBAAM,CAAC;gBACN,aAAa,CAAC,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAA;YAChD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,gCAAgC;QAClC,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IAC/B,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IACnE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACzC,IAAI,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAA;IAE3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACxC,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAA;IAEzC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;AAC9D,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,10 @@
+export declare const log: {
+    info: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    step: (msg: string) => void;
+    blank: () => void;
+    title: (msg: string) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,GAAG;gBACF,MAAM;mBACH,MAAM;gBACT,MAAM;iBACL,MAAM;gBACP,MAAM;;iBAEL,MAAM;CAKpB,CAAA"}

package/dist/utils/logger.js

@@ -0,0 +1,15 @@
+import chalk from "chalk";
+export const log = {
+    info: (msg) => console.log(chalk.cyan("ℹ"), msg),
+    success: (msg) => console.log(chalk.green("✓"), msg),
+    warn: (msg) => console.log(chalk.yellow("⚠"), msg),
+    error: (msg) => console.error(chalk.red("✗"), msg),
+    step: (msg) => console.log(chalk.dim("→"), msg),
+    blank: () => console.log(),
+    title: (msg) => {
+        log.blank();
+        console.log(chalk.bold(msg));
+        log.blank();
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACxD,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC5D,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC1D,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IAC1D,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACvD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;IAC1B,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE;QACrB,GAAG,CAAC,KAAK,EAAE,CAAA;QACX,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAC5B,GAAG,CAAC,KAAK,EAAE,CAAA;IACb,CAAC;CACF,CAAA"}

package/dist/utils/shell.d.ts

@@ -0,0 +1,7 @@
+export interface ExecOptions {
+    cwd?: string;
+    silent?: boolean;
+}
+export declare function exec(command: string, options?: ExecOptions): string;
+export declare function execSilent(command: string, cwd?: string): string | null;
+//# sourceMappingURL=shell.d.ts.map

package/dist/utils/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/utils/shell.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAevE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMvE"}

package/dist/utils/shell.js

@@ -0,0 +1,28 @@
+import { execSync } from "node:child_process";
+import { log } from "./logger.js";
+export function exec(command, options = {}) {
+    const { cwd, silent = false } = options;
+    try {
+        const result = execSync(command, {
+            cwd,
+            encoding: "utf-8",
+            stdio: silent ? "pipe" : "inherit",
+        });
+        return typeof result === "string" ? result.trim() : "";
+    }
+    catch (error) {
+        if (!silent) {
+            log.error(`Command failed: ${command}`);
+        }
+        throw error;
+    }
+}
+export function execSilent(command, cwd) {
+    try {
+        return exec(command, { cwd, silent: true });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/utils/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/utils/shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAOjC,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,UAAuB,EAAE;IAC7D,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE;YAC/B,GAAG;YACH,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;SACnC,CAAC,CAAA;QACF,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACxD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,GAAG,CAAC,KAAK,CAAC,mBAAmB,OAAO,EAAE,CAAC,CAAA;QACzC,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,GAAY;IACtD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-substrate",
+  "version": "0.1.0",
+  "description": "Scaffold a Substrate creative tool playground",
+  "type": "module",
+  "bin": {
+    "create-substrate": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "keywords": [
+    "substrate",
+    "canvas",
+    "design-tool",
+    "vite",
+    "react",
+    "scaffold"
+  ],
+  "license": "MIT"
+}

package/skills/3d-scene/SKILL.md

@@ -0,0 +1,172 @@
+# 3D scene
+
+Guide to building interactive 3D viewports with Substrate — object placement, orbit cameras, material editors, and lighting controls.
+
+## When to use this surface
+
+Use a 3D scene when the app involves spatial objects in three dimensions: product viewers, architectural walkthroughs, particle systems, shader playgrounds, or any tool where users orbit, zoom, and interact with a scene graph.
+
+## Surface setup
+
+The 3D viewport lives inside the Substrate layout where the canvas would normally go. Use Three.js (via `@react-three/fiber` and `@react-three/drei`) as the rendering engine.
+
+### Dependencies
+
+```bash
+npm install three @react-three/fiber @react-three/drei
+npm install -D @types/three
+```
+
+### Mount the viewport
+
+Create a surface component that fills the available space between panels:
+
+```tsx
+"use client"
+
+import { Canvas } from "@react-three/fiber"
+import { OrbitControls, Grid, Environment } from "@react-three/drei"
+
+export function SceneViewport() {
+  return (
+    <div className="absolute inset-0 bg-canvas">
+      <Canvas camera={{ position: [5, 5, 5], fov: 50 }}>
+        <OrbitControls makeDefault />
+        <Grid infiniteGrid fadeDistance={50} />
+        <Environment preset="studio" />
+        <ambientLight intensity={0.4} />
+        <directionalLight position={[10, 10, 5]} intensity={1} />
+        {/* Scene objects render here */}
+      </Canvas>
+    </div>
+  )
+}
+```
+
+Drop this into the playground layout in place of `<DesignCanvas />`.
+
+## Store architecture
+
+Create a Zustand scene store to manage the 3D scene graph. This follows the same pattern as `document-store` but for 3D objects:
+
+```ts
+interface SceneObject {
+  id: string
+  name: string
+  type: "mesh" | "light" | "group" | "camera"
+  position: [number, number, number]
+  rotation: [number, number, number]
+  scale: [number, number, number]
+  geometry?: "box" | "sphere" | "cylinder" | "plane" | "torus" | "custom"
+  material?: MaterialConfig
+  visible: boolean
+  locked: boolean
+  children?: string[]
+}
+```
+
+Store actions should include: `addObject`, `removeObject`, `updateObject`, `selectObject`, `pushSnapshot` (for undo/redo). Use the same snapshot-based undo pattern as the 2D canvas.
+
+## Wiring to Substrate chrome
+
+### Toolbar
+
+Map toolbar toggles to 3D-specific modes:
+
+| Tool | Purpose | Shortcut |
+|---|---|---|
+| Select | Click objects in the viewport | V |
+| Move | Translate selected object(s) | G |
+| Rotate | Rotate selected object(s) | R |
+| Scale | Scale selected object(s) | S |
+| Add | Open an add menu (cube, sphere, light, etc.) | Shift+A |
+
+Use `useToolStore` — the same store the 2D canvas uses. The tool type union can be extended with 3D-specific modes.
+
+### Panels
+
+**Left panel — scene hierarchy:**
+
+A tree view of the scene graph. Each node shows name, type icon, and visibility toggle. Clicking selects the object in the viewport. This follows the same pattern as the layers panel but supports nesting (groups/parent-child).
+
+**Right panel — properties inspector:**
+
+Use the Pane/Action/Slider compound components to expose:
+
+- **Transform pane** — X/Y/Z position, rotation (degrees), scale with number inputs
+- **Geometry pane** — type-specific properties (radius, segments, width/height/depth)
+- **Material pane** — colour picker, metalness/roughness sliders, texture upload
+- **Light pane** (when a light is selected) — intensity slider, colour, shadow toggle
+
+### Keyboard shortcuts
+
+Extend `useKeyboardShortcuts` or create a `use3DShortcuts` hook:
+
+- Delete — remove selected object
+- Cmd+Z / Cmd+Shift+Z — undo/redo via snapshot store
+- Cmd+D — duplicate selected
+- H — toggle visibility of selected
+- Numpad shortcuts for camera views (front/top/right) if desired
+
+## Interaction patterns
+
+### Object selection
+
+`@react-three/fiber` provides `onPointerDown` on mesh components. Use raycasting (built into R3F) rather than manual hit-testing:
+
+```tsx
+<mesh
+  onClick={(e) => {
+    e.stopPropagation()
+    sceneStore.selectObject(object.id, e.shiftKey)
+  }}
+>
+  {/* geometry + material */}
+</mesh>
+```
+
+### Transform gizmos
+
+Use `@react-three/drei`'s `TransformControls` for move/rotate/scale. Wire the active mode to `useToolStore`:
+
+```tsx
+{selectedId && (
+  <TransformControls
+    object={selectedRef}
+    mode={activeTool === "rotate" ? "rotate" : activeTool === "scale" ? "scale" : "translate"}
+    onObjectChange={() => sceneStore.updateFromRef(selectedId, selectedRef)}
+  />
+)}
+```
+
+### Camera
+
+`OrbitControls` handles orbit/zoom/pan. Disable it when a transform gizmo is active to prevent conflicts. The hand tool can temporarily enable a fly/walk camera mode.
+
+## Theming
+
+The 3D viewport background can read `--canvas` via CSS on the container div. For the Three.js scene background, read it from the DOM:
+
+```ts
+const style = getComputedStyle(document.documentElement)
+const bg = style.getPropertyValue("--canvas").trim()
+// Convert to Three.js colour and set scene.background
+```
+
+Grid, gizmo, and selection highlight colours can be configured as constants or driven by additional CSS variables.
+
+## What to build
+
+Some examples of what this surface enables:
+
+- **Product configurator** — load a 3D model, expose material/colour options in panes, orbit to inspect
+- **Scene builder** — add primitives, position them, set up lighting, export as glTF
+- **Shader playground** — custom `ShaderMaterial` with uniforms exposed as sliders in the properties panel
+- **Particle system editor** — particle emitter properties as pane controls, real-time preview in the viewport
+- **Architectural viewer** — import a model, add measurement tools, annotate with text labels
+
+## Related reference skills
+
+- **substrate-scaffold** — Toolbar, Panel, StatusBar, ZoomControls for the app shell
+- **substrate-controls** — NumberInput, Slider, ColourPicker, ActionControls for property panes
+- **substrate-interaction** — useUndoable, useClipboard, createKeyboardShortcuts, TreeList for scene hierarchy

package/skills/animation/SKILL.md

@@ -0,0 +1,194 @@
+# Animation
+
+Guide to building timeline-based motion tools with Substrate — keyframe editing, easing controls, playback, and animated previews.
+
+## When to use this surface
+
+Use an animation surface when the app involves motion over time: UI animation prototyping, motion graphics editors, sprite animation, easing explorers, or any tool where users define how things change across a timeline.
+
+## Surface setup
+
+Animation tools combine a **preview stage** (where the animation plays) with a **timeline** (where keyframes are edited). The preview can be DOM-based (GSAP animating real elements) or canvas-based, depending on what's being animated.
+
+### Dependencies
+
+```bash
+npm install gsap
+```
+
+GSAP handles the animation engine — tweening, easing, timeline sequencing. For simpler cases, CSS animations or the Web Animations API may suffice, but GSAP provides the most control for a creative tool.
+
+### Layout
+
+Animation tools typically use a vertical split — preview on top, timeline on the bottom:
+
+```
+┌──────────┬────────────────────────┬──────────┐
+│          │                        │          │
+│  Left    │   Preview stage        │  Right   │
+│  panel   │   (animated elements)  │  panel   │
+│          │                        │          │
+│  Layers  │                        │  Props   │
+│          │                        │          │
+├──────────┴────────────────────────┴──────────┤
+│  Timeline                                     │
+│  ──●────────●──────────●─────── ▶ 0:00 / 2:00│
+│  [tracks with keyframe diamonds]              │
+└───────────────────────────────────────────────┘
+                 [ Toolbar ]
+```
+
+## Store architecture
+
+### Animation store
+
+```ts
+interface AnimationState {
+  duration: number           // Total duration in seconds
+  currentTime: number        // Playhead position
+  isPlaying: boolean
+  fps: number                // Preview framerate (default 60)
+  layers: AnimationLayer[]
+  selectedKeyframes: string[]
+}
+
+interface AnimationLayer {
+  id: string
+  name: string
+  targetId: string           // Which element this layer animates
+  property: string           // "x" | "y" | "opacity" | "scale" | "rotation" | ...
+  keyframes: Keyframe[]
+  visible: boolean
+  locked: boolean
+}
+
+interface Keyframe {
+  id: string
+  time: number               // Position in seconds
+  value: number
+  easing: EasingType         // "linear" | "ease-in" | "ease-out" | "ease-in-out" | "cubic-bezier" | ...
+  bezierHandles?: [number, number, number, number]  // For custom cubic-bezier
+}
+```
+
+### Element store
+
+Reuse the same pattern as the 2D canvas document store, but elements here represent animated objects on the stage rather than static shapes. Each element has base properties that keyframes override at specific times.
+
+## Timeline component
+
+The timeline is the core component that's unique to animation surfaces. It needs:
+
+- **Playhead** — a draggable vertical line showing current time, scrubbable
+- **Tracks** — one row per animated property, showing keyframe diamonds
+- **Keyframe diamonds** — draggable markers at specific times, selectable
+- **Zoom** — horizontal zoom to see more or fewer seconds
+- **Rulers** — time markings along the top (seconds/frames)
+- **Playback controls** — play/pause, jump to start/end, loop toggle
+
+### Interaction model
+
+The timeline uses horizontal dragging extensively:
+
+- Drag the playhead to scrub through time
+- Drag a keyframe diamond to move it in time
+- Shift-click keyframes to multi-select
+- Double-click a track to add a keyframe at that time
+- Right-click a keyframe for easing options
+
+This is pointer-event-driven, similar to the 2D canvas interaction model but on a 1D (time) axis rather than 2D space. Consider a dedicated `useTimelineInteraction` hook following the same state machine pattern as `useCanvasInteraction`.
+
+## Wiring to Substrate chrome
+
+### Toolbar
+
+| Tool | Purpose | Shortcut |
+|---|---|---|
+| Select | Select keyframes on timeline | V |
+| Add keyframe | Click on timeline to add | K |
+| Play/Pause | Toggle playback | Space |
+| Jump to start | Move playhead to 0 | Home |
+| Jump to end | Move playhead to duration | End |
+| Loop | Toggle loop playback | L |
+
+### Left panel — layers
+
+List animation layers (one per animated property per element). Show: element name, property name, visibility toggle, lock toggle. Group layers by element.
+
+### Right panel — keyframe properties
+
+When a keyframe is selected, show:
+
+- **Time pane** — exact time position (number input)
+- **Value pane** — the property value at this keyframe
+- **Easing pane** — easing type dropdown plus a visual curve editor for cubic-bezier
+- **Interpolation** — linear vs smooth vs step
+
+The easing curve editor is a specialised pane — a small canvas showing the bezier curve with draggable control points.
+
+## Preview stage
+
+The preview stage renders the current state of the animation at `currentTime`. On each frame:
+
+1. Read `currentTime` from the animation store
+2. For each layer, interpolate between the surrounding keyframes using the specified easing
+3. Apply interpolated values to the corresponding elements
+4. Render the stage
+
+During playback, a `requestAnimationFrame` loop advances `currentTime` at the configured FPS.
+
+### Using GSAP
+
+GSAP's timeline can be built from the keyframe data and scrubbed to `currentTime`:
+
+```ts
+// Build a GSAP timeline from store data
+const tl = gsap.timeline({ paused: true })
+
+for (const layer of layers) {
+  for (let i = 0; i < layer.keyframes.length - 1; i++) {
+    const from = layer.keyframes[i]
+    const to = layer.keyframes[i + 1]
+    tl.to(targetRef, {
+      [layer.property]: to.value,
+      duration: to.time - from.time,
+      ease: to.easing,
+    }, from.time)
+  }
+}
+
+// Scrub to current time
+tl.seek(currentTime)
+```
+
+Rebuild the GSAP timeline when keyframes change. Seek to `currentTime` on every frame during playback and when the user scrubs.
+
+## Keyboard shortcuts
+
+- Space — play/pause
+- K — add keyframe at current time for selected property
+- Delete — remove selected keyframes
+- Cmd+Z / Cmd+Shift+Z — undo/redo
+- Left/Right arrows — step forward/back one frame
+- Shift+Left/Right — step forward/back 10 frames
+- Home/End — jump to start/end
+
+## Theming
+
+The preview stage uses `bg-canvas`. The timeline area can use `bg-panel` or a slightly different shade. Keyframe diamonds, playhead, and track colours should be configurable — consider additional CSS variables like `--timeline-playhead`, `--timeline-keyframe`, `--timeline-track`.
+
+## What to build
+
+Some examples of what this surface enables:
+
+- **UI animation prototyper** — animate component properties (opacity, position, scale), export CSS/GSAP code
+- **Easing explorer** — visual comparison of different easing functions, interactive curve editor
+- **Sprite animator** — frame-by-frame sprite animation with onion skinning
+- **Motion graphics tool** — animate text and shapes along paths with timing controls
+- **Transition builder** — design page/component transitions, preview at different speeds
+
+## Related reference skills
+
+- **substrate-scaffold** — Toolbar, Panel, StatusBar for the app shell
+- **substrate-controls** — NumberInput, Slider, EasingCurveEditor, ActionControls for keyframe properties
+- **substrate-interaction** — useUndoable, createKeyboardShortcuts, LayerList for animation layers