truecanvas 0.1.0 → 0.3.0

package/dist/{chunk-WB35FXGP.js → chunk-XWQ5MS24.js}

@@ -1,78 +1,24 @@
+import {
+  detectFramework,
+  idOf,
+  isComponentName,
+  jsxName,
+  parseModule,
+  rewriteImportSource,
+  walk
+} from "./chunk-PBKX3SBC.js";
 import {
   Catalog,
-  importSpecifier
-} from "./chunk-753N4QRO.js";
-
-// src/core/config.ts
-import fs from "fs";
-import path from "path";
-function loadConfig(root, overrides = {}) {
-  let file = {};
-  const configPath = path.join(root, "truecanvas.config.json");
-  if (fs.existsSync(configPath)) file = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  const appDir = file.appDir ?? (fs.existsSync(path.join(root, "src/app")) ? "src/app" : "app");
-  const srcPrefix = appDir.startsWith("src/") ? "src/" : "";
-  let deps = {};
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-    deps = { ...pkg.dependencies, ...pkg.devDependencies };
-  } catch {
-    deps = {};
-  }
-  const knownLibraries = ["@paper-design/shaders-react"].filter((l) => l in deps);
-  return {
-    root,
-    appUrl: "http://localhost:3000",
-    port: 4800,
-    canvasDir: `${srcPrefix}canvas`,
-    appDir,
-    components: [`${srcPrefix}components/**/*.tsx`],
-    darkMode: { strategy: "class", value: "dark" },
-    ...file,
-    libraries: [.../* @__PURE__ */ new Set([...knownLibraries, ...file.libraries ?? []])],
-    ...stripUndefined(overrides)
-  };
-}
-function stripUndefined(o) {
-  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
-}
-
-// src/core/ast.ts
-import { parse } from "@babel/parser";
-function parseModule(source) {
-  return parse(source, {
-    sourceType: "module",
-    plugins: ["typescript", "jsx"],
-    errorRecovery: false
-  });
-}
-function idOf(node) {
-  const loc = node.loc.start;
-  return `${loc.line}:${loc.column}`;
-}
-function jsxName(name) {
-  if (name.type === "JSXIdentifier") return name.name;
-  if (name.type === "JSXNamespacedName") return `${name.namespace.name}:${name.name.name}`;
-  return `${jsxName(name.object)}.${name.property.name}`;
-}
-function walk(node, visit, parent = null) {
-  if (!node || typeof node !== "object") return;
-  if (Array.isArray(node)) {
-    for (const child of node) walk(child, visit, parent);
-    return;
-  }
-  const n = node;
-  if (typeof n.type !== "string") return;
-  if (visit(n, parent) === false) return;
-  for (const key of Object.keys(n)) {
-    if (key === "loc" || key === "leadingComments" || key === "trailingComments" || key === "innerComments" || key === "extra") continue;
-    const value = n[key];
-    if (value && typeof value === "object") walk(value, visit, n);
-  }
-}
-function isComponentName(name) {
-  return /^[A-Z]/.test(name) || name.includes(".");
-}
+  importSpecifier,
+  posix,
+  resolveAliasPath
+} from "./chunk-WU7NBTJH.js";
+import {
+  ICON_LIBRARIES,
+  iconLibrary,
+  loadIcons,
+  searchIcons
+} from "./chunk-C4SATRZT.js";
 
 // src/core/parse.ts
 function parseCanvas(name, file, source) {
@@ -102,8 +48,8 @@ function parseCanvas(name, file, source) {
   let frameIndex = 0;
   for (const child of canvasNode.children) {
     if (child.kind !== "component" || child.name !== "Frame") continue;
-    const path12 = [frameIndex++];
-    reindex(child, path12);
+    const path14 = [frameIndex++];
+    reindex(child, path14);
     frames.push({
       ...child,
       frameName: str(child.props.name) ?? `Frame ${frameIndex}`,
@@ -134,6 +80,7 @@ function readImports(ast) {
       typeOnly,
       // value bindings only: `import type` and `{ type X }` don't exist at runtime
       names: typeOnly ? [] : [...named.filter((s) => s.importKind !== "type").map((s) => s.local.name), ...ns ? [ns.local.name] : []],
+      bindings: typeOnly ? [] : named.filter((s) => s.importKind !== "type").map((s) => ({ imported: s.imported.type === "Identifier" ? s.imported.name : s.imported.value, local: s.local.name })),
       defaultName: def ? def.local.name : null,
       start: stmt.start,
       end: stmt.end,
@@ -153,9 +100,9 @@ function topLevelNames(ast) {
   }
   return out;
 }
-function reindex(node, path12) {
-  node.path = path12;
-  node.children.forEach((c, i) => reindex(c, [...path12, i]));
+function reindex(node, path14) {
+  node.path = path14;
+  node.children.forEach((c, i) => reindex(c, [...path14, i]));
 }
 function str(v) {
   return v?.kind === "string" ? v.value : void 0;
@@ -163,10 +110,10 @@ function str(v) {
 function num(v) {
   return v?.kind === "number" ? v.value : void 0;
 }
-function buildNode(el, source, path12) {
+function buildNode(el, source, path14) {
   const children = [];
   for (const child of el.children) {
-    const built = buildChild(child, source, [...path12, children.length]);
+    const built = buildChild(child, source, [...path14, children.length]);
     if (built) children.push(built);
   }
   if (el.type === "JSXFragment") {
@@ -181,7 +128,7 @@ function buildNode(el, source, path12) {
       end: el.end,
       line: el.loc.start.line,
       col: el.loc.start.column,
-      path: path12,
+      path: path14,
       attrs: [],
       nameEnd: el.openingFragment.end - 1,
       openEnd: el.openingFragment.end,
@@ -216,7 +163,7 @@ function buildNode(el, source, path12) {
     end: el.end,
     line: open.loc.start.line,
     col: open.loc.start.column,
-    path: path12,
+    path: path14,
     attrs,
     // after type arguments: `<Select<Opt> …>`
     nameEnd: (open.typeParameters ?? open.name).end,
@@ -225,27 +172,27 @@ function buildNode(el, source, path12) {
     closeStart: el.closingElement ? el.closingElement.start : open.end
   };
 }
-function buildChild(child, source, path12) {
-  if (child.type === "JSXElement" || child.type === "JSXFragment") return buildNode(child, source, path12);
+function buildChild(child, source, path14) {
+  if (child.type === "JSXElement" || child.type === "JSXFragment") return buildNode(child, source, path14);
   if (child.type === "JSXText") {
     const text = child.value.replace(/\s+/g, " ").trim();
     if (!text) return null;
-    return leaf("text", text, child, path12, { text });
+    return leaf("text", text, child, path14, { text });
   }
   if (child.type === "JSXExpressionContainer") {
     const expr = child.expression;
     if (expr.type === "JSXEmptyExpression") return null;
-    if (expr.type === "StringLiteral") return leaf("text", expr.value, child, path12, { text: expr.value });
+    if (expr.type === "StringLiteral") return leaf("text", expr.value, child, path14, { text: expr.value });
     if (expr.type === "TemplateLiteral" && expr.expressions.length === 0) {
       const text = expr.quasis.map((q) => q.value.cooked ?? "").join("");
-      return leaf("text", text, child, path12, { text });
+      return leaf("text", text, child, path14, { text });
     }
-    return leaf("expression", source.slice(expr.start, expr.end), child, path12, {});
+    return leaf("expression", source.slice(expr.start, expr.end), child, path14, {});
   }
-  if (child.type === "JSXSpreadChild") return leaf("expression", source.slice(child.start, child.end), child, path12, {});
+  if (child.type === "JSXSpreadChild") return leaf("expression", source.slice(child.start, child.end), child, path14, {});
   return null;
 }
-function leaf(kind, name, node, path12, extra) {
+function leaf(kind, name, node, path14, extra) {
   return {
     id: `${kind[0]}${idOf(node)}`,
     kind,
@@ -258,7 +205,7 @@ function leaf(kind, name, node, path12, extra) {
     end: node.end,
     line: node.loc.start.line,
     col: node.loc.start.column,
-    path: path12,
+    path: path14,
     attrs: [],
     nameEnd: node.end,
     openEnd: node.end,
@@ -322,10 +269,10 @@ function findNode(doc, id) {
 function findFrame(doc, ref) {
   return doc.frames.find((f) => f.id === ref || f.frameName === ref) ?? null;
 }
-function findByPath(doc, path12) {
-  if (!path12.length) return null;
-  let node = doc.frames[path12[0]];
-  for (const i of path12.slice(1)) node = node?.children[i];
+function findByPath(doc, path14) {
+  if (!path14.length) return null;
+  let node = doc.frames[path14[0]];
+  for (const i of path14.slice(1)) node = node?.children[i];
   return node ?? null;
 }
 
@@ -418,7 +365,8 @@ var CanvasEditor = class {
     } else if (node.openEnd === node.closeStart) {
       this.s.appendLeft(node.openEnd, code);
     } else {
-      this.s.overwrite(node.openEnd, node.closeStart, code);
+      const comments = this.source.slice(node.openEnd, node.closeStart).match(/\{\s*\/\*[\s\S]*?\*\/\s*\}/g) ?? [];
+      this.s.overwrite(node.openEnd, node.closeStart, comments.join("") + code);
     }
   }
   // ---------- indentation helpers: edits match the file's existing style ----------
@@ -454,13 +402,20 @@ var CanvasEditor = class {
     }
     return this.lineIndent(parent.start) + this.unit();
   }
-  /** Re-indents lines 2..n of a snippet so it sits at `indent`. */
+  /**
+   * Re-indents lines 2..n of a snippet so it sits at `indent`. Lines that start
+   * inside a multi-line string or template literal are content, not code: they
+   * are kept exactly as written.
+   */
   shift(code, indent) {
-    const lines = code.trim().split("\n");
-    const rest = lines.slice(1).filter((l) => l.trim());
+    const trimmed = code.trim();
+    const lines = trimmed.split("\n");
+    const frozen = literalLines(trimmed);
+    const free = (i) => !frozen.has(i);
+    const rest = lines.slice(1).filter((l, i) => l.trim() && free(i + 1));
     const base = rest.length ? Math.min(...rest.map((l) => /^[ \t]*/.exec(l)[0].length)) : 0;
-    const relative = lines.slice(1).map((l) => l.trim() ? l.slice(base) : "");
-    const steps = relative.map((l) => /^ */.exec(l)[0].length).filter((n) => n > 0);
+    const relative = lines.slice(1).map((l, i) => free(i + 1) ? l.trim() ? l.slice(base) : "" : l);
+    const steps = relative.filter((_, i) => free(i + 1)).map((l) => /^ */.exec(l)[0].length).filter((n) => n > 0);
     const from = steps.length ? Math.min(...steps) : 0;
     const unit = this.unit();
     const convert = (l) => {
@@ -468,7 +423,7 @@ var CanvasEditor = class {
       const n = /^ */.exec(l)[0].length;
       return unit.repeat(Math.floor(n / from)) + " ".repeat(n % from) + l.slice(n);
     };
-    return [lines[0], ...relative.map((l) => l ? indent + convert(l) : "")].join("\n");
+    return [lines[0], ...relative.map((l, i) => !free(i + 1) ? l : l ? indent + convert(l) : "")].join("\n");
   }
   openToClose(node, inner) {
     let end = node.openEnd - 2;
@@ -532,16 +487,18 @@ ${pi}`);
       this.placed.push({ x: right + 80, y: f.y, width: f.width, height: h });
       code = rewriteFrameProps(code, { name, x: right + 80 });
     }
+    const marked = withMarker(code.trim(), node);
     this.s.appendLeft(this.contentEnd(node), `
-${this.lineIndent(node.start)}${code.trim()}`);
-    const path12 = [...node.path];
-    path12[path12.length - 1] += 1;
-    this.selectPaths.push(path12);
+${this.lineIndent(node.start)}${marked}`);
+    if (marked === code.trim()) {
+      const path14 = [...node.path];
+      path14[path14.length - 1] += 1;
+      this.selectPaths.push(path14);
+    }
   }
   move(node, target, index) {
     if (isInside(target, node)) throw new EditError("Cannot move a node into itself.");
-    const raw = this.source.slice(this.contentStart(node), this.contentEnd(node));
-    const code = node.kind === "component" || node.kind === "element" ? raw.replace(/^<([\w.:-]+)/, "<$1 __tcsel") : raw;
+    const code = withMarker(this.source.slice(this.contentStart(node), this.contentEnd(node)), node);
     const kids = target.children.filter((c) => c.id !== node.id);
     const i = index === void 0 || index < 0 || index > kids.length ? kids.length : index;
     this.remove(node);
@@ -583,7 +540,7 @@ ${ind}${close}`);
       this.remove(node);
       return;
     }
-    const inner = this.source.slice(this.contentStart(kids[0]), this.contentEnd(kids[kids.length - 1]));
+    const inner = node.selfClosing ? "" : this.source.slice(node.openEnd, node.closeStart).trim();
     this.s.overwrite(this.contentStart(node), this.contentEnd(node), this.shift(inner, this.lineIndent(this.contentStart(node))));
     this.selectPaths.push(node.path);
   }
@@ -601,8 +558,36 @@ ${ind}${close}`);
       this.s.appendLeft(same.lastSpecifierEnd, `, ${name}`);
       return;
     }
+    this.addImportLine(`import { ${name} } from ${JSON.stringify(from)};`);
+  }
+  /**
+   * Imports `name` from `from` and returns the local name to write in JSX. When
+   * the name is already taken by something else (another import, a local
+   * component), it is imported under `alias` instead: `{ Search as SearchIcon }`.
+   */
+  importAs(name, from, alias) {
+    const existing = this.doc.imports.find((i) => i.source === from && !i.typeOnly)?.bindings.find((b) => b.imported === name);
+    if (existing) return existing.local;
+    const key = `${from}\0${name}`;
+    const pending = this.importedAs.get(key);
+    if (pending) return pending;
+    const taken = (n) => this.doc.declared.includes(n) || this.added.has(n) || this.doc.imports.some((i) => i.names.includes(n) || i.defaultName === n);
+    let local = name;
+    if (taken(local)) {
+      local = alias;
+      for (let k = 2; taken(local); k++) local = `${alias}${k}`;
+    }
+    this.added.add(local);
+    this.importedAs.set(key, local);
+    const specifier = local === name ? name : `${name} as ${local}`;
+    const same = this.doc.imports.find((i) => i.source === from && !i.typeOnly && i.lastSpecifierEnd !== null);
+    if (same) this.s.appendLeft(same.lastSpecifierEnd, `, ${specifier}`);
+    else this.addImportLine(`import { ${specifier} } from ${JSON.stringify(from)};`);
+    return local;
+  }
+  importedAs = /* @__PURE__ */ new Map();
+  addImportLine(line) {
     const last = this.doc.imports[this.doc.imports.length - 1];
-    const line = `import { ${name} } from ${JSON.stringify(from)};`;
     if (last) this.s.appendLeft(last.end, `
 ${line}`);
     else if (this.doc.prologueEnd) this.s.appendLeft(this.doc.prologueEnd, `
@@ -622,12 +607,7 @@ ${line}`);
     const known = /* @__PURE__ */ new Set([...this.doc.imports.flatMap((i) => [...i.names, ...i.defaultName ? [i.defaultName] : []]), ...this.added]);
     if (names.length && names.every((n) => known.has(n))) return;
     for (const n of names) this.added.add(n);
-    const last = this.doc.imports[this.doc.imports.length - 1];
-    if (last) this.s.appendLeft(last.end, `
-${statement}`);
-    else if (this.doc.prologueEnd) this.s.appendLeft(this.doc.prologueEnd, `
-${statement}`);
-    else this.prependImport(statement);
+    this.addImportLine(statement);
   }
   importsPrepended = false;
   /** First imports of a file: in order, with a blank line before the code. */
@@ -683,6 +663,43 @@ function componentNamesIn(jsx) {
   });
   return [...names];
 }
+function withMarker(code, node) {
+  if (node.kind !== "component" && node.kind !== "element") return code;
+  const m = /^<[\w.:-]+/.exec(code);
+  if (!m) return code;
+  let i = m[0].length;
+  if (code[i] === "<") {
+    for (let depth = 0; i < code.length; i++) {
+      if (code[i] === "<") depth++;
+      else if (code[i] === ">" && --depth === 0) {
+        i++;
+        break;
+      }
+    }
+  }
+  return `${code.slice(0, i)} __tcsel${code.slice(i)}`;
+}
+function literalLines(code) {
+  const out = /* @__PURE__ */ new Set();
+  if (!code.includes("\n") || !/[`"']/.test(code)) return out;
+  let ast;
+  try {
+    ast = parseModule(`<>${code}</>`);
+  } catch {
+    return out;
+  }
+  const ranges = [];
+  walk(ast, (n) => {
+    if (n.type === "TemplateLiteral" || n.type === "StringLiteral") ranges.push([n.start - 2, n.end - 2]);
+  });
+  if (!ranges.length) return out;
+  let offset = 0;
+  code.split("\n").forEach((line, i) => {
+    if (i > 0 && ranges.some(([a, b]) => offset > a && offset < b)) out.add(i);
+    offset += line.length + 1;
+  });
+  return out;
+}
 function parseJsx(jsx) {
   try {
     return parseModule(`<>${jsx}</>`);
@@ -724,6 +741,237 @@ function findDevice(id) {
   return id ? DEVICES.find((d) => d.id === id) : void 0;
 }
 
+// src/core/scaffold.ts
+import fs from "fs";
+import path from "path";
+var CANVAS_SUFFIX = ".canvas.tsx";
+function canvasFiles(config) {
+  const dir = path.join(config.root, config.canvasDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(CANVAS_SUFFIX)).sort((a, b) => canvasNameOf(a).localeCompare(canvasNameOf(b)));
+}
+function canvasNameOf(file) {
+  return path.basename(file).slice(0, -CANVAS_SUFFIX.length);
+}
+function assertCanvasName(name) {
+  if (!/^[a-z0-9][a-z0-9-_]*$/i.test(name)) throw new Error(`Invalid canvas name "${name}". Use letters, digits, - and _.`);
+  return name;
+}
+function canvasPath(config, name) {
+  assertCanvasName(name);
+  return path.join(config.root, config.canvasDir, `${name}${CANVAS_SUFFIX}`);
+}
+function writeIfChanged(file, content) {
+  if (fs.existsSync(file) && fs.readFileSync(file, "utf8") === content) return false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+  return true;
+}
+function routeDirOf(config) {
+  return path.join(config.root, config.routeDir);
+}
+function syncRoute(config) {
+  const routeDir = routeDirOf(config);
+  const registryFile = path.join(routeDir, "canvases.tsx");
+  const canvasDirAbs = path.join(config.root, config.canvasDir);
+  let rel = posix(path.relative(routeDir, canvasDirAbs));
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  const compareDir = path.join(routeDir, "compare");
+  const compares = fs.existsSync(compareDir) ? fs.readdirSync(compareDir).filter((f) => f.endsWith(CANVAS_SUFFIX)) : [];
+  const entries = [
+    ...canvasFiles(config).map((f) => `  ${JSON.stringify(canvasNameOf(f))}: lazy(() => import(${JSON.stringify(`${rel}/${f.replace(/\.tsx$/, "")}`)})),`),
+    // older versions rendered for Compare
+    ...compares.map((f) => `  ${JSON.stringify(`__compare__${canvasNameOf(f)}`)}: lazy(() => import(${JSON.stringify(`./compare/${f.replace(/\.tsx$/, "")}`)})),`)
+  ].join("\n");
+  const registry = `"use client";
+/* eslint-disable */
+// Generated by Truecanvas. Do not edit: it is regenerated when canvases are added or removed.
+import { lazy } from "react";
+import { TruecanvasHost, type HostProps } from "truecanvas/host";
+import { components } from "./components";
+
+const canvases = {
+${entries}
+};
+
+export default function Canvases(props: Omit<HostProps, "canvases" | "components">) {
+  return <TruecanvasHost {...props} canvases={canvases} components={components} />;
+}
+`;
+  const dm = config.darkMode;
+  const componentsFile = path.join(routeDir, "components.tsx");
+  if (!fs.existsSync(componentsFile)) writeIfChanged(componentsFile, componentRegistry(config, []));
+  const a = writeIfChanged(registryFile, registry);
+  if (config.framework === "vite") return writeIfChanged(path.join(routeDir, "entry.tsx"), viteEntry(config)) || a;
+  const page = `/* eslint-disable */
+// Generated by Truecanvas. Dev-only route that renders canvas frames.
+import { notFound } from "next/navigation";
+import Canvases from "../canvases";
+
+export const dynamic = "force-dynamic";
+
+export default async function TruecanvasFrame({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ canvas: string }>;
+  searchParams: Promise<Record<string, string | undefined>>;
+}) {
+  if (process.env.NODE_ENV !== "development") notFound();
+  const { canvas } = await params;
+  const query = await searchParams;
+  return (
+    <Canvases
+      canvas={canvas}
+      frame={query.frame ?? null}
+      theme={(query.theme as "light" | "dark" | "system" | undefined) ?? "system"}
+      darkMode={${JSON.stringify(dm)}}
+    />
+  );
+}
+`;
+  return writeIfChanged(path.join(routeDir, "[canvas]", "page.tsx"), page) || a;
+}
+function viteEntry(config) {
+  const css = (config.css ?? viteStylesheets(config.root)).map((f) => f.startsWith("/") ? f : f.startsWith("./") ? f.slice(1) : fs.existsSync(path.join(config.root, f)) ? `/${f}` : f);
+  return `/* eslint-disable */
+// Generated by Truecanvas. Dev-only entry that renders canvas frames at /truecanvas/<canvas>.
+${css.map((f) => `import ${JSON.stringify(f)};`).join("\n")}
+import { createRoot } from "react-dom/client";
+import Canvases from "./canvases";
+
+const query = new URLSearchParams(location.search);
+const canvas = decodeURIComponent(location.pathname.split("/")[2] ?? "");
+
+createRoot(document.getElementById("tc-root")!).render(
+  <Canvases
+    canvas={canvas}
+    frame={query.get("frame")}
+    theme={(query.get("theme") as "light" | "dark" | "system" | null) ?? "system"}
+    darkMode={${JSON.stringify(config.darkMode)}}
+  />,
+);
+`;
+}
+function viteStylesheets(root) {
+  let html = "";
+  try {
+    html = fs.readFileSync(path.join(root, "index.html"), "utf8");
+  } catch {
+    return [];
+  }
+  const src = /<script[^>]*type=["']module["'][^>]*src=["']([^"']+)["']/i.exec(html)?.[1] ?? /<script[^>]*src=["']([^"']+)["'][^>]*type=["']module["']/i.exec(html)?.[1];
+  if (!src || /^https?:/.test(src)) return [];
+  const entry = path.join(root, src.replace(/^\//, ""));
+  let code = "";
+  try {
+    code = fs.readFileSync(entry, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const m of code.matchAll(/^\s*import\s+["']([^"']+\.(?:css|scss|sass|less|styl|pcss))["']/gm)) {
+    const spec = m[1];
+    out.push(spec.startsWith(".") ? `/${posix(path.relative(root, path.resolve(path.dirname(entry), spec)))}` : spec);
+  }
+  return out;
+}
+var STARTER_CANVAS = `"use client";
+import { Canvas, Frame } from "truecanvas";
+
+/*
+ * A placeholder page. Replace the Welcome frame with your own components:
+ * drag them from Assets, draw frames with F, or ask your agent over MCP.
+ * Inline styles keep it readable in any app, with or without Tailwind.
+ */
+export default function StarterCanvas() {
+  return (
+    <Canvas>
+      <Frame name="Welcome" x={0} y={0} width={1200} height={760}>
+        <div
+          style={{
+            height: "100%",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif",
+            color: "light-dark(#1d1d1b, #ededea)",
+            backgroundColor: "light-dark(#f6f5f2, #121211)",
+            backgroundImage: "radial-gradient(light-dark(rgba(0,0,0,.07), rgba(255,255,255,.06)) 1px, transparent 1px), radial-gradient(circle at 50% 38%, rgba(255,138,92,.16), transparent 55%)",
+            backgroundSize: "22px 22px, 100% 100%",
+          }}
+        >
+          <div
+            style={{
+              width: 520,
+              padding: 40,
+              borderRadius: 24,
+              backgroundColor: "light-dark(#ffffff, #1b1b1a)",
+              border: "1px solid light-dark(#e9e8e4, #2a2a28)",
+              boxShadow: "0 1px 2px rgba(0,0,0,.04), 0 24px 60px -24px rgba(0,0,0,.25)",
+            }}
+          >
+            <svg width="44" height="44" viewBox="0 0 64 64" aria-hidden>
+              <defs>
+                <linearGradient id="tc-starter" x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="0" stopColor="#ff9466" />
+                  <stop offset="1" stopColor="#ea6a3c" />
+                </linearGradient>
+              </defs>
+              <rect width="64" height="64" rx="15" fill="url(#tc-starter)" />
+              <path fill="#f6f5f1" fillRule="evenodd" d="M10.5 10.5h43v13.1h-43z M25.5 16.8h13v36.7h-13z" />
+            </svg>
+            <h1 style={{ margin: "22px 0 6px", fontSize: 26, lineHeight: "32px", fontWeight: 650, letterSpacing: "-0.02em" }}>Your canvas is ready</h1>
+            <p style={{ margin: 0, fontSize: 15, lineHeight: "23px", color: "light-dark(#6b6b66, #a3a39d)" }}>
+              Everything here is real code from your app. Replace this frame with your own components.
+            </p>
+            <div style={{ marginTop: 28, display: "flex", flexDirection: "column", gap: 14 }}>
+              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
+                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, backgroundColor: "light-dark(#f3f2ee, #262624)", border: "1px solid light-dark(#e3e1dc, #34342f)" }}>Assets</span>
+                <span>Drag a component from your design system onto a frame</span>
+              </div>
+              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
+                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, backgroundColor: "light-dark(#f3f2ee, #262624)", border: "1px solid light-dark(#e3e1dc, #34342f)" }}>F</span>
+                <span>Draw a frame, or pick an iPhone or desktop size</span>
+              </div>
+              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
+                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, color: "#fff", backgroundColor: "#ee7445", border: "1px solid #e0652f" }}>Agent</span>
+                <span>Ask: \u201CBuild a pricing page with our components\u201D</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </Frame>
+    </Canvas>
+  );
+}
+`;
+function componentRegistry(config, specs) {
+  const routeDir = routeDirOf(config);
+  const lines = specs.map((c) => {
+    let from = c.library;
+    if (!from) {
+      from = posix(path.relative(routeDir, path.join(config.root, c.file))).replace(/\.(tsx|ts|jsx|js)$/, "");
+      if (!from.startsWith(".")) from = `./${from}`;
+    }
+    return `  ${JSON.stringify(c.name)}: lazy(() => import(${JSON.stringify(from)}).then((m) => ({ default: m[${JSON.stringify(c.name)}] }))),`;
+  });
+  return `"use client";
+/* eslint-disable */
+// Generated by Truecanvas. Do not edit: it is regenerated when components change.
+import { lazy, type ComponentType } from "react";
+
+// any: components with required props are rendered with whatever the preview passes
+export const components: Record<string, ComponentType<any>> = {
+${lines.join("\n")}
+};
+`;
+}
+function syncComponentRegistry(config, specs) {
+  const file = path.join(routeDirOf(config), "components.tsx");
+  return writeIfChanged(file, componentRegistry(config, specs));
+}
+
 // src/core/comments.ts
 import fs2 from "fs";
 import path2 from "path";
@@ -734,7 +982,7 @@ var Comments = class {
   }
   config;
   file(canvas) {
-    return path2.join(this.config.root, this.config.canvasDir, `${canvas}.comments.json`);
+    return path2.join(this.config.root, this.config.canvasDir, `${assertCanvasName(canvas)}.comments.json`);
   }
   list(canvas) {
     try {
@@ -755,8 +1003,9 @@ var Comments = class {
   }
   update(canvas, id, fn) {
     const threads = this.list(canvas);
-    const t = threads.find((x) => x.id === id || x.id.startsWith(id));
-    if (!t) throw new Error(`No comment thread "${id}".`);
+    const prefixed = id.length >= 4 ? threads.filter((x) => x.id.startsWith(id)) : [];
+    const t = threads.find((x) => x.id === id) ?? (prefixed.length === 1 ? prefixed[0] : void 0);
+    if (!t) throw new Error(prefixed.length > 1 ? `"${id}" matches several comment threads. Use the full id.` : `No comment thread "${id}".`);
     fn(t);
     this.save(canvas, threads);
     return t;
@@ -833,6 +1082,10 @@ function run(cmd, cwd, args, timeout, opts = {}) {
     if (opts.input !== void 0) child.stdin?.end(opts.input);
   });
 }
+function safeRef(ref) {
+  if (!ref || ref.startsWith("-") || !/^[\w./~^@{}+-]+$/.test(ref) || ref.includes("..")) throw new GitError(`Invalid git ref "${ref}".`);
+  return ref;
+}
 var Git = class {
   constructor(cwd) {
     this.cwd = cwd;
@@ -845,9 +1098,12 @@ var Git = class {
     } catch {
       return { repo: false, root: null, branch: null, unborn: false, upstream: null, ahead: 0, behind: 0, files: [], user: null, defaultBranch: null, remote: null };
     }
-    const out = await git(this.cwd, ["status", "--porcelain=v2", "--branch", "--untracked-files=all", "--", "."]);
+    const out = await git(this.cwd, ["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=all", "--", "."]);
+    const prefix = await this.prefix();
     const s = { repo: true, root, branch: null, unborn: false, upstream: null, ahead: 0, behind: 0, files: [], user: null, defaultBranch: null, remote: null };
-    for (const line of out.split("\n")) {
+    const entries = out.split("\0");
+    for (let i = 0; i < entries.length; i++) {
+      const line = entries[i];
       if (line.startsWith("# branch.head ")) s.branch = line.slice(14) === "(detached)" ? null : line.slice(14);
       else if (line.startsWith("# branch.oid ")) s.unborn = line.slice(13) === "(initial)";
       else if (line.startsWith("# branch.upstream ")) s.upstream = line.slice(18);
@@ -857,10 +1113,13 @@ var Git = class {
       } else if (line.startsWith("1 ") || line.startsWith("2 ")) {
         const parts = line.split(" ");
         const xy = parts[1];
-        const file = line.startsWith("2 ") ? line.split("	")[0].split(" ").slice(9).join(" ") : parts.slice(8).join(" ");
+        const file = parts.slice(line.startsWith("2 ") ? 9 : 8).join(" ");
+        if (line.startsWith("2 ")) i++;
         const code = xy.replace(".", "")[0] ?? "M";
-        s.files.push({ path: this.rel(root, file), status: code === "A" ? "added" : code === "D" ? "deleted" : code === "R" ? "renamed" : "modified", staged: xy[0] !== "." });
-      } else if (line.startsWith("? ")) s.files.push({ path: this.rel(root, line.slice(2)), status: "untracked", staged: false });
+        s.files.push({ path: this.rel(prefix, file), status: code === "A" ? "added" : code === "D" ? "deleted" : code === "R" ? "renamed" : "modified", staged: xy[0] !== "." });
+      } else if (line.startsWith("u ")) {
+        s.files.push({ path: this.rel(prefix, line.split(" ").slice(10).join(" ")), status: "conflicted", staged: false });
+      } else if (line.startsWith("? ")) s.files.push({ path: this.rel(prefix, line.slice(2)), status: "untracked", staged: false });
     }
     s.user = (await git(this.cwd, ["config", "user.name"]).catch(() => "")).trim() || null;
     s.remote = (await git(this.cwd, ["remote", "get-url", "origin"]).catch(() => "")).trim() || null;
@@ -881,11 +1140,12 @@ var Git = class {
   }
   /** When a commit was made (ms). */
   async commitAt(ref) {
-    const out = await git(this.cwd, ["log", "-1", "--format=%ct", ref]).catch(() => "");
+    const out = await git(this.cwd, ["log", "-1", "--format=%ct", safeRef(ref), "--"]).catch(() => "");
     return Number(out.trim() || 0) * 1e3;
   }
   /** Commit where this branch left `base`. */
   async mergeBase(base) {
+    safeRef(base);
     for (const ref of [`origin/${base}`, base]) {
       const out = await git(this.cwd, ["merge-base", ref, "HEAD"]).catch(() => "");
       if (out.trim()) return out.trim();
@@ -894,7 +1154,7 @@ var Git = class {
   }
   /** Files changed between a commit and HEAD, from the project root. */
   async changedSince(ref) {
-    const out = await git(this.cwd, ["diff", "--name-only", "--relative", `${ref}...HEAD`]).catch(() => "");
+    const out = await git(this.cwd, ["diff", "--name-only", "--relative", `${safeRef(ref)}...HEAD`, "--"]).catch(() => "");
     return out.split("\n").filter(Boolean);
   }
   /** Unified diff of these files against HEAD, including new files. */
@@ -911,9 +1171,10 @@ var Git = class {
    * (used for PR screenshots), and pushes it. Returns the branch tip.
    */
   async commitToSideBranch(branch, files, message) {
+    safeRef(branch);
     const tip = (await git(this.cwd, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).catch(() => "")).trim() || (await git(this.cwd, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`]).catch(() => "")).trim();
     const os = await import("os");
-    const fs11 = await import("fs");
+    const fs13 = await import("fs");
     const index = path3.join(os.tmpdir(), `truecanvas-index-${process.pid}-${Date.now()}`);
     const env = { GIT_INDEX_FILE: index };
     try {
@@ -928,7 +1189,7 @@ var Git = class {
       await git(this.cwd, ["update-ref", `refs/heads/${branch}`, commit]);
       await git(this.cwd, ["push", "origin", `refs/heads/${branch}:refs/heads/${branch}`], 12e4);
     } finally {
-      fs11.rmSync(index, { force: true });
+      fs13.rmSync(index, { force: true });
     }
   }
   // ---------- GitHub (gh CLI) ----------
@@ -952,7 +1213,7 @@ var Git = class {
     return { number: pr.number, url: pr.url, title: pr.title, state: pr.state, draft: pr.isDraft, review: pr.reviewDecision || null, checks };
   }
   async createPullRequest(opts) {
-    const out = await run("gh", this.cwd, ["pr", "create", "--title", opts.title, "--body-file", "-", "--base", opts.base, ...opts.draft ? ["--draft"] : []], 12e4, { input: opts.body });
+    const out = await run("gh", this.cwd, ["pr", "create", "--title", opts.title, "--body-file", "-", "--base", safeRef(opts.base), ...opts.draft ? ["--draft"] : []], 12e4, { input: opts.body });
     return out.trim().split("\n").pop() ?? "";
   }
   /** Creates a GitHub repo for this project and pushes it (gh repo create). */
@@ -962,8 +1223,16 @@ var Git = class {
     return (await git(this.cwd, ["remote", "get-url", "origin"])).trim();
   }
   /** git reports paths from the repo root; we show them from the project root. */
-  rel(root, file) {
-    return path3.relative(this.cwd, path3.join(root, file));
+  rel(prefix, file) {
+    return file.startsWith(prefix) ? file.slice(prefix.length) : posix(path3.posix.relative(prefix, file));
+  }
+  /**
+   * The project folder inside the repo ("apps/web/", or "" at the root), as git
+   * itself sees it. Asking git instead of comparing file system paths holds up
+   * through symlinks (macOS /var → /private/var), junctions and Windows short names.
+   */
+  async prefix() {
+    return (await git(this.cwd, ["rev-parse", "--show-prefix"]).catch(() => "")).trim();
   }
   async branches() {
     const out = await git(this.cwd, ["branch", "-a", "--format=%(refname)%09%(HEAD)"]).catch(() => "");
@@ -991,9 +1260,8 @@ var Git = class {
   }
   /** A file's content at a ref, or null if it doesn't exist there. */
   async show(ref, file) {
-    const root = (await git(this.cwd, ["rev-parse", "--show-toplevel"])).trim();
-    const inRepo = path3.relative(root, path3.join(this.cwd, file)).split(path3.sep).join("/");
-    return git(this.cwd, ["show", `${ref}:${inRepo}`]).catch(() => null);
+    const inRepo = path3.posix.normalize(`${await this.prefix()}${posix(file)}`);
+    return git(this.cwd, ["show", `${safeRef(ref)}:${inRepo}`, "--"]).catch(() => null);
   }
   async commit(message, files) {
     if (!message.trim()) throw new GitError("Write a commit message.");
@@ -1015,14 +1283,14 @@ var Git = class {
     });
   }
   async switch(branch, create = false) {
-    if (!/^[\w./-]+$/.test(branch) || branch.startsWith("-")) throw new GitError("Invalid branch name.");
+    safeRef(branch);
     await git(this.cwd, create ? ["switch", "-c", branch] : ["switch", branch]);
   }
 };
 
 // src/core/workspace.ts
-import fs8 from "fs";
-import path9 from "path";
+import fs7 from "fs";
+import path8 from "path";
 import { createRequire } from "module";
 
 // src/core/link.ts
@@ -1243,6 +1511,7 @@ function parseTargetDoc(file, source) {
 var PAGE = /^page\.(tsx|jsx|ts|js)$/;
 var LAYOUT = ["layout.tsx", "layout.jsx", "layout.js", "layout.ts"];
 function listRoutes(config) {
+  if (config.framework !== "next") return [];
   const appDir = path4.join(config.root, config.appDir);
   const out = [];
   const walkDir = (dir, segments) => {
@@ -1255,7 +1524,7 @@ function listRoutes(config) {
     for (const e of entries) {
       if (e.isFile() && PAGE.test(e.name)) {
         const visible = segments.filter((s) => !/^\(.*\)$/.test(s) && !s.startsWith("@"));
-        out.push({ route: `/${visible.join("/")}`, file: path4.relative(config.root, path4.join(dir, e.name)), dynamic: segments.some((s) => s.startsWith("[")) });
+        out.push({ route: `/${visible.join("/")}`, file: posix(path4.relative(config.root, path4.join(dir, e.name))), dynamic: segments.some((s) => s.startsWith("[")) });
       }
       if (e.isDirectory() && !e.name.startsWith("_") && e.name !== "truecanvas" && e.name !== "api" && e.name !== "node_modules") walkDir(path4.join(dir, e.name), [...segments, e.name]);
     }
@@ -1274,7 +1543,7 @@ function extract(file, canvasFile, config, layout) {
     if (/\.(css|scss|sass|less)$/.test(src)) continue;
     const from = repoint(config, src, file, canvasFile);
     const text = source.slice(stmt.start, stmt.end);
-    imports.push(from === src ? text : text.replace(JSON.stringify(src), JSON.stringify(from)).replace(`'${src}'`, `'${from}'`));
+    imports.push(from === src ? text : rewriteImportSource(text, src, from));
   }
   return { jsx: source.slice(info.node.start, info.node.end), imports };
 }
@@ -1287,7 +1556,7 @@ function layoutFiles(config, pageFile) {
   const out = [];
   for (let dir = path4.dirname(path4.resolve(config.root, pageFile)); dir.startsWith(appDir) && dir !== appDir; dir = path4.dirname(dir)) {
     const file = LAYOUT.map((f) => path4.join(dir, f)).find((f) => fs3.existsSync(f));
-    if (file) out.push(path4.relative(config.root, file));
+    if (file) out.push(posix(path4.relative(config.root, file)));
   }
   return out;
 }
@@ -1319,7 +1588,8 @@ function routeFrame(config, pageFile, canvasFile) {
     const layout = extract(file, canvasAbs, config, true);
     const holes = layout ? (layout.jsx.match(/\{\s*children\s*\}/g) ?? []).length : 0;
     if (layout && holes === 1) {
-      jsx = layout.jsx.replace(/\{\s*children\s*\}/, jsx.startsWith("<>") ? jsx.slice(2, -3) : jsx);
+      const inner = jsx.startsWith("<>") ? jsx.slice(2, -3) : jsx;
+      jsx = layout.jsx.replace(/\{\s*children\s*\}/, () => inner);
       imports.push(...layout.imports);
     } else {
       const local = `RouteLayout${i++ || ""}`;
@@ -1349,6 +1619,18 @@ function readSource(config, rel) {
     return null;
   }
 }
+var parseMemo = /* @__PURE__ */ new Map();
+function memoParse(key, source, parse) {
+  let hit = parseMemo.get(key);
+  if (!hit || hit.source !== source) {
+    hit = { source, doc: parse() };
+    parseMemo.set(key, hit);
+  }
+  return hit.doc && { ...hit.doc, frames: hit.doc.frames.map(cloneTree) };
+}
+function cloneTree(n) {
+  return { ...n, children: n.children.map(cloneTree) };
+}
 function resolveLinks(config, doc) {
   if (!doc.frames.some((f) => f.page || f.component)) return doc;
   return { ...doc, frames: doc.frames.map((f) => f.component ? linkComponent(config, f) : f.page ? linkFrame(config, f) : f) };
@@ -1361,7 +1643,7 @@ function linkComponent(config, original) {
   const frame = { ...original };
   const { file, name } = splitComponentRef(frame.component);
   const source = readSource(config, file);
-  const doc = source === null ? null : parseModuleDoc(file, source);
+  const doc = source === null ? null : memoParse(`module:${file}`, source, () => parseModuleDoc(file, source));
   const own = doc?.frames.find((f) => f.frameName === name);
   if (!own) {
     frame.link = { kind: "component", page: file, route: name, files: [], editable: false, reason: source === null ? `${file} doesn't exist anymore.` : `${file} has no exported component ${name} returning JSX.` };
@@ -1384,7 +1666,7 @@ function linkFrame(config, original) {
   const chain = wrapperChain(original);
   const files = [];
   let current;
-  const pageDoc = parseSourceDoc(page, pageSource, false);
+  const pageDoc = memoParse(`page:${page}`, pageSource, () => parseSourceDoc(page, pageSource, false));
   if (pageDoc) {
     current = flatten(pageDoc.frames[0].children[0]);
     files.push(page);
@@ -1394,7 +1676,7 @@ function linkFrame(config, original) {
   const layouts = layoutFiles(config, page);
   layouts.forEach((rel, i) => {
     const src = readSource(config, rel);
-    const ldoc = src === null ? null : parseSourceDoc(rel, src, true);
+    const ldoc = src === null ? null : memoParse(`layout:${rel}`, src, () => parseSourceDoc(rel, src, true));
     const root = ldoc?.frames[0].children[0];
     const slot = root && findSlot(root);
     if (root && slot) {
@@ -1479,7 +1761,7 @@ function explorationBody(config, frame, canvasRel) {
       const src = stmt.source.value;
       const from = repoint(config, src, pageAbs, path5.join(config.root, canvasRel));
       const text = source.slice(stmt.start, stmt.end);
-      imports.push(from === src ? text : text.replace(JSON.stringify(src), JSON.stringify(from)).replace(`'${src}'`, `'${from}'`));
+      imports.push(from === src ? text : rewriteImportSource(text, src, from));
     }
     jsx = unwrapFragment(source.slice(info.node.start, info.node.end));
   } else {
@@ -1778,8 +2060,8 @@ export function TextAnimate({ effect = "words", stagger = 0.06, delay = 0, durat
 function motionFiles(config) {
   const glob = config.components[0] ?? "components/**/*.tsx";
   const base = glob.split("/").filter((p) => !p.includes("*")).join("/") || "components";
-  const dir = path6.join(base, "motion");
-  return { reveal: path6.join(dir, "reveal.tsx"), text: path6.join(dir, "text-animate.tsx") };
+  const dir = `${base}/motion`;
+  return { reveal: `${dir}/reveal.tsx`, text: `${dir}/text-animate.tsx` };
 }
 function ensureMotionComponents(config) {
   const files = motionFiles(config);
@@ -1891,193 +2173,11 @@ ${indentBlock(indentBlock(jsx.trim()))}
 `;
 }
 function newComponentPath(config, name) {
-  const rel = path7.join(componentsDir(config), `${kebab(name)}.tsx`);
+  const rel = `${componentsDir(config)}/${kebab(name)}.tsx`;
   if (fs6.existsSync(path7.join(config.root, rel))) throw new EditError(`${rel} already exists. Pick another name.`);
   return rel;
 }
 
-// src/core/scaffold.ts
-import fs7 from "fs";
-import path8 from "path";
-var CANVAS_SUFFIX = ".canvas.tsx";
-var ROUTE = "truecanvas";
-function canvasFiles(config) {
-  const dir = path8.join(config.root, config.canvasDir);
-  if (!fs7.existsSync(dir)) return [];
-  return fs7.readdirSync(dir).filter((f) => f.endsWith(CANVAS_SUFFIX)).sort((a, b) => canvasNameOf(a).localeCompare(canvasNameOf(b)));
-}
-function canvasNameOf(file) {
-  return path8.basename(file).slice(0, -CANVAS_SUFFIX.length);
-}
-function canvasPath(config, name) {
-  if (!/^[a-z0-9][a-z0-9-_]*$/i.test(name)) throw new Error(`Invalid canvas name "${name}". Use letters, digits, - and _.`);
-  return path8.join(config.root, config.canvasDir, `${name}${CANVAS_SUFFIX}`);
-}
-function writeIfChanged(file, content) {
-  if (fs7.existsSync(file) && fs7.readFileSync(file, "utf8") === content) return false;
-  fs7.mkdirSync(path8.dirname(file), { recursive: true });
-  fs7.writeFileSync(file, content);
-  return true;
-}
-function syncRoute(config) {
-  const routeDir = path8.join(config.root, config.appDir, ROUTE);
-  const pageFile = path8.join(routeDir, "[canvas]", "page.tsx");
-  const registryFile = path8.join(routeDir, "canvases.tsx");
-  const canvasDirAbs = path8.join(config.root, config.canvasDir);
-  let rel = path8.relative(routeDir, canvasDirAbs);
-  if (!rel.startsWith(".")) rel = `./${rel}`;
-  const compareDir = path8.join(routeDir, "compare");
-  const compares = fs7.existsSync(compareDir) ? fs7.readdirSync(compareDir).filter((f) => f.endsWith(CANVAS_SUFFIX)) : [];
-  const entries = [
-    ...canvasFiles(config).map((f) => `  ${JSON.stringify(canvasNameOf(f))}: lazy(() => import(${JSON.stringify(`${rel}/${f.replace(/\.tsx$/, "")}`)})),`),
-    // older versions rendered for Compare
-    ...compares.map((f) => `  ${JSON.stringify(`__compare__${canvasNameOf(f)}`)}: lazy(() => import(${JSON.stringify(`./compare/${f.replace(/\.tsx$/, "")}`)})),`)
-  ].join("\n");
-  const registry = `"use client";
-/* eslint-disable */
-// Generated by Truecanvas. Do not edit: it is regenerated when canvases are added or removed.
-import { lazy } from "react";
-import { TruecanvasHost, type HostProps } from "truecanvas/host";
-import { components } from "./components";
-
-const canvases = {
-${entries}
-};
-
-export default function Canvases(props: Omit<HostProps, "canvases" | "components">) {
-  return <TruecanvasHost {...props} canvases={canvases} components={components} />;
-}
-`;
-  const dm = config.darkMode;
-  const page = `/* eslint-disable */
-// Generated by Truecanvas. Dev-only route that renders canvas frames.
-import { notFound } from "next/navigation";
-import Canvases from "../canvases";
-
-export const dynamic = "force-dynamic";
-
-export default async function TruecanvasFrame({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ canvas: string }>;
-  searchParams: Promise<Record<string, string | undefined>>;
-}) {
-  if (process.env.NODE_ENV !== "development") notFound();
-  const { canvas } = await params;
-  const query = await searchParams;
-  return (
-    <Canvases
-      canvas={canvas}
-      frame={query.frame ?? null}
-      theme={(query.theme as "light" | "dark" | "system" | undefined) ?? "system"}
-      darkMode={${JSON.stringify(dm)}}
-    />
-  );
-}
-`;
-  const componentsFile = path8.join(routeDir, "components.tsx");
-  if (!fs7.existsSync(componentsFile)) writeIfChanged(componentsFile, componentRegistry(config, []));
-  const a = writeIfChanged(registryFile, registry);
-  const b = writeIfChanged(pageFile, page);
-  return a || b;
-}
-var STARTER_CANVAS = `"use client";
-import { Canvas, Frame } from "truecanvas";
-
-/*
- * A placeholder page. Replace the Welcome frame with your own components:
- * drag them from Assets, draw frames with F, or ask your agent over MCP.
- * Inline styles keep it readable in any app, with or without Tailwind.
- */
-export default function StarterCanvas() {
-  return (
-    <Canvas>
-      <Frame name="Welcome" x={0} y={0} width={1200} height={760}>
-        <div
-          style={{
-            height: "100%",
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
-            fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif",
-            color: "light-dark(#1d1d1b, #ededea)",
-            backgroundColor: "light-dark(#f6f5f2, #121211)",
-            backgroundImage: "radial-gradient(light-dark(rgba(0,0,0,.07), rgba(255,255,255,.06)) 1px, transparent 1px), radial-gradient(circle at 50% 38%, rgba(255,138,92,.16), transparent 55%)",
-            backgroundSize: "22px 22px, 100% 100%",
-          }}
-        >
-          <div
-            style={{
-              width: 520,
-              padding: 40,
-              borderRadius: 24,
-              backgroundColor: "light-dark(#ffffff, #1b1b1a)",
-              border: "1px solid light-dark(#e9e8e4, #2a2a28)",
-              boxShadow: "0 1px 2px rgba(0,0,0,.04), 0 24px 60px -24px rgba(0,0,0,.25)",
-            }}
-          >
-            <svg width="44" height="44" viewBox="0 0 64 64" aria-hidden>
-              <defs>
-                <linearGradient id="tc-starter" x1="0" y1="0" x2="0" y2="1">
-                  <stop offset="0" stopColor="#ff9466" />
-                  <stop offset="1" stopColor="#ea6a3c" />
-                </linearGradient>
-              </defs>
-              <rect width="64" height="64" rx="15" fill="url(#tc-starter)" />
-              <path fill="#f6f5f1" fillRule="evenodd" d="M10.5 10.5h43v13.1h-43z M25.5 16.8h13v36.7h-13z" />
-            </svg>
-            <h1 style={{ margin: "22px 0 6px", fontSize: 26, lineHeight: "32px", fontWeight: 650, letterSpacing: "-0.02em" }}>Your canvas is ready</h1>
-            <p style={{ margin: 0, fontSize: 15, lineHeight: "23px", color: "light-dark(#6b6b66, #a3a39d)" }}>
-              Everything here is real code from your app. Replace this frame with your own components.
-            </p>
-            <div style={{ marginTop: 28, display: "flex", flexDirection: "column", gap: 14 }}>
-              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
-                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, backgroundColor: "light-dark(#f3f2ee, #262624)", border: "1px solid light-dark(#e3e1dc, #34342f)" }}>Assets</span>
-                <span>Drag a component from your design system onto a frame</span>
-              </div>
-              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
-                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, backgroundColor: "light-dark(#f3f2ee, #262624)", border: "1px solid light-dark(#e3e1dc, #34342f)" }}>F</span>
-                <span>Draw a frame, or pick an iPhone or desktop size</span>
-              </div>
-              <div style={{ display: "flex", alignItems: "center", gap: 14, fontSize: 14 }}>
-                <span style={{ minWidth: 58, textAlign: "center", padding: "3px 8px", borderRadius: 7, fontSize: 12, fontWeight: 600, color: "#fff", backgroundColor: "#ee7445", border: "1px solid #e0652f" }}>Agent</span>
-                <span>Ask: \u201CBuild a pricing page with our components\u201D</span>
-              </div>
-            </div>
-          </div>
-        </div>
-      </Frame>
-    </Canvas>
-  );
-}
-`;
-function componentRegistry(config, specs) {
-  const routeDir = path8.join(config.root, config.appDir, ROUTE);
-  const lines = specs.map((c) => {
-    let from = c.library;
-    if (!from) {
-      from = path8.relative(routeDir, path8.join(config.root, c.file)).replace(/\.(tsx|ts|jsx|js)$/, "");
-      if (!from.startsWith(".")) from = `./${from}`;
-    }
-    return `  ${JSON.stringify(c.name)}: lazy(() => import(${JSON.stringify(from)}).then((m) => ({ default: m[${JSON.stringify(c.name)}] }))),`;
-  });
-  return `"use client";
-/* eslint-disable */
-// Generated by Truecanvas. Do not edit: it is regenerated when components change.
-import { lazy, type ComponentType } from "react";
-
-// any: components with required props are rendered with whatever the preview passes
-export const components: Record<string, ComponentType<any>> = {
-${lines.join("\n")}
-};
-`;
-}
-function syncComponentRegistry(config, specs) {
-  const file = path8.join(config.root, config.appDir, ROUTE, "components.tsx");
-  return writeIfChanged(file, componentRegistry(config, specs));
-}
-
 // src/core/workspace.ts
 var require2 = createRequire(import.meta.url);
 var MARK = "__tcsel";
@@ -2094,13 +2194,14 @@ var Workspace = class {
     this.catalog = new Catalog(config.root, config.components, config.libraries);
     this.comments = new Comments(config);
     this.git = new Git(config.root);
-    for (const c of this.canvases()) this.sources.set(c, fs8.readFileSync(this.file(c), "utf8"));
+    for (const c of this.canvases()) this.sources.set(c, fs7.readFileSync(this.file(c), "utf8"));
   }
   config;
   catalog;
   sources = /* @__PURE__ */ new Map();
   undoStacks = /* @__PURE__ */ new Map();
   redoStacks = /* @__PURE__ */ new Map();
+  /** Activity across canvases: labels only, never file copies. */
   feed = [];
   seq = 0;
   queue = Promise.resolve();
@@ -2124,29 +2225,52 @@ var Workspace = class {
     return canvasPath(this.config, canvas);
   }
   relFile(canvas) {
-    return path9.relative(this.config.root, this.file(canvas));
+    return posix(path8.relative(this.config.root, this.file(canvas)));
   }
   read(canvas) {
     const file = this.file(canvas);
-    if (!fs8.existsSync(file)) throw new EditError(`Canvas "${canvas}" does not exist. Canvases: ${this.canvases().join(", ") || "none"}`);
-    const src = fs8.readFileSync(file, "utf8");
+    if (!fs7.existsSync(file)) throw new EditError(`Canvas "${canvas}" does not exist. Canvases: ${this.canvases().join(", ") || "none"}`);
+    const src = fs7.readFileSync(file, "utf8");
     if (!this.sources.has(canvas)) this.sources.set(canvas, src);
     return src;
   }
   doc(canvas) {
     return this.docFrom(canvas, this.read(canvas));
   }
-  /** A canvas doc with linked frames resolved to their page's layers. */
+  /**
+   * A canvas doc with linked frames resolved to their page's layers. Resolving
+   * reads and parses every linked page and layout, so the result is reused
+   * until the canvas source or one of those files changes (checked with stat).
+   */
   docFrom(canvas, source) {
-    return resolveLinks(this.config, parseCanvas(canvas, this.relFile(canvas), source));
+    const hit = this.docCache.get(canvas);
+    if (hit && hit.source === source && hit.stamps.every(([rel, stamp]) => this.stamp(rel) === stamp)) return { ...hit.doc, rev: ++this.revision };
+    const doc = resolveLinks(this.config, parseCanvas(canvas, this.relFile(canvas), source));
+    const files = new Set(doc.frames.flatMap((f) => [...f.link?.files ?? [], ...f.page ? [f.page] : []]));
+    this.docCache.set(canvas, { source, doc, stamps: [...files].map((rel) => [rel, this.stamp(rel)]) });
+    return { ...doc, rev: ++this.revision };
+  }
+  /** a doc computed later reflects the files at least as recently: its rev is higher */
+  revision = 0;
+  docCache = /* @__PURE__ */ new Map();
+  stamp(rel) {
+    try {
+      const st = fs7.statSync(path8.join(this.config.root, rel));
+      return `${st.mtimeMs}:${st.size}`;
+    } catch {
+      return "missing";
+    }
   }
   /** Where a node's code lives: the canvas, or a linked page/layout file. */
   nodeSource(canvas, id) {
-    const hit = findNode(this.doc(canvas), id);
+    const doc = this.doc(canvas);
+    const hit = findNode(doc, id);
     if (!hit) return null;
-    const rel = fileOfId(id) ?? this.relFile(canvas);
-    const abs = path9.join(this.config.root, rel);
-    return { node: hit.node, rel, abs, source: fs8.readFileSync(abs, "utf8") };
+    const linked = fileOfId(id);
+    if (linked) assertShown(doc, linked);
+    const rel = linked ?? this.relFile(canvas);
+    const abs = path8.join(this.config.root, rel);
+    return { node: hit.node, rel, abs, source: fs7.readFileSync(abs, "utf8") };
   }
   /** Page and layout files shown by linked frames, across all canvases (the Git panel counts them as design files). */
   linkedFiles() {
@@ -2165,7 +2289,7 @@ var Workspace = class {
    */
   designFiles() {
     const m = motionFiles(this.config);
-    return [...this.linkedFiles(), ...[m.reveal, m.text].filter((f) => fs8.existsSync(path9.join(this.config.root, f)))];
+    return [...this.linkedFiles(), ...[m.reveal, m.text].filter((f) => fs7.existsSync(path8.join(this.config.root, f)))];
   }
   /** Canvases with a linked frame showing this page or layout file. */
   canvasesLinking(rel) {
@@ -2181,20 +2305,21 @@ var Workspace = class {
   linkedFileChanged(rel) {
     let next;
     try {
-      next = fs8.readFileSync(path9.join(this.config.root, rel), "utf8");
+      next = fs7.readFileSync(path8.join(this.config.root, rel), "utf8");
     } catch {
       next = "";
     }
     const key = `file:${rel}`;
     if (this.sources.get(key) === next) return;
     this.sources.set(key, next);
+    this.docCache.clear();
     for (const c of this.canvasesLinking(rel)) this.emit({ type: "doc", canvas: c, doc: this.doc(c) });
   }
   createCanvas(name, actor, content = STARTER_CANVAS) {
     const file = canvasPath(this.config, name);
-    if (fs8.existsSync(file)) throw new EditError(`Canvas "${name}" already exists.`);
-    fs8.mkdirSync(path9.dirname(file), { recursive: true });
-    fs8.writeFileSync(file, content);
+    if (fs7.existsSync(file)) throw new EditError(`Canvas "${name}" already exists.`);
+    fs7.mkdirSync(path8.dirname(file), { recursive: true });
+    fs7.writeFileSync(file, content);
     this.sources.set(name, content);
     this.canvasesChanged();
     this.record(name, `Created canvas ${name}`, actor, "", content, []);
@@ -2229,10 +2354,10 @@ var Workspace = class {
   }
   renameCanvas(from, to) {
     const src = this.file(from);
-    if (!fs8.existsSync(src)) throw new EditError(`Canvas "${from}" does not exist.`);
+    if (!fs7.existsSync(src)) throw new EditError(`Canvas "${from}" does not exist.`);
     const dest = canvasPath(this.config, to);
-    if (fs8.existsSync(dest)) throw new EditError(`A canvas named "${to}" already exists.`);
-    fs8.renameSync(src, dest);
+    if (fs7.existsSync(dest)) throw new EditError(`A canvas named "${to}" already exists.`);
+    fs7.renameSync(src, dest);
     this.comments.renameCanvas(from, to);
     for (const map of [this.sources, this.undoStacks, this.redoStacks]) {
       if (map.has(from)) {
@@ -2249,7 +2374,7 @@ var Workspace = class {
   duplicateCanvas(name) {
     const source = this.read(name);
     const copy = this.uniqueCanvasName(`${name}-copy`);
-    fs8.writeFileSync(canvasPath(this.config, copy), source);
+    fs7.writeFileSync(canvasPath(this.config, copy), source);
     this.sources.set(copy, source);
     this.canvasesChanged();
     return copy;
@@ -2258,17 +2383,19 @@ var Workspace = class {
   trash = /* @__PURE__ */ new Map();
   deleteCanvas(name) {
     const file = this.file(name);
-    if (!fs8.existsSync(file)) throw new EditError(`Canvas "${name}" does not exist.`);
-    this.trash.set(name, fs8.readFileSync(file, "utf8"));
-    fs8.unlinkSync(file);
+    if (!fs7.existsSync(file)) throw new EditError(`Canvas "${name}" does not exist.`);
+    this.trash.set(name, fs7.readFileSync(file, "utf8"));
+    fs7.unlinkSync(file);
     this.sources.delete(name);
+    this.undoStacks.delete(name);
+    this.redoStacks.delete(name);
     this.canvasesChanged();
   }
   restoreCanvas(name) {
     const source = this.trash.get(name);
     if (source === void 0) throw new EditError(`Nothing to restore for "${name}".`);
     const target = this.uniqueCanvasName(name);
-    fs8.writeFileSync(canvasPath(this.config, target), source);
+    fs7.writeFileSync(canvasPath(this.config, target), source);
     this.sources.set(target, source);
     this.trash.delete(name);
     this.canvasesChanged();
@@ -2279,14 +2406,14 @@ var Workspace = class {
     if (!fileName.endsWith(CANVAS_SUFFIX)) return;
     const canvas = canvasNameOf(fileName);
     const file = this.file(canvas);
-    if (!fs8.existsSync(file)) {
+    if (!fs7.existsSync(file)) {
       this.sources.delete(canvas);
       syncRoute(this.config);
       this.emit({ type: "canvases", canvases: this.canvases() });
       return;
     }
     const prev = this.sources.get(canvas);
-    const next = fs8.readFileSync(file, "utf8");
+    const next = fs7.readFileSync(file, "utf8");
     if (prev === next) return;
     this.sources.set(canvas, next);
     if (prev === void 0) {
@@ -2305,7 +2432,8 @@ var Workspace = class {
       } catch (err) {
         if (!(err instanceof ConflictError)) throw err;
         if (err.file) this.linkedFileChanged(err.file);
-        else this.externalChange(path9.basename(this.file(cmd.canvas)));
+        else this.externalChange(path8.basename(this.file(cmd.canvas)));
+        if (nodeRefs(cmd).length || "frame" in cmd && cmd.frame) throw new EditError(`${path8.basename(err.file ?? this.relFile(cmd.canvas))} changed while editing. Re-read the canvas and try again.`);
         return this.exec(cmd, actor);
       }
     });
@@ -2314,32 +2442,55 @@ var Workspace = class {
   }
   async exec(cmd, actor) {
     cmd = { ...cmd };
-    if (cmd.op === "add_component_frame" && !fs8.existsSync(this.file(cmd.canvas))) this.createCanvas(cmd.canvas, actor, COMPONENTS_CANVAS);
+    let prepared = null;
+    if (cmd.op === "add_component_frame" && !fs7.existsSync(this.file(cmd.canvas))) {
+      await this.catalog.load();
+      const spec = this.catalog.get(cmd.component);
+      if (!spec) throw new EditError(`Unknown component "${cmd.component}". Use list_components.`);
+      if (spec.library) throw new EditError(`${spec.name} comes from ${spec.library}: it can't be edited here.`);
+      this.createCanvas(cmd.canvas, actor, COMPONENTS_CANVAS);
+    }
     const canvasSource = this.read(cmd.canvas);
     const canvasDoc = parseCanvas(cmd.canvas, this.relFile(cmd.canvas), canvasSource);
     if (canvasDoc.error) throw new EditError(`The canvas file does not parse: ${canvasDoc.error}`);
     const view = resolveLinks(this.config, canvasDoc);
     cmd = this.routeLinked(cmd, view);
     let target = this.targetOf(cmd);
+    if (target) assertShown(view, target);
     if (cmd.op === "explore_copy") {
       const frame = findFrame(canvasDoc, cmd.frame);
       if (!frame) throw new EditError(`Frame "${cmd.frame}" not found.`);
       const body = explorationBody(this.config, frame, this.relFile(cmd.canvas));
-      this.pending = { kind: "explore", frame, imports: body.imports, jsx: await this.formatSnippet(body.jsx) };
+      prepared = { kind: "explore", frame, imports: body.imports, jsx: await this.formatSnippet(body.jsx) };
     }
     if (cmd.op === "apply_to_page") {
       const frame = findFrame(canvasDoc, cmd.frame);
       if (!frame) throw new EditError(`Frame "${cmd.frame}" not found.`);
       const plan = applyPlan(this.config, canvasSource, canvasDoc, frame, this.relFile(cmd.canvas));
       target = plan.page;
-      this.pending = { kind: "apply", frame, ...plan };
+      prepared = { kind: "apply", frame, ...plan };
     }
     const rel = target ?? this.relFile(cmd.canvas);
-    const file = path9.join(this.config.root, rel);
-    const before = target ? fs8.readFileSync(file, "utf8") : canvasSource;
-    const parse2 = (src) => target ? parseTargetDoc(target, src) : parseCanvas(cmd.canvas, rel, src);
-    const doc = parse2(before);
+    const file = path8.join(this.config.root, rel);
+    const original = target ? fs7.readFileSync(file, "utf8") : canvasSource;
+    const crlf = original.includes("\r\n");
+    const before = crlf ? original.replace(/\r\n/g, "\n") : original;
+    const parse = (src) => target ? parseTargetDoc(target, src) : parseCanvas(cmd.canvas, rel, src);
+    const doc = parse(before);
     if (!doc) throw new EditError(`${rel} has data or logic in its component now, so it can't be edited from the canvas. Explore a copy instead.`);
+    if (cmd.op === "insert_icon") {
+      const icon = cmd;
+      const lib = iconLibrary(icon.library);
+      if (!lib) throw new EditError(`Unknown icon library "${icon.library}". Known: ${ICON_LIBRARIES.map((l) => l.id).join(", ")}.`);
+      const icons = await loadIcons(this.config.root, lib.id);
+      const wanted = icon.name.toLowerCase();
+      const exact = icons.find((i) => i.name === icon.name) ?? icons.find((i) => i.name.toLowerCase() === wanted);
+      if (!exact) {
+        const near = searchIcons(icons, icon.name, 5).icons.map((i) => i.name);
+        throw new EditError(`No icon "${icon.name}" in ${lib.label}.${near.length ? ` Did you mean ${near.join(", ")}?` : " Use search_icons."}`);
+      }
+      cmd = { ...icon, library: lib.id, name: exact.name };
+    }
     if ((cmd.op === "insert_jsx" || cmd.op === "replace" || cmd.op === "create_frame") && cmd.jsx) {
       cmd = { ...cmd, jsx: await this.formatSnippet(cmd.jsx) };
     }
@@ -2349,16 +2500,16 @@ var Workspace = class {
       if (!r) throw new EditError(`No page "${cmd.route}". Pages: ${routes.map((x) => x.route).join(", ") || "none"}`);
       if (cmd.copy) {
         const built = routeFrame(this.config, r.file, this.relFile(cmd.canvas));
-        this.pending = { kind: "route", route: r.route, page: null, imports: built.imports, mode: built.mode, jsx: await this.formatSnippet(built.jsx) };
+        prepared = { kind: "route", route: r.route, page: null, imports: built.imports, mode: built.mode, jsx: await this.formatSnippet(built.jsx) };
       } else {
         const built = linkedFrameBody(this.config, canvasDoc, this.relFile(cmd.canvas), r.file);
-        this.pending = { kind: "route", route: r.route, page: r.file, imports: built.imports, mode: "linked", jsx: built.jsx };
+        prepared = { kind: "route", route: r.route, page: r.file, imports: built.imports, mode: "linked", jsx: built.jsx };
       }
     }
     if (cmd.op === "add_animation") {
       const files = ensureMotionComponents(this.config);
       if (files.created) this.catalog.invalidate();
-      this.motion = files;
+      prepared = { kind: "motion", files };
     }
     let newComponent = null;
     let movedNames = /* @__PURE__ */ new Set();
@@ -2379,15 +2530,15 @@ var Workspace = class {
         imports = importsFor(this.config, jsx, before, doc, rel, fileRel);
         movedNames = new Set(componentNamesIn(jsx));
       }
-      const abs = path9.join(this.config.root, fileRel);
+      const abs = path8.join(this.config.root, fileRel);
       newComponent = { rel: fileRel, content: await this.format(componentFile(name, jsx, imports), abs).catch(() => componentFile(name, jsx, imports)) };
-      this.pending = { kind: "component", name, file: fileRel };
+      prepared = { kind: "component", name, file: fileRel };
     }
     await this.catalog.load().catch(() => []);
     const ed = new CanvasEditor(before, doc);
     const renamedFrame = cmd.op === "update_frame" && cmd.name !== void 0 ? findFrame(doc, cmd.frame) : null;
     const usedBefore = cmd.op === "apply_to_page" ? new Set(componentNamesIn(before.slice(doc.frames[0].children[0].start, doc.frames[0].children[0].end))) : null;
-    const label = this.apply(ed, cmd, rel);
+    const label = this.apply(ed, cmd, rel, prepared);
     const pretty = await this.isPrettierClean(before, file);
     const finish = async (code) => pretty ? this.format(code, file) : validate(code);
     let result = ed.result();
@@ -2397,8 +2548,8 @@ var Workspace = class {
     let after = await finish(result);
     let ids = [];
     const reparse = (src) => {
-      const d = parse2(src);
-      if (!d) throw new EditError(`That edit would put logic into ${path9.basename(rel)}. Only plain JSX can be edited from the canvas.`);
+      const d = parse(src);
+      if (!d) throw new EditError(`That edit would put logic into ${path8.basename(rel)}. Only plain JSX can be edited from the canvas.`);
       return d;
     };
     if (after.includes(MARK)) {
@@ -2421,19 +2572,25 @@ var Workspace = class {
       ids = paths.map((p) => pathId(clean, p)).filter(Boolean);
     }
     if (cmd.op === "apply_to_page") ids = [findFrame(canvasDoc, cmd.frame).id];
-    if (after === before) return { doc: target ? this.doc(cmd.canvas) : view, ids, label };
-    if (fs8.readFileSync(file, "utf8") !== before) throw new ConflictError(`${path9.basename(rel)} changed during the edit.`, target ?? void 0);
-    if (newComponent) {
-      fs8.mkdirSync(path9.dirname(path9.join(this.config.root, newComponent.rel)), { recursive: true });
-      fs8.writeFileSync(path9.join(this.config.root, newComponent.rel), newComponent.content, { flag: "wx" });
+    const writeNewComponent = () => {
+      if (!newComponent) return;
+      fs7.mkdirSync(path8.dirname(path8.join(this.config.root, newComponent.rel)), { recursive: true });
+      fs7.writeFileSync(path8.join(this.config.root, newComponent.rel), newComponent.content, { flag: "wx" });
       this.catalog.invalidate();
       this.emit({ type: "catalog" });
+    };
+    if (crlf) after = after.replace(/\n/g, "\r\n");
+    if (after === original) {
+      writeNewComponent();
+      return { doc: target ? this.doc(cmd.canvas) : view, ids, label };
     }
+    if (fs7.readFileSync(file, "utf8") !== original) throw new ConflictError(`${path8.basename(rel)} changed during the edit.`, target ?? void 0);
+    writeNewComponent();
     if (target) this.sources.set(`file:${target}`, after);
     else this.sources.set(cmd.canvas, after);
-    fs8.writeFileSync(file, after);
+    fs7.writeFileSync(file, after);
     const newDoc = this.doc(cmd.canvas);
-    this.record(cmd.canvas, label, actor, before, after, ids, target ?? void 0, touchedFrames(cmd, ids, view, newDoc));
+    this.record(cmd.canvas, label, actor, original, after, ids, target ?? void 0, touchedFrames(cmd, ids, view, newDoc));
     if (renamedFrame) {
       const now = newDoc.frames[renamedFrame.path[0]];
       if (now && now.frameName !== renamedFrame.frameName) {
@@ -2457,7 +2614,7 @@ var Workspace = class {
       const f = findFrame(view, cmd.parent);
       if (f?.link) {
         if (!f.link.editable) throw viewOnly(f);
-        const src = fs8.readFileSync(path9.join(this.config.root, f.link.page), "utf8");
+        const src = fs7.readFileSync(path8.join(this.config.root, f.link.page), "utf8");
         if (f.link.kind === "component") {
           const own = parseModuleDoc(f.link.page, src)?.frames.find((x) => x.frameName === f.link.route);
           if (!own) throw viewOnly(f);
@@ -2482,21 +2639,60 @@ var Workspace = class {
     const refs = nodeRefs(cmd);
     const files = new Set(refs.map(fileOfId));
     if (files.size > 1) {
-      const names = [...files].map((f) => f ? path9.basename(f) : "the canvas");
+      const names = [...files].map((f) => f ? path8.basename(f) : "the canvas");
       throw new EditError(`These layers live in different files (${names.join(", ")}). Edit them one file at a time.`);
     }
     return [...files][0] ?? null;
   }
-  apply(ed, cmd, rel) {
+  /** Applies a command to the file being edited and returns its history label. */
+  apply(ed, cmd, rel, prepared) {
+    switch (cmd.op) {
+      case "set_props":
+      case "set_text":
+      case "set_class":
+      case "insert_jsx":
+      case "insert_component":
+      case "insert_icon":
+      case "replace":
+      case "duplicate":
+      case "delete":
+      case "move":
+      case "reorder":
+      case "wrap":
+        return this.applyLayerEdit(ed, cmd, rel, prepared);
+      case "create_frame":
+      case "update_frame":
+      case "add_background":
+      case "apply_preset":
+      case "create_variants":
+      case "add_component_frame":
+        return this.applyFrameEdit(ed, cmd, rel, prepared);
+      case "import_route":
+      case "explore_copy":
+      case "apply_to_page":
+        return this.applyPageEdit(ed, cmd, rel, prepared);
+      case "add_animation":
+      case "remove_animation":
+        return this.applyMotionEdit(ed, cmd, rel, prepared);
+      case "create_component":
+        return this.applyComponentEdit(ed, cmd, rel, prepared);
+      default: {
+        const unknown = cmd;
+        throw new EditError(`Unknown command ${unknown.op}.`);
+      }
+    }
+  }
+  /** Edits to layers: props, text, classes, inserting, moving, wrapping. */
+  applyLayerEdit(ed, cmd, rel, prepared) {
     const doc = ed.doc;
     const guard = (node, verb) => {
       if (doc.canvasNode) return;
-      if (node.path.length <= 2) throw new EditError(`Can't ${verb} the root element of ${path9.basename(rel)}.`);
-      if (node.kind === "expression" && node.name.trim() === "children" && /^layout\.[jt]sx?$/.test(path9.basename(rel))) throw new EditError(`Can't ${verb} the {children} slot of ${path9.basename(rel)}: that's where the page renders.`);
+      if (node.path.length <= 2) throw new EditError(`Can't ${verb} the root element of ${path8.basename(rel)}.`);
+      if (node.kind === "expression" && node.name.trim() === "children" && /^layout\.[jt]sx?$/.test(path8.basename(rel))) throw new EditError(`Can't ${verb} the {children} slot of ${path8.basename(rel)}: that's where the page renders.`);
     };
     const literalOnly = (node, key) => {
       const v = node.props[key];
-      if (!doc.canvasNode && v?.kind === "expression") throw new EditError(`${key} on ${node.name} is computed in code ({${short(v.code, 50)}}). Edit it in ${path9.basename(rel)}, or ask your agent.`);
+      if (!doc.canvasNode && v?.kind === "expression") throw new EditError(`${key} on ${node.name} is computed in code ({${short(v.code, 50)}}). Edit it in ${path8.basename(rel)}, or ask your agent.`);
     };
     switch (cmd.op) {
       case "set_props": {
@@ -2545,6 +2741,14 @@ var Workspace = class {
         ed.insertChild(parent, cmd.index, jsx);
         return `Inserted ${spec.name}`;
       }
+      case "insert_icon": {
+        const parent = ed.container(cmd.parent);
+        const lib = iconLibrary(cmd.library);
+        const local = ed.importAs(cmd.name, lib.from, `${cmd.name.replace(/Icon$/, "")}Icon`);
+        const className = cmd.className?.trim() ?? "size-4";
+        ed.insertChild(parent, cmd.index, `<${local}${className ? ` className=${JSON.stringify(className)}` : ""} />`);
+        return `Inserted ${cmd.name} icon`;
+      }
       case "replace": {
         const { node } = ed.node(cmd.id);
         parseJsx(cmd.jsx);
@@ -2553,7 +2757,8 @@ var Workspace = class {
         return `Replaced ${node.name}`;
       }
       case "duplicate": {
-        const nodes = cmd.ids.map((id) => ed.node(id));
+        const all = cmd.ids.map((id) => ed.node(id));
+        const nodes = all.filter(({ node: n }) => !all.some(({ node: o }) => o !== n && n.start >= o.start && n.end <= o.end));
         for (const { node } of nodes) guard(node, "duplicate");
         for (const { node } of nodes) ed.duplicate(node);
         return nodes.length === 1 ? `Duplicated ${nodes[0].node.kind === "component" && "frameName" in nodes[0].node ? "frame" : nodes[0].node.name}` : `Duplicated ${nodes.length} layers`;
@@ -2590,11 +2795,19 @@ var Workspace = class {
         ed.wrap(nodes, `<div className="${cls}">`, "</div>");
         return nodes.length === 1 ? `Wrapped ${nodes[0].name} in auto layout` : `Wrapped ${nodes.length} layers in auto layout`;
       }
+      default:
+        throw new Error(`Internal: ${cmd.op} isn't handled by applyLayerEdit.`);
+    }
+  }
+  /** Frames: creating, updating, backgrounds, presets, variant grids, main component frames. */
+  applyFrameEdit(ed, cmd, rel, prepared) {
+    const doc = ed.doc;
+    switch (cmd.op) {
       case "create_frame": {
         const device = findDevice(cmd.device);
         if (cmd.device && !device) throw new EditError(`Unknown device "${cmd.device}". Devices: ${DEVICES.map((d) => d.id).join(", ")}`);
         const name = uniqueFrameName(doc, cmd.name ?? device?.name ?? "Frame");
-        const right = doc.frames.reduce((m, f) => Math.max(m, f.x + f.width), -80);
+        const right = rightEdge(doc);
         const top = doc.frames.length ? Math.min(...doc.frames.map((f) => f.y)) : 0;
         if (cmd.jsx) {
           parseJsx(cmd.jsx);
@@ -2684,19 +2897,68 @@ var Workspace = class {
         ed.selectPaths.push(node.path);
         return `Applied ${preset.name} preset to ${spec.name}`;
       }
+      case "create_variants": {
+        const spec = this.catalog.get(cmd.component);
+        if (!spec) throw new EditError(`Unknown component "${cmd.component}".`);
+        const prop = spec.props.find((p) => p.name === cmd.prop);
+        if (!prop) throw new EditError(`${spec.name} has no prop "${cmd.prop}".`);
+        const values = prop.type === "enum" ? prop.options : prop.type === "boolean" ? [false, true] : [];
+        if (!values.length) throw new EditError(`Prop "${cmd.prop}" is ${prop.typeText}; variants need a union of string literals or a boolean.`);
+        ed.ensureImport(spec.name, importSpecifier(this.config.root, rel, spec.file));
+        const label = (v) => typeof v === "string" ? v[0].toUpperCase() + v.slice(1) : `${prop.name}: ${v}`;
+        const rows = indentBlock(values.map((v) => componentJsx(spec, { ...cmd.props, [prop.name]: v }, spec.acceptsChildren ? label(v) : void 0)).join("\n"));
+        const right = rightEdge(doc);
+        const name = uniqueFrameName(doc, `${spec.name} \xB7 ${prop.name}`);
+        ed.insertFrame(frameCode({ name, x: cmd.x ?? right + 80, y: cmd.y ?? 0, width: 360, body: `<div className="flex flex-col gap-3 p-4">
+${rows}
+</div>` }));
+        return `Created ${spec.name} ${prop.name} variants`;
+      }
+      case "add_component_frame": {
+        const spec = this.catalog.get(cmd.component);
+        if (!spec) throw new EditError(`Unknown component "${cmd.component}". Use list_components.`);
+        if (spec.library) throw new EditError(`${spec.name} comes from ${spec.library}: it can't be edited here.`);
+        const existing = doc.frames.find((f) => f.component === `${spec.file}#${spec.name}`);
+        if (existing) {
+          ed.selectPaths.push(existing.path);
+          return `Opened ${spec.name}`;
+        }
+        ed.ensureImport(spec.name, importSpecifier(this.config.root, rel, spec.file));
+        const right = rightEdge(doc);
+        const top = doc.frames.length ? Math.min(...doc.frames.map((f) => f.y)) : 0;
+        ed.insertFrame(
+          frameCode({
+            name: uniqueFrameName(doc, spec.name),
+            x: cmd.x ?? right + 80,
+            y: cmd.y ?? top,
+            width: cmd.width ?? 640,
+            component: `${spec.file}#${spec.name}`,
+            body: `<div className="p-10">
+  ${componentJsx(spec)}
+</div>`
+          })
+        );
+        return `Opened main component ${spec.name}`;
+      }
+      default:
+        throw new Error(`Internal: ${cmd.op} isn't handled by applyFrameEdit.`);
+    }
+  }
+  /** Linked pages: adding a page, exploring a copy, applying it back. */
+  applyPageEdit(ed, cmd, rel, prepared) {
+    const doc = ed.doc;
+    switch (cmd.op) {
       case "import_route": {
-        const built = this.pending;
-        this.pending = null;
+        const built = take(prepared, "route");
         for (const stmt of built.imports) ed.addImportStatement(stmt);
-        const right = doc.frames.reduce((m, f) => Math.max(m, f.x + f.width), -80);
+        const right = rightEdge(doc);
         const top = doc.frames.length ? Math.min(...doc.frames.map((f) => f.y)) : 0;
         const name = uniqueFrameName(doc, cmd.name ?? (built.route === "/" ? "Home" : built.route.split("/").filter(Boolean).map((p) => p.replace(/^./, (c) => c.toUpperCase())).join(" / ")));
         ed.insertFrame(frameCode({ name, x: cmd.x ?? right + 80, y: cmd.y ?? top, width: cmd.width ?? 1440, height: null, page: built.page ?? void 0, body: built.jsx }));
         return built.mode === "linked" ? `Linked ${built.route}` : built.mode === "inline" ? `Copied ${built.route} as layers` : `Copied ${built.route}`;
       }
       case "explore_copy": {
-        const built = this.pending;
-        this.pending = null;
+        const built = take(prepared, "explore");
         const f = built.frame;
         for (const stmt of built.imports) ed.addImportStatement(stmt);
         const h = (fr) => fr.height ?? 2e3;
@@ -2707,17 +2969,23 @@ var Workspace = class {
         return `Explored a copy of ${f.frameName}`;
       }
       case "apply_to_page": {
-        const plan = this.pending;
-        this.pending = null;
+        const plan = take(prepared, "apply");
         for (const stmt of plan.imports) ed.addImportStatement(stmt);
         ed.replace(doc.frames[0].children[0], plan.jsx);
         return `Applied ${plan.frame.frameName} to ${plan.page}`;
       }
+      default:
+        throw new Error(`Internal: ${cmd.op} isn't handled by applyPageEdit.`);
+    }
+  }
+  /** Scroll reveals and text animations. */
+  applyMotionEdit(ed, cmd, rel, prepared) {
+    switch (cmd.op) {
       case "add_animation": {
         const { node, parent } = ed.node(cmd.id);
         if ("frameName" in node) throw new EditError("Animate a layer inside the frame, not the frame itself.");
         if (node.kind === "expression") throw new EditError("Expressions can't be animated; pick the element around it.");
-        const files = this.motion ?? motionFiles(this.config);
+        const files = prepared?.kind === "motion" ? prepared.files : motionFiles(this.config);
         const props = {};
         if (cmd.effect !== void 0) props.effect = cmd.effect;
         for (const k of ["delay", "duration", "stagger"]) if (cmd[k] !== void 0 && !(cmd.kind === "reveal" && k === "stagger")) props[k] = Math.round(cmd[k] * 100) / 100;
@@ -2765,10 +3033,16 @@ var Workspace = class {
         ed.selectPaths.push(wrapper === kids[0] ? node.path : wrapper.path);
         return cmd.kind === "reveal" ? "Removed the reveal" : "Removed the text animation";
       }
+      default:
+        throw new Error(`Internal: ${cmd.op} isn't handled by applyMotionEdit.`);
+    }
+  }
+  /** New components, from scratch or from selected layers. */
+  applyComponentEdit(ed, cmd, rel, prepared) {
+    switch (cmd.op) {
       case "create_component": {
-        const made = this.pending;
-        this.pending = null;
-        ed.ensureImport(made.name, importSpecifier(this.config.root, rel, made.file));
+        const made = take(prepared, "component");
+        if (cmd.from || cmd.parent) ed.ensureImport(made.name, importSpecifier(this.config.root, rel, made.file));
         if (cmd.from) {
           const { node } = ed.node(cmd.from);
           ed.replace(node, `<${made.name} />`);
@@ -2778,49 +3052,8 @@ var Workspace = class {
         ed.insertChild(ed.container(cmd.parent), cmd.index, `<${made.name} />`);
         return `Created component ${made.name}`;
       }
-      case "add_component_frame": {
-        const spec = this.catalog.get(cmd.component);
-        if (!spec) throw new EditError(`Unknown component "${cmd.component}". Use list_components.`);
-        if (spec.library) throw new EditError(`${spec.name} comes from ${spec.library}: it can't be edited here.`);
-        const existing = doc.frames.find((f) => f.component === `${spec.file}#${spec.name}`);
-        if (existing) {
-          ed.selectPaths.push(existing.path);
-          return `Opened ${spec.name}`;
-        }
-        ed.ensureImport(spec.name, importSpecifier(this.config.root, rel, spec.file));
-        const right = doc.frames.reduce((m, f) => Math.max(m, f.x + f.width), -80);
-        const top = doc.frames.length ? Math.min(...doc.frames.map((f) => f.y)) : 0;
-        ed.insertFrame(
-          frameCode({
-            name: uniqueFrameName(doc, spec.name),
-            x: cmd.x ?? right + 80,
-            y: cmd.y ?? top,
-            width: cmd.width ?? 640,
-            component: `${spec.file}#${spec.name}`,
-            body: `<div className="p-10">
-  ${componentJsx(spec)}
-</div>`
-          })
-        );
-        return `Opened main component ${spec.name}`;
-      }
-      case "create_variants": {
-        const spec = this.catalog.get(cmd.component);
-        if (!spec) throw new EditError(`Unknown component "${cmd.component}".`);
-        const prop = spec.props.find((p) => p.name === cmd.prop);
-        if (!prop) throw new EditError(`${spec.name} has no prop "${cmd.prop}".`);
-        const values = prop.type === "enum" ? prop.options : prop.type === "boolean" ? [false, true] : [];
-        if (!values.length) throw new EditError(`Prop "${cmd.prop}" is ${prop.typeText}; variants need a union of string literals or a boolean.`);
-        ed.ensureImport(spec.name, importSpecifier(this.config.root, rel, spec.file));
-        const label = (v) => typeof v === "string" ? v[0].toUpperCase() + v.slice(1) : `${prop.name}: ${v}`;
-        const rows = indentBlock(values.map((v) => componentJsx(spec, { ...cmd.props, [prop.name]: v }, spec.acceptsChildren ? label(v) : void 0)).join("\n"));
-        const right = doc.frames.reduce((m, f) => Math.max(m, f.x + f.width), -80);
-        const name = uniqueFrameName(doc, `${spec.name} \xB7 ${prop.name}`);
-        ed.insertFrame(frameCode({ name, x: cmd.x ?? right + 80, y: cmd.y ?? 0, width: 360, body: `<div className="flex flex-col gap-3 p-4">
-${rows}
-</div>` }));
-        return `Created ${spec.name} ${prop.name} variants`;
-      }
+      default:
+        throw new Error(`Internal: ${cmd.op} isn't handled by applyComponentEdit.`);
     }
   }
   autoImport(ed, rel, jsx) {
@@ -2833,9 +3066,6 @@ ${rows}
       ed.ensureImport(name, importSpecifier(this.config.root, rel, spec.file));
     }
   }
-  motion = null;
-  /** work resolved (async) in exec before the synchronous apply */
-  pending = null;
   cleanCache = /* @__PURE__ */ new Map();
   async isPrettierClean(source, file) {
     const hit = this.cleanCache.get(source);
@@ -2880,11 +3110,29 @@ ${rows}
     if (stack.length > 200) stack.shift();
     this.undoStacks.set(canvas, stack);
     this.redoStacks.set(canvas, []);
-    this.feed.push(entry);
+    this.feed.push(publicEntry(entry));
     if (this.feed.length > 300) this.feed.shift();
+    this.trimHistory();
     this.emit({ type: "change", entry: publicEntry(entry), ids });
     this.emitHistory(canvas);
   }
+  /**
+   * Undo entries hold whole files (before and after). Keep their total under a
+   * budget by dropping the oldest entries across canvases, so long sessions on
+   * big pages don't grow without limit.
+   */
+  trimHistory(budget = 48 * 1024 * 1024) {
+    const all = [...this.undoStacks.values(), ...this.redoStacks.values()];
+    let total = 0;
+    for (const stack of all) for (const e of stack) total += e.before.length + e.after.length;
+    while (total > budget) {
+      let oldest = null;
+      for (const stack of all) if (stack.length && (!oldest || stack[0].at < oldest[0].at)) oldest = stack;
+      if (!oldest) break;
+      const e = oldest.shift();
+      total -= e.before.length + e.after.length;
+    }
+  }
   /** Changes still in effect (not undone) on a canvas since a time, oldest first. */
   changesSince(canvas, since) {
     return (this.undoStacks.get(canvas) ?? []).filter((e) => e.at > since).map(publicEntry);
@@ -2909,17 +3157,20 @@ ${rows}
       const entry = stack[stack.length - 1];
       if (!entry) throw new EditError(`Nothing to ${dir}.`);
       if (dir === "undo" && entry.before === "") throw new EditError("Cannot undo creating the canvas; delete the file instead.");
-      stack.pop();
-      const file = entry.file ? path9.join(this.config.root, entry.file) : this.file(canvas);
-      const current = entry.file ? fs8.readFileSync(file, "utf8") : this.read(canvas);
-      const expected = dir === "undo" ? entry.after : entry.before;
-      if (current !== expected) {
-        stack.push(entry);
-        throw new EditError(`Cannot ${dir} "${entry.label}": ${entry.file ? path9.basename(entry.file) : "the file"} changed since.`);
+      const file = entry.file ? path8.join(this.config.root, entry.file) : this.file(canvas);
+      const name = entry.file ? path8.basename(entry.file) : "the file";
+      let current;
+      try {
+        current = entry.file ? fs7.readFileSync(file, "utf8") : this.read(canvas);
+      } catch {
+        throw new EditError(`Cannot ${dir} "${entry.label}": ${name} can't be read right now.`);
       }
+      const expected = dir === "undo" ? entry.after : entry.before;
+      if (current !== expected) throw new EditError(`Cannot ${dir} "${entry.label}": ${name} changed since.`);
+      stack.pop();
       const next = dir === "undo" ? entry.before : entry.after;
       this.sources.set(entry.file ? `file:${entry.file}` : canvas, next);
-      fs8.writeFileSync(file, next);
+      fs7.writeFileSync(file, next);
       const list = to.get(canvas) ?? [];
       list.push(entry);
       to.set(canvas, list);
@@ -2929,9 +3180,10 @@ ${rows}
         for (const c of this.canvasesLinking(entry.file)) if (c !== canvas) this.emit({ type: "doc", canvas: c, doc: this.doc(c) });
       }
       const label = `${dir === "undo" ? "Undid" : "Redid"} \u201C${entry.label}\u201D`;
-      const marker = { ...entry, id: ++this.seq, label, actor, at: Date.now() };
+      const marker = publicEntry({ ...entry, id: ++this.seq, label, actor, at: Date.now() });
       this.feed.push(marker);
-      this.emit({ type: "change", entry: publicEntry(marker), ids: [] });
+      if (this.feed.length > 300) this.feed.shift();
+      this.emit({ type: "change", entry: marker, ids: [] });
       this.emitHistory(canvas);
       return { doc, label };
     });
@@ -2939,7 +3191,7 @@ ${rows}
     return job;
   }
   publicFeed() {
-    return this.feed.map(publicEntry);
+    return this.feed;
   }
   // ---------- agents ----------
   touchAgent(session, name) {
@@ -2959,17 +3211,17 @@ ${rows}
     if (this.agents.delete(session)) this.emit({ type: "agents", agents: [...this.agents.values()] });
   }
   ensureRoute() {
-    if (!fs8.existsSync(path9.join(this.config.root, this.config.canvasDir))) {
-      fs8.mkdirSync(path9.join(this.config.root, this.config.canvasDir), { recursive: true });
+    if (!fs7.existsSync(path8.join(this.config.root, this.config.canvasDir))) {
+      fs7.mkdirSync(path8.join(this.config.root, this.config.canvasDir), { recursive: true });
     }
     if (!this.canvases().length) {
       const file = canvasPath(this.config, "home");
       const content = this.homeCanvas();
-      fs8.writeFileSync(file, content);
+      fs7.writeFileSync(file, content);
       void this.format(content, file).then((pretty) => {
-        if (fs8.readFileSync(file, "utf8") !== content) return;
+        if (fs7.readFileSync(file, "utf8") !== content) return;
         this.sources.set("home", pretty);
-        fs8.writeFileSync(file, pretty);
+        fs7.writeFileSync(file, pretty);
       }).catch(() => {
       });
     }
@@ -2980,7 +3232,7 @@ ${rows}
     try {
       const home = listRoutes(this.config).find((r) => r.route === "/");
       if (!home) return STARTER_CANVAS;
-      const rel = path9.relative(this.config.root, canvasPath(this.config, "home"));
+      const rel = path8.relative(this.config.root, canvasPath(this.config, "home"));
       const empty = parseCanvas("home", rel, `import { Canvas, Frame } from "truecanvas";
 export default function C() { return <Canvas></Canvas>; }
 `);
@@ -3020,6 +3272,10 @@ export default function ComponentsCanvas() {
   return <Canvas></Canvas>;
 }
 `;
+function take(prepared, kind) {
+  if (prepared?.kind !== kind) throw new Error(`Internal: the ${kind} step wasn't prepared.`);
+  return prepared;
+}
 function validate(code) {
   try {
     parseModule(code);
@@ -3032,6 +3288,13 @@ function publicEntry(e) {
   const { before: _b, after: _a, ...rest } = e;
   return rest;
 }
+function assertShown(view, rel) {
+  const shown = view.frames.some((f) => f.link?.files.includes(rel));
+  if (!shown || path8.isAbsolute(rel) || rel.split(/[\\/]/).includes("..")) throw new EditError(`${rel} isn't shown on this canvas. Re-read the canvas for current ids.`);
+}
+function rightEdge(doc) {
+  return doc.frames.reduce((m, f) => Math.max(m, f.x + f.width), -80);
+}
 function nodeRefs(cmd) {
   const refs = [];
   if ("id" in cmd && cmd.id) refs.push(cmd.id);
@@ -3097,6 +3360,130 @@ function componentJsx(spec, props = {}, text) {
   return childText !== void 0 ? `${open}>${textCode(childText)}</${spec.name}>` : `${open} />`;
 }
 
+// src/core/pm.ts
+import { spawn } from "child_process";
+import fs8 from "fs";
+import path9 from "path";
+function detectPm(dir) {
+  for (let d = dir; ; d = path9.dirname(d)) {
+    if (fs8.existsSync(path9.join(d, "pnpm-lock.yaml")) || fs8.existsSync(path9.join(d, "pnpm-workspace.yaml"))) return "pnpm";
+    if (fs8.existsSync(path9.join(d, "yarn.lock"))) return "yarn";
+    if (fs8.existsSync(path9.join(d, "bun.lock")) || fs8.existsSync(path9.join(d, "bun.lockb"))) return "bun";
+    if (fs8.existsSync(path9.join(d, "package-lock.json"))) return "npm";
+    if (path9.dirname(d) === d || fs8.existsSync(path9.join(d, ".git"))) break;
+  }
+  const agent = process.env.npm_config_user_agent ?? "";
+  if (agent.startsWith("pnpm")) return "pnpm";
+  if (agent.startsWith("yarn")) return "yarn";
+  if (agent.startsWith("bun")) return "bun";
+  return "npm";
+}
+function addArgs(pm, specs, dev = false) {
+  if (pm === "npm") return ["install", ...dev ? ["-D"] : [], ...specs];
+  if (pm === "bun") return ["add", ...dev ? ["-d"] : [], ...specs];
+  return ["add", ...dev ? ["-D"] : [], ...specs];
+}
+function dlx(pm, pkg, args) {
+  if (pm === "pnpm") return ["pnpm", ["dlx", pkg, ...args]];
+  if (pm === "yarn") return ["yarn", ["dlx", pkg, ...args]];
+  if (pm === "bun") return ["bunx", [pkg, ...args]];
+  return ["npx", ["--yes", pkg, ...args]];
+}
+function toolEnv(extra = {}) {
+  return { ...process.env, PATH: `${path9.dirname(process.execPath)}${path9.delimiter}${process.env.PATH ?? ""}`, ...extra };
+}
+function shellSafe(cmd, args) {
+  if (process.platform !== "win32") return { cmd, args, shell: false };
+  const quote = (a) => /[\s"&|<>^()%!]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a;
+  return { cmd: quote(cmd), args: args.map(quote), shell: true };
+}
+function run2(cmd, args, cwd, timeoutMs = 3e5) {
+  return new Promise((resolve) => {
+    let out = "";
+    let done = false;
+    const finish = (ok, extra = "") => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve({ ok, out: (out + extra).slice(-2e4) });
+    };
+    const safe = shellSafe(cmd, args);
+    const p = spawn(safe.cmd, safe.args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: toolEnv({ CI: "1", FORCE_COLOR: "0", NO_COLOR: "1" }), shell: safe.shell });
+    const timer = setTimeout(() => {
+      p.kill();
+      finish(false, `
+${cmd} timed out after ${Math.round(timeoutMs / 1e3)}s`);
+    }, timeoutMs);
+    p.stdout.on("data", (d) => out += d);
+    p.stderr.on("data", (d) => out += d);
+    p.on("error", (err) => finish(false, `
+${err.message}`));
+    p.on("close", (code) => finish(code === 0));
+  });
+}
+
+// src/core/shadcn.ts
+import fs9 from "fs";
+import path10 from "path";
+function shadcnStatus(root) {
+  const file = path10.join(root, "components.json");
+  if (!fs9.existsSync(file)) return { initialized: false, uiDir: null, installed: [] };
+  let ui = "@/components/ui";
+  try {
+    ui = JSON.parse(fs9.readFileSync(file, "utf8"))?.aliases?.ui ?? ui;
+  } catch {
+  }
+  const dir = resolveAliasPath(root, ui);
+  let installed = [];
+  try {
+    installed = fs9.readdirSync(dir).filter((f) => /\.(tsx|jsx)$/.test(f)).map((f) => f.replace(/\.(tsx|jsx)$/, "")).sort();
+  } catch {
+    installed = [];
+  }
+  return { initialized: true, uiDir: posix(path10.relative(root, dir)), installed };
+}
+var FALLBACK = "accordion alert alert-dialog aspect-ratio avatar badge breadcrumb button button-group calendar card carousel chart checkbox collapsible combobox command context-menu dialog drawer dropdown-menu empty field form hover-card input input-group input-otp item kbd label menubar navigation-menu pagination popover progress radio-group resizable scroll-area select separator sheet sidebar skeleton slider sonner spinner switch table tabs textarea toggle toggle-group tooltip".split(" ");
+var registryCache = null;
+async function shadcnRegistry() {
+  if (registryCache && Date.now() - registryCache.at < 36e5) return { names: registryCache.names, offline: false };
+  try {
+    const res = await fetch("https://ui.shadcn.com/r/index.json", { signal: AbortSignal.timeout(8e3) });
+    if (!res.ok) throw new Error(String(res.status));
+    const items = await res.json();
+    const names = items.filter((i) => i.type === "registry:ui" && VALID.test(i.name)).map((i) => i.name).sort();
+    if (!names.length) throw new Error("empty registry");
+    registryCache = { at: Date.now(), names };
+    return { names, offline: false };
+  } catch {
+    return { names: FALLBACK, offline: true };
+  }
+}
+var VALID = /^[a-z0-9][a-z0-9-]*$/;
+async function shadcnInit(root) {
+  const [cmd, args] = dlx(detectPm(root), "shadcn@latest", ["init", "--defaults", "--yes", "--no-monorepo"]);
+  return run2(cmd, args, root);
+}
+async function shadcnAdd(root, names) {
+  const bad = names.filter((n) => !VALID.test(n));
+  if (bad.length) return { ok: false, out: `Not a component name: ${bad.join(", ")}`, added: [] };
+  const before = new Set(shadcnStatus(root).installed);
+  let log = "";
+  if (!shadcnStatus(root).initialized) {
+    const init = await shadcnInit(root);
+    log += init.out;
+    if (!init.ok) return { ok: false, out: log, added: [] };
+  }
+  const wanted = names.filter((n) => !before.has(n));
+  if (wanted.length) {
+    const [cmd, args] = dlx(detectPm(root), "shadcn@latest", ["add", ...wanted, "--yes"]);
+    const res = await run2(cmd, args, root);
+    log += res.out;
+    if (!res.ok) return { ok: false, out: log, added: [] };
+  }
+  const added = shadcnStatus(root).installed.filter((n) => !before.has(n));
+  return { ok: true, out: log, added };
+}
+
 // src/core/outline.ts
 function propText(name, v) {
   if (v.kind === "boolean") return v.value ? name : `${name}={false}`;
@@ -3185,8 +3572,8 @@ function describeComponent(c, verbose = false) {
 }
 
 // src/core/tokens.ts
-import fs9 from "fs";
-import path10 from "path";
+import fs10 from "fs";
+import path11 from "path";
 import { globSync } from "tinyglobby";
 var GROUPS = [
   ["--color-", "Colors", "bg-{name} text-{name} border-{name}"],
@@ -3203,9 +3590,9 @@ function readDesignTokens(root) {
   const sources = [];
   let darkVariant = null;
   for (const file of files) {
-    const css = fs9.readFileSync(file, "utf8");
+    const css = fs10.readFileSync(file, "utf8");
     if (!css.includes("@theme") && !css.includes("@custom-variant")) continue;
-    sources.push(path10.relative(root, file));
+    sources.push(posix(path11.relative(root, file)));
     const dv = /@custom-variant\s+dark\s*\(([^;]+)\);/.exec(css);
     if (dv) darkVariant = dv[1].trim();
     for (const block of css.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g)) {
@@ -3244,7 +3631,7 @@ function readTokenData(root) {
     for (const m of body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) into.set(m[1], m[2].trim());
   };
   for (const file of files) {
-    const css = fs9.readFileSync(file, "utf8");
+    const css = fs10.readFileSync(file, "utf8");
     for (const block of css.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g)) decls(block[1], theme);
     for (const block of css.matchAll(/(?:^|\n)\s*:root\s*\{([\s\S]*?)\n\}/g)) decls(block[1], lightVars);
     for (const block of css.matchAll(/(?:^|\n)\s*(?:\.dark|\[data-theme=["']?dark["']?\]|:root\.dark)\s*\{([\s\S]*?)\n\}/g)) decls(block[1], darkVars);
@@ -3276,30 +3663,30 @@ function readTokenData(root) {
 }
 
 // src/core/compare.ts
-import fs10 from "fs";
-import path11 from "path";
+import fs11 from "fs";
+import path12 from "path";
 var COMPARE_PREFIX = "__compare__";
 function writeCompare(config, canvas, source, files = {}, as = canvas) {
-  const routeDir = path11.join(config.root, config.appDir, "truecanvas");
-  const dir = path11.join(routeDir, "compare");
-  fs10.mkdirSync(dir, { recursive: true });
-  const canvasDir = path11.join(config.root, config.canvasDir);
-  const canvasRel = path11.join(config.canvasDir, `${canvas}.canvas.tsx`);
+  const routeDir = routeDirOf(config);
+  const dir = path12.join(routeDir, "compare");
+  fs11.mkdirSync(dir, { recursive: true });
+  const canvasDir = path12.join(config.root, config.canvasDir);
+  const canvasRel = `${config.canvasDir}/${canvas}.canvas.tsx`;
   const swapped = /* @__PURE__ */ new Map();
   for (const [rel, content] of Object.entries(files)) {
-    const ext = path11.extname(rel);
+    const ext = path12.extname(rel);
     const name = `${as}--${rel.slice(0, -ext.length).replace(/[^\w.-]+/g, "_")}${ext}`;
-    const original = path11.join(config.root, rel);
-    fs10.writeFileSync(path11.join(dir, name), rewriteImports(content, (spec) => spec.startsWith(".") ? relativeSpec(dir, path11.resolve(path11.dirname(original), spec)) : spec));
+    const original = path12.join(config.root, rel);
+    fs11.writeFileSync(path12.join(dir, name), rewriteImports(content, (spec) => spec.startsWith(".") ? relativeSpec(dir, path12.resolve(path12.dirname(original), spec)) : spec));
     swapped.set(importSpecifier(config.root, canvasRel, rel), `./${name.slice(0, -ext.length)}`);
   }
-  const out = rewriteImports(source, (spec) => swapped.get(spec) ?? (spec.startsWith(".") ? relativeSpec(dir, path11.resolve(canvasDir, spec)) : spec));
-  fs10.writeFileSync(path11.join(dir, `${as}.canvas.tsx`), out);
+  const out = rewriteImports(source, (spec) => swapped.get(spec) ?? (spec.startsWith(".") ? relativeSpec(dir, path12.resolve(canvasDir, spec)) : spec));
+  fs11.writeFileSync(path12.join(dir, `${as}.canvas.tsx`), out);
   syncRoute(config);
   return `${COMPARE_PREFIX}${as}`;
 }
 function relativeSpec(fromDir, target) {
-  const next = path11.relative(fromDir, target);
+  const next = posix(path12.relative(fromDir, target));
   return next.startsWith(".") ? next : `./${next}`;
 }
 function rewriteImports(source, map) {
@@ -3308,15 +3695,16 @@ function rewriteImports(source, map) {
   for (const imp of [...doc.imports].sort((a, b) => b.start - a.start)) {
     const next = map(imp.source);
     if (next === imp.source) continue;
-    const stmt = out.slice(imp.start, imp.end).replace(JSON.stringify(imp.source), JSON.stringify(next)).replace(`'${imp.source}'`, `'${next}'`);
+    const stmt = rewriteImportSource(out.slice(imp.start, imp.end), imp.source, next);
     out = out.slice(0, imp.start) + stmt + out.slice(imp.end);
   }
   return out;
 }
 function clearCompare(config, canvas) {
-  const dir = path11.join(config.root, config.appDir, "truecanvas", "compare");
-  if (!fs10.existsSync(dir)) return;
-  for (const f of fs10.readdirSync(dir)) if (!canvas || f === `${canvas}.canvas.tsx` || f.startsWith(`${canvas}--`)) fs10.rmSync(path11.join(dir, f));
+  if (canvas) assertCanvasName(canvas);
+  const dir = path12.join(routeDirOf(config), "compare");
+  if (!fs11.existsSync(dir)) return;
+  for (const f of fs11.readdirSync(dir)) if (!canvas || f === `${canvas}.canvas.tsx` || f.startsWith(`${canvas}--`)) fs11.rmSync(path12.join(dir, f));
   syncRoute(config);
 }
 function frameChanges(before, after) {
@@ -3332,11 +3720,189 @@ function frameChanges(before, after) {
   return out;
 }
 
+// src/core/init.ts
+import fs12 from "fs";
+import MagicString2 from "magic-string";
+import path13 from "path";
+var CONFIG_FILES = {
+  next: ["next.config.ts", "next.config.mjs", "next.config.js", "next.config.mts"],
+  vite: ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"]
+};
+function projectFramework(root) {
+  try {
+    const pkg = JSON.parse(fs12.readFileSync(path13.join(root, "package.json"), "utf8"));
+    return detectFramework({ ...pkg.dependencies, ...pkg.devDependencies });
+  } catch {
+    return "next";
+  }
+}
+function configStatus(root, framework = projectFramework(root)) {
+  const marker = framework === "vite" ? "truecanvas/vite" : "withTruecanvas";
+  for (const name of CONFIG_FILES[framework]) {
+    const file = path13.join(root, name);
+    if (fs12.existsSync(file)) return { file, wrapped: fs12.readFileSync(file, "utf8").includes(marker), framework };
+  }
+  return { file: null, wrapped: false, framework };
+}
+function initProject(config) {
+  const { root } = config;
+  const report = { done: [], todo: [] };
+  const vite = config.framework === "vite";
+  const status = configStatus(root, config.framework);
+  if (vite) {
+    const name = status.file ? path13.basename(status.file) : "vite.config.ts";
+    if (status.wrapped) report.done.push(`${name} already uses the truecanvas() plugin`);
+    else {
+      const src = status.file ? fs12.readFileSync(status.file, "utf8") : null;
+      const next = src && addVitePlugin(src);
+      if (next) {
+        fs12.writeFileSync(status.file, next);
+        report.done.push(`Added the truecanvas() plugin to ${name}`);
+      } else report.todo.push(`Add truecanvas() from "truecanvas/vite" to the plugins in ${name}`);
+    }
+  } else if (!status.file) {
+    const file = path13.join(root, "next.config.ts");
+    fs12.writeFileSync(file, `import type { NextConfig } from "next";
+import { withTruecanvas } from "truecanvas/next";
+
+const nextConfig: NextConfig = {};
+
+export default withTruecanvas(nextConfig);
+`);
+    report.done.push("Created next.config.ts with withTruecanvas()");
+  } else if (status.wrapped) {
+    report.done.push(`${path13.basename(status.file)} already uses withTruecanvas()`);
+  } else {
+    const src = fs12.readFileSync(status.file, "utf8");
+    const next = wrapConfigExport(src);
+    if (next && next !== src && next.includes("withTruecanvas(")) {
+      fs12.writeFileSync(status.file, next);
+      report.done.push(`Wrapped ${path13.basename(status.file)} with withTruecanvas()`);
+    } else {
+      report.todo.push(`Wrap your ${path13.basename(status.file)} export with withTruecanvas() from "truecanvas/next"`);
+    }
+  }
+  const pkgFile = path13.join(root, "package.json");
+  try {
+    const raw = fs12.readFileSync(pkgFile, "utf8");
+    const pkg = JSON.parse(raw);
+    pkg.scripts ??= {};
+    if (!Object.values(pkg.scripts).some((v) => typeof v === "string" && v.includes("truecanvas"))) {
+      pkg.scripts.canvas = "truecanvas dev";
+      const indent = /\n(\s+)"/.exec(raw)?.[1] ?? "  ";
+      fs12.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, indent)}
+`);
+      report.done.push(`Added the "canvas" script (npm run canvas)`);
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!("tailwindcss" in deps)) report.todo.push("Tailwind CSS isn't installed: layout and style controls write Tailwind classes");
+    if (!("next" in deps) && !("vite" in deps)) report.todo.push("Neither Next.js nor Vite is in package.json: Truecanvas needs a Next.js (App Router) or Vite + React app");
+  } catch {
+    report.todo.push("Couldn't read package.json");
+  }
+  const ignoreFile = path13.join(root, ".gitignore");
+  const entry = `/${config.routeDir}/`;
+  const ignore = fs12.existsSync(ignoreFile) ? fs12.readFileSync(ignoreFile, "utf8") : "";
+  if (!ignore.split("\n").some((l) => l.trim() === entry || l.trim() === entry.slice(1))) {
+    fs12.writeFileSync(ignoreFile, `${ignore}${ignore && !ignore.endsWith("\n") ? "\n" : ""}
+# Truecanvas (generated dev-only route)
+${entry}
+`);
+    report.done.push(`Ignored ${entry} in .gitignore`);
+  }
+  for (const name of ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"]) {
+    const file = path13.join(root, name);
+    if (!fs12.existsSync(file)) continue;
+    const src = fs12.readFileSync(file, "utf8");
+    const glob = `./${config.canvasDir}/**/*.{ts,tsx}`;
+    if (src.includes(config.canvasDir)) break;
+    const m = /content\s*:\s*\[([ \t]*\n?)([ \t]*)/.exec(src);
+    if (m) {
+      const indent = m[2] || "    ";
+      const at = m.index + m[0].length;
+      const entry2 = m[1].includes("\n") ? `${JSON.stringify(glob)},
+${indent}` : `${JSON.stringify(glob)}, `;
+      fs12.writeFileSync(file, src.slice(0, at) + entry2 + src.slice(at));
+      report.done.push(`Added ${config.canvasDir} to Tailwind's content in ${name}`);
+    } else report.todo.push(`Add "${glob}" to the content list in ${name} so Tailwind styles your canvases`);
+    break;
+  }
+  if (!vite && !fs12.existsSync(path13.join(root, config.appDir))) report.todo.push(`No ${config.appDir}/ folder found: Truecanvas needs the Next.js App Router`);
+  return report;
+}
+function addImport(src, line) {
+  const lines = src.split("\n");
+  let at = 0;
+  lines.forEach((l, i) => {
+    if (/^\s*import\s/.test(l) || /^\s*["']use (client|server)["']/.test(l)) at = i + 1;
+  });
+  while (at > 0 && at < lines.length && !/;\s*$|from\s+["'][^"']+["']\s*;?\s*$/.test(lines[at - 1])) at++;
+  lines.splice(at, 0, line);
+  return lines.join("\n");
+}
+function wrapConfigExport(src) {
+  let ast;
+  try {
+    ast = parseModule(src);
+  } catch {
+    return null;
+  }
+  const s = new MagicString2(src);
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ExportDefaultDeclaration") {
+      const d = stmt.declaration;
+      if (d.type === "FunctionDeclaration" && d.id) {
+        s.remove(stmt.start, d.start);
+        s.appendLeft(stmt.end, `
+
+export default withTruecanvas(${d.id.name});`);
+      } else if (d.type === "FunctionDeclaration" || d.type === "ArrowFunctionExpression" || d.type.endsWith("Expression") || d.type === "Identifier") {
+        s.appendLeft(d.start, "withTruecanvas(");
+        s.appendRight(d.end, ")");
+      } else return null;
+      return addImport(s.toString(), `import { withTruecanvas } from "truecanvas/next";`);
+    }
+    if (stmt.type === "ExpressionStatement" && stmt.expression.type === "AssignmentExpression") {
+      const { left, right } = stmt.expression;
+      const isModuleExports = left.type === "MemberExpression" && left.object.type === "Identifier" && left.object.name === "module" && left.property.type === "Identifier" && left.property.name === "exports";
+      if (!isModuleExports) continue;
+      s.appendLeft(right.start, "withTruecanvas(");
+      s.appendRight(right.end, ")");
+      return `const { withTruecanvas } = require("truecanvas/next");
+${s.toString()}`;
+    }
+  }
+  return null;
+}
+function addVitePlugin(src) {
+  let ast;
+  try {
+    ast = parseModule(src);
+  } catch {
+    return null;
+  }
+  let plugins = null;
+  walk(ast, (node) => {
+    if (plugins) return false;
+    if (node.type !== "ObjectProperty" || node.value.type !== "ArrayExpression") return;
+    const key = node.key.type === "Identifier" ? node.key.name : node.key.type === "StringLiteral" ? node.key.value : null;
+    if (key !== "plugins") return;
+    plugins = { start: node.value.start, end: node.value.end, elements: node.value.elements.filter((e) => e !== null).map((e) => ({ start: e.start, end: e.end })) };
+    return false;
+  });
+  if (!plugins) return null;
+  const { start, end, elements } = plugins;
+  const s = new MagicString2(src);
+  if (!elements.length) s.overwrite(start, end, "[truecanvas()]");
+  else {
+    const last = elements[elements.length - 1];
+    const before = src.slice(start + 1, elements[0].start);
+    s.appendLeft(last.end, before.includes("\n") ? `,${before.replace(/^[^\n]*/, "")}truecanvas()` : ", truecanvas()");
+  }
+  return addImport(s.toString(), `import { truecanvas } from "truecanvas/vite";`);
+}
+
 export {
-  loadConfig,
-  parseModule,
-  idOf,
-  walk,
   parseCanvas,
   allNodes,
   findNode,
@@ -3351,16 +3917,32 @@ export {
   componentsDir,
   DEVICES,
   findDevice,
+  assertCanvasName,
+  syncRoute,
+  viteStylesheets,
+  syncComponentRegistry,
   Comments,
   Git,
-  syncComponentRegistry,
   Workspace,
   componentJsx,
+  detectPm,
+  addArgs,
+  toolEnv,
+  shellSafe,
+  run2 as run,
+  shadcnStatus,
+  shadcnRegistry,
+  shadcnInit,
+  shadcnAdd,
   outlineDoc,
   describeComponent,
   readDesignTokens,
   readTokenData,
   writeCompare,
   clearCompare,
-  frameChanges
+  frameChanges,
+  configStatus,
+  initProject,
+  wrapConfigExport,
+  addVitePlugin
 };