foss-design 0.7.0 → 0.8.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import path28 from "path";
+import path30 from "path";
 import { parseArgs } from "util";
 
 // src/core/paths.ts
@@ -134,12 +134,12 @@ function resolveFrom(anchor, request) {
 
 // src/cli/commands/build.ts
 import { spawnSync } from "child_process";
-import fs12 from "fs";
-import path12 from "path";
+import fs13 from "fs";
+import path13 from "path";
 
 // src/build/static.ts
-import fs11 from "fs";
-import path11 from "path";
+import fs12 from "fs";
+import path12 from "path";
 import { build } from "vite";
 
 // src/core/png.ts
@@ -307,8 +307,8 @@ function ensureThumb(file) {
 }
 
 // src/core/project.ts
-import fs7 from "fs";
-import path7 from "path";
+import fs8 from "fs";
+import path8 from "path";
 
 // src/core/canvas.ts
 import { createHash } from "crypto";
@@ -346,8 +346,8 @@ function routeError(pattern) {
   }
   return null;
 }
-function split(path29) {
-  return path29.split("/").filter(Boolean);
+function split(path31) {
+  return path31.split("/").filter(Boolean);
 }
 function compileRoute(pattern) {
   return {
@@ -366,8 +366,8 @@ function decode2(part) {
     return part;
   }
 }
-function scoreRoute(route2, path29) {
-  const parts = split(path29.split(/[?#]/)[0] ?? "").map(decode2);
+function scoreRoute(route2, path31) {
+  const parts = split(path31.split(/[?#]/)[0] ?? "").map(decode2);
   const walk2 = (s, p) => {
     if (s === route2.segments.length) return p === parts.length ? 0 : null;
     const segment = route2.segments[s];
@@ -385,11 +385,11 @@ function scoreRoute(route2, path29) {
   };
   return walk2(0, 0);
 }
-function matchRoute(entries, path29) {
+function matchRoute(entries, path31) {
   let best = null;
   for (const entry of entries) {
     for (const route2 of entry.routes) {
-      const score = scoreRoute(route2, path29);
+      const score = scoreRoute(route2, path31);
       if (score !== null && (!best || score > best.score)) best = { score, value: entry.value };
     }
   }
@@ -426,6 +426,8 @@ var DesignConfigSchema = z.strictObject({
   alias: z.record(z.string(), z.string()).optional(),
   /** Extra folders Tailwind scans for class names, relative to the project root. */
   sources: z.array(z.string()).optional(),
+  /** A monorepo's app package, relative to the project root: screens import its dependencies and its React. */
+  app: z.string().min(1).optional(),
   /** A folder served at the root of every screen, like Vite's `public`, relative to the project root. */
   public: z.string().min(1).optional(),
   port: z.number().int().min(1).max(65535).optional()
@@ -512,9 +514,9 @@ var CanvasSchema = z.strictObject({
   pages: z.array(z.unknown()).min(1, "add at least one page")
 });
 var ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/i;
-function formatPath(base, path29) {
+function formatPath(base, path31) {
   let out = base;
-  for (const part of path29) out += typeof part === "number" ? `[${part}]` : out ? `.${String(part)}` : String(part);
+  for (const part of path31) out += typeof part === "number" ? `[${part}]` : out ? `.${String(part)}` : String(part);
   return out;
 }
 function describeZodError(error, base = "") {
@@ -831,33 +833,80 @@ function summarize(canvas) {
   };
 }
 
-// src/core/public.ts
+// src/core/icon.ts
 import fs4 from "fs";
 import path4 from "path";
+var ICON_EXTENSIONS = ["svg", "png", "webp"];
+var MAX_ICON_BYTES = 256 * 1024;
+var iconName = (ext) => `icon.${ext}`;
+function iconFile(paths) {
+  for (const ext of ICON_EXTENSIONS) {
+    const file = path4.join(paths.system, iconName(ext));
+    if (fs4.existsSync(file) && fs4.statSync(file).isFile()) return file;
+  }
+  return null;
+}
+function sniffIcon(data) {
+  if (data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+    return "png";
+  if (data.length >= 12 && data.toString("latin1", 0, 4) === "RIFF" && data.toString("latin1", 8, 12) === "WEBP")
+    return "webp";
+  const head = data.subarray(0, 4096).toString("utf8").replace(/^/, "");
+  const rest = head.replace(/^(?:\s|<\?xml[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/i, "");
+  return /^<svg[\s>]/i.test(rest) ? "svg" : null;
+}
+function iconProblem(data, ext) {
+  const kind = sniffIcon(data);
+  if (!kind) return "the icon must be an SVG, PNG or WebP image";
+  if (ext && ext !== kind) return `the file is ${kind.toUpperCase()}, not ${ext.toUpperCase()}`;
+  if (data.length > MAX_ICON_BYTES)
+    return `the icon is ${Math.ceil(data.length / 1024)} KB; the limit is ${MAX_ICON_BYTES / 1024} KB`;
+  return null;
+}
+function writeIcon(paths, data) {
+  for (const ext2 of ICON_EXTENSIONS) fs4.rmSync(path4.join(paths.system, iconName(ext2)), { force: true });
+  if (!data) return null;
+  const ext = sniffIcon(data);
+  fs4.mkdirSync(paths.system, { recursive: true });
+  const file = path4.join(paths.system, iconName(ext));
+  fs4.writeFileSync(file, data);
+  return file;
+}
+function onlyIcon(dir) {
+  try {
+    return fs4.readdirSync(dir).filter((name) => !name.startsWith(".")).every((name) => ICON_EXTENSIONS.some((ext) => name === iconName(ext)));
+  } catch {
+    return false;
+  }
+}
+
+// src/core/public.ts
+import fs5 from "fs";
+import path5 from "path";
 function publicFiles(dir) {
   const files = [];
   let root;
   try {
-    root = fs4.realpathSync(dir);
+    root = fs5.realpathSync(dir);
   } catch {
     return files;
   }
   const visit = (current) => {
     let entries;
     try {
-      entries = fs4.readdirSync(current, { withFileTypes: true });
+      entries = fs5.readdirSync(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-      const full = path4.join(current, entry.name);
+      const full = path5.join(current, entry.name);
       if (entry.isDirectory()) visit(full);
-      else if (entry.isFile()) files.push(toPosix(path4.relative(dir, full)));
+      else if (entry.isFile()) files.push(toPosix(path5.relative(dir, full)));
       else if (entry.isSymbolicLink()) {
         try {
-          const target = fs4.realpathSync(full);
-          if (isInside(root, target) && fs4.statSync(target).isFile()) files.push(toPosix(path4.relative(dir, full)));
+          const target = fs5.realpathSync(full);
+          if (isInside(root, target) && fs5.statSync(target).isFile()) files.push(toPosix(path5.relative(dir, full)));
         } catch {
         }
       }
@@ -868,12 +917,12 @@ function publicFiles(dir) {
 }
 
 // src/core/system.ts
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path7 from "path";
 
 // src/core/tokens.ts
-import fs5 from "fs";
-import path5 from "path";
+import fs6 from "fs";
+import path6 from "path";
 import postcss from "postcss";
 var NAMESPACES = [
   ["--color-", "color"],
@@ -1032,12 +1081,12 @@ function readStylesheets(entry) {
   const seen = /* @__PURE__ */ new Set();
   const files = [];
   const walk2 = (file) => {
-    if (seen.has(file) || !fs5.existsSync(file)) return;
+    if (seen.has(file) || !fs6.existsSync(file)) return;
     seen.add(file);
-    const css2 = fs5.readFileSync(file, "utf8");
+    const css2 = fs6.readFileSync(file, "utf8");
     const imports = [...css2.matchAll(/@import\s+(?:url\()?\s*["']([^"']+)["']/g)].map((m) => m[1]);
     for (const spec of imports) {
-      if (spec.startsWith("./") || spec.startsWith("../")) walk2(path5.resolve(path5.dirname(file), spec));
+      if (spec.startsWith("./") || spec.startsWith("../")) walk2(path6.resolve(path6.dirname(file), spec));
     }
     files.push({ file, css: css2 });
   };
@@ -1173,11 +1222,11 @@ var COMPONENT_EXT = [".tsx", ".jsx", ".ts", ".js", ".vue", ".svelte", ".html"];
 var IMAGE_EXT = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico"]);
 var FONT_EXT = /* @__PURE__ */ new Set([".woff", ".woff2", ".ttf", ".otf"]);
 function listFiles(dir, deep = false) {
-  if (!fs6.existsSync(dir)) return [];
+  if (!fs7.existsSync(dir)) return [];
   const out = [];
-  for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+  for (const entry of fs7.readdirSync(dir, { withFileTypes: true })) {
     if (entry.name.startsWith(".")) continue;
-    const full = path6.join(dir, entry.name);
+    const full = path7.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (deep) out.push(...listFiles(full, true));
     } else out.push(full);
@@ -1185,16 +1234,16 @@ function listFiles(dir, deep = false) {
   return out.sort();
 }
 function guessSources(componentsDir, stem) {
-  if (!fs6.existsSync(componentsDir)) return [];
+  if (!fs7.existsSync(componentsDir)) return [];
   const wanted = slugify(stem);
   for (const file of listFiles(componentsDir)) {
-    const ext = path6.extname(file);
-    if (COMPONENT_EXT.includes(ext) && slugify(path6.basename(file, ext)) === wanted) return [file];
+    const ext = path7.extname(file);
+    if (COMPONENT_EXT.includes(ext) && slugify(path7.basename(file, ext)) === wanted) return [file];
   }
-  for (const entry of fs6.readdirSync(componentsDir, { withFileTypes: true })) {
+  for (const entry of fs7.readdirSync(componentsDir, { withFileTypes: true })) {
     if (entry.isDirectory() && slugify(entry.name) === wanted) {
-      const files = listFiles(path6.join(componentsDir, entry.name)).filter(
-        (f) => COMPONENT_EXT.includes(path6.extname(f))
+      const files = listFiles(path7.join(componentsDir, entry.name)).filter(
+        (f) => COMPONENT_EXT.includes(path7.extname(f))
       );
       if (files.length) return files;
     }
@@ -1202,14 +1251,14 @@ function guessSources(componentsDir, stem) {
   return [];
 }
 function loadSystem(paths, urls) {
-  if (!fs6.existsSync(paths.system)) return null;
+  if (!fs7.existsSync(paths.system) || onlyIcon(paths.system)) return null;
   const issues = [];
-  const configFile = path6.join(paths.system, "system.json");
+  const configFile = path7.join(paths.system, "system.json");
   const report = (severity, file, message, at) => issues.push({ severity, file: relToRoot(paths, file), message, at });
   let config = null;
-  if (fs6.existsSync(configFile)) {
+  if (fs7.existsSync(configFile)) {
     try {
-      const parsed = SystemConfigSchema.safeParse(JSON.parse(fs6.readFileSync(configFile, "utf8")));
+      const parsed = SystemConfigSchema.safeParse(JSON.parse(fs7.readFileSync(configFile, "utf8")));
       if (parsed.success) config = parsed.data;
       else for (const issue of describeZodError(parsed.error)) report("error", configFile, issue.message, issue.at);
     } catch (error) {
@@ -1218,36 +1267,36 @@ function loadSystem(paths, urls) {
   } else {
     report("warning", configFile, 'system.json is missing; run `design system init` or add { "name": "\u2026" }');
   }
-  const tokensFile = path6.join(paths.system, "tokens.css");
+  const tokensFile = path7.join(paths.system, "tokens.css");
   let stylesheet = null;
   if (config?.stylesheet) {
-    stylesheet = path6.resolve(paths.system, config.stylesheet);
-    if (!fs6.existsSync(stylesheet)) {
+    stylesheet = path7.resolve(paths.system, config.stylesheet);
+    if (!fs7.existsSync(stylesheet)) {
       report("error", configFile, `stylesheet not found: ${config.stylesheet}`, "stylesheet");
       stylesheet = null;
     }
   }
-  const tokenEntry = stylesheet ?? (fs6.existsSync(tokensFile) ? tokensFile : null);
+  const tokenEntry = stylesheet ?? (fs7.existsSync(tokensFile) ? tokensFile : null);
   const tokens = tokenEntry ? parseTokens(readStylesheets(tokenEntry)) : [];
   if (!tokenEntry) report("warning", tokensFile, "no tokens.css: screens get the default Tailwind theme");
-  const specimensDir = path6.join(paths.system, "specimens");
-  const componentsDir = path6.join(paths.system, "components");
+  const specimensDir = path7.join(paths.system, "specimens");
+  const componentsDir = path7.join(paths.system, "components");
   const components = [];
   const specimens = [];
   const usedIds = /* @__PURE__ */ new Set();
   for (const file of listFiles(specimensDir)) {
-    const ext = path6.extname(file).toLowerCase();
+    const ext = path7.extname(file).toLowerCase();
     if (!SPECIMEN_EXT.has(ext)) continue;
-    const stem = path6.basename(file, ext);
+    const stem = path7.basename(file, ext);
     let id2 = slugify(stem);
     if (usedIds.has(id2)) id2 = `${id2}-${usedIds.size + 1}`;
     usedIds.add(id2);
-    const tags = parseDocTags(fs6.readFileSync(file, "utf8"));
-    const sources = (tags.source ?? []).flatMap((value) => value.split(/[\s,]+/)).filter(Boolean).map((value) => path6.resolve(path6.dirname(file), value));
+    const tags = parseDocTags(fs7.readFileSync(file, "utf8"));
+    const sources = (tags.source ?? []).flatMap((value) => value.split(/[\s,]+/)).filter(Boolean).map((value) => path7.resolve(path7.dirname(file), value));
     for (const source of sources) {
-      if (!fs6.existsSync(source)) report("warning", file, `@source not found: ${path6.relative(paths.system, source)}`);
+      if (!fs7.existsSync(source)) report("warning", file, `@source not found: ${path7.relative(paths.system, source)}`);
     }
-    const found = sources.filter((source) => fs6.existsSync(source));
+    const found = sources.filter((source) => fs7.existsSync(source));
     const title = tags.title?.[0] || titleize(stem);
     const format = ext === ".html" ? "html" : "module";
     components.push({
@@ -1273,10 +1322,10 @@ function loadSystem(paths, urls) {
     });
   }
   const guidelines = [];
-  for (const file of listFiles(path6.join(paths.system, "guidelines"))) {
-    if (path6.extname(file).toLowerCase() !== ".md") continue;
-    const stem = path6.basename(file, ".md");
-    const { data, body } = parseFrontmatter(fs6.readFileSync(file, "utf8"));
+  for (const file of listFiles(path7.join(paths.system, "guidelines"))) {
+    if (path7.extname(file).toLowerCase() !== ".md") continue;
+    const stem = path7.basename(file, ".md");
+    const { data, body } = parseFrontmatter(fs7.readFileSync(file, "utf8"));
     const prefix = /^(\d+)[-_. ]+(.*)$/.exec(stem);
     const order = data.order !== void 0 ? Number(data.order) : prefix ? Number(prefix[1]) : 1e3;
     guidelines.push({
@@ -1288,14 +1337,14 @@ function loadSystem(paths, urls) {
   }
   guidelines.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
   const assets = [];
-  const assetsDir = path6.join(paths.system, "assets");
+  const assetsDir = path7.join(paths.system, "assets");
   for (const file of listFiles(assetsDir, true)) {
-    const ext = path6.extname(file).toLowerCase();
+    const ext = path7.extname(file).toLowerCase();
     assets.push({
-      name: path6.basename(file),
-      path: path6.relative(paths.system, file).split(path6.sep).join("/"),
+      name: path7.basename(file),
+      path: path7.relative(paths.system, file).split(path7.sep).join("/"),
       url: urls.file(relToDesign(paths, file)),
-      size: fs6.statSync(file).size,
+      size: fs7.statSync(file).size,
       kind: IMAGE_EXT.has(ext) ? "image" : FONT_EXT.has(ext) ? "font" : "other"
     });
   }
@@ -1331,7 +1380,7 @@ function loadSystem(paths, urls) {
     },
     config,
     stylesheet,
-    tokensFile: fs6.existsSync(tokensFile) ? tokensFile : null,
+    tokensFile: fs7.existsSync(tokensFile) ? tokensFile : null,
     specimens
   };
 }
@@ -1348,10 +1397,10 @@ function summarizeSystem(system) {
 
 // src/core/project.ts
 function publicProblem(root, value) {
-  const dir = path7.resolve(root, value);
-  if (!fs7.existsSync(dir) || !fs7.statSync(dir).isDirectory()) return `no folder "${value}"`;
-  const real = fs7.realpathSync(dir);
-  const realRoot = fs7.realpathSync(root);
+  const dir = path8.resolve(root, value);
+  if (!fs8.existsSync(dir) || !fs8.statSync(dir).isDirectory()) return `no folder "${value}"`;
+  const real = fs8.realpathSync(dir);
+  const realRoot = fs8.realpathSync(root);
   if (real === realRoot || !isInside(realRoot, real)) return `"${value}" is not a folder inside the project`;
   return null;
 }
@@ -1373,9 +1422,9 @@ var DesignProject = class {
     const issues = [];
     let config = {};
     const file = this.paths.config;
-    if (fs7.existsSync(file)) {
+    if (fs8.existsSync(file)) {
       try {
-        const parsed = DesignConfigSchema.safeParse(JSON.parse(fs7.readFileSync(file, "utf8")));
+        const parsed = DesignConfigSchema.safeParse(JSON.parse(fs8.readFileSync(file, "utf8")));
         if (parsed.success) config = parsed.data;
         else
           for (const issue of describeZodError(parsed.error))
@@ -1388,6 +1437,14 @@ var DesignProject = class {
         });
       }
     }
+    if (config.app !== void 0) {
+      const dir = path8.resolve(this.paths.root, config.app);
+      const problem = !fs8.existsSync(path8.join(dir, "node_modules")) ? `no node_modules in "${config.app}"; install the app's dependencies there` : isInside(this.paths.root, dir) ? null : `"${config.app}" is not a folder inside the project`;
+      if (problem) {
+        issues.push({ severity: "error", file: relToRoot(this.paths, file), at: "app", message: problem });
+        config = { ...config, app: void 0 };
+      }
+    }
     if (config.public !== void 0) {
       const problem = publicProblem(this.paths.root, config.public);
       if (problem) {
@@ -1398,10 +1455,15 @@ var DesignProject = class {
     this.configCache = { config, issues };
     return this.configCache;
   }
+  /** The app package from design.json `app`, when it is usable. */
+  appDir() {
+    const configured = this.config().config.app;
+    return configured === void 0 ? null : path8.resolve(this.paths.root, configured);
+  }
   /** The public folder from design.json, when it is a folder inside the project. */
   publicDir() {
     const configured = this.config().config.public;
-    return configured === void 0 ? null : path7.resolve(this.paths.root, configured);
+    return configured === void 0 ? null : path8.resolve(this.paths.root, configured);
   }
   /** The public folder's files, relative to it; `invalidatePublic` when they change. */
   publicFiles() {
@@ -1421,11 +1483,11 @@ var DesignProject = class {
     const configured = this.config().config.name;
     if (configured) return configured;
     try {
-      const manifest = JSON.parse(fs7.readFileSync(path7.join(this.paths.root, "package.json"), "utf8"));
+      const manifest = JSON.parse(fs8.readFileSync(path8.join(this.paths.root, "package.json"), "utf8"));
       if (typeof manifest.name === "string" && manifest.name) return manifest.name;
     } catch {
     }
-    return path7.basename(this.paths.root);
+    return path8.basename(this.paths.root);
   }
   system() {
     if (this.systemCache === void 0) this.systemCache = loadSystem(this.paths, this.urls);
@@ -1437,7 +1499,7 @@ var DesignProject = class {
   canvas(id2) {
     const cached = this.canvasCache.get(id2);
     if (cached) return cached;
-    if (!fs7.existsSync(path7.join(this.paths.canvases, id2))) return null;
+    if (!fs8.existsSync(path8.join(this.paths.canvases, id2))) return null;
     const canvas = loadCanvas(this.paths, id2, this.urls, this.snapshots);
     this.canvasCache.set(id2, canvas);
     return canvas;
@@ -1462,13 +1524,26 @@ var DesignProject = class {
       version: packageVersion(),
       system: system ? summarizeSystem(system) : null,
       canvases: this.canvases().map(summarize),
-      issues: this.config().issues
+      issues: this.config().issues,
+      icon: this.iconUrl()
     };
   }
+  /** The icon's URL, with its change time so a new icon is fetched anew. */
+  iconUrl() {
+    const file = iconFile(this.paths);
+    if (!file) return null;
+    return `${this.urls.file(relToDesign(this.paths, file))}?v=${Math.round(fs8.statSync(file).mtimeMs)}`;
+  }
+  iconIssues() {
+    const file = iconFile(this.paths);
+    const problem = file ? iconProblem(fs8.readFileSync(file), path8.extname(file).slice(1)) : null;
+    return problem ? [{ severity: "error", file: relToRoot(this.paths, file), message: problem }] : [];
+  }
   /** Every problem in the project, for `design check`. */
   issues() {
     return [
       ...this.config().issues,
+      ...this.iconIssues(),
       ...this.system()?.doc.issues ?? [],
       ...this.canvases().flatMap((canvas) => canvas.doc.issues)
     ];
@@ -1508,21 +1583,21 @@ var STATIC_URLS = {
 };
 
 // src/server/entries.ts
-import fs8 from "fs";
-import path8 from "path";
+import fs9 from "fs";
+import path9 from "path";
 var SYSTEM_CSS = "system.css";
 var HTML_BOOT = "html-boot.js";
 function writeIfChanged(file, content) {
   try {
-    if (fs8.readFileSync(file, "utf8") === content) return false;
+    if (fs9.readFileSync(file, "utf8") === content) return false;
   } catch {
   }
-  fs8.mkdirSync(path8.dirname(file), { recursive: true });
-  fs8.writeFileSync(file, content);
+  fs9.mkdirSync(path9.dirname(file), { recursive: true });
+  fs9.writeFileSync(file, content);
   return true;
 }
 function importPath(fromDir, file) {
-  const rel = toPosix(path8.relative(fromDir, file));
+  const rel = toPosix(path9.relative(fromDir, file));
   return rel.startsWith(".") ? rel : `./${rel}`;
 }
 var css = (file) => JSON.stringify(toPosix(file));
@@ -1535,10 +1610,10 @@ var Entries = class {
     return this.project.paths.entries;
   }
   systemCssFile() {
-    return path8.join(this.dir, SYSTEM_CSS);
+    return path9.join(this.dir, SYSTEM_CSS);
   }
   entryFile(source) {
-    return path8.join(this.dir, source.canvas, `${source.id}.js`);
+    return path9.join(this.dir, source.canvas, `${source.id}.js`);
   }
   /** Tailwind with the design tokens, or the stylesheet system.json names; scans every file in `.design`. */
   systemCss() {
@@ -1555,14 +1630,14 @@ var Entries = class {
       if (system?.tokensFile) lines.push(`@import ${css(system.tokensFile)};`);
     }
     lines.push(`@source ${css(paths.design)};`, `@source not ${css(paths.cache)};`);
-    lines.push(`@source not ${css(path8.join(paths.design, "node_modules"))};`);
-    for (const extra of config.sources ?? []) lines.push(`@source ${css(path8.resolve(paths.root, extra))};`);
+    lines.push(`@source not ${css(path9.join(paths.design, "node_modules"))};`);
+    for (const extra of config.sources ?? []) lines.push(`@source ${css(path9.resolve(paths.root, extra))};`);
     return `${lines.join("\n")}
 `;
   }
   entrySource(source) {
     const file = this.entryFile(source);
-    const dir = path8.dirname(file);
+    const dir = path9.dirname(file);
     const lines = [];
     if (source.system) lines.push(`import ${JSON.stringify(importPath(dir, this.systemCssFile()))}`);
     if (source.builtin === "typography") {
@@ -1577,7 +1652,7 @@ var Entries = class {
         `import * as screen from ${JSON.stringify(importPath(dir, source.file))}`,
         "",
         `const Screen = screen.default ?? Object.values(screen).find((value) => typeof value === 'function')`,
-        "if (!Screen) throw new Error(" + JSON.stringify(`${path8.basename(source.file)} has no component to render: export one as default`) + ")",
+        "if (!Screen) throw new Error(" + JSON.stringify(`${path9.basename(source.file)} has no component to render: export one as default`) + ")",
         "hmr(import.meta.hot)",
         "mount(Screen)"
       );
@@ -1590,14 +1665,14 @@ ${lines.join("\n")}
   sync() {
     writeIfChanged(this.systemCssFile(), this.systemCss());
     writeIfChanged(
-      path8.join(this.dir, HTML_BOOT),
+      path9.join(this.dir, HTML_BOOT),
       `// Generated by foss-design.
 import { boot, hmr } from '@design/runtime'
 boot()
 hmr(import.meta.hot)
 `
     );
-    const wanted = /* @__PURE__ */ new Set([this.systemCssFile(), path8.join(this.dir, HTML_BOOT)]);
+    const wanted = /* @__PURE__ */ new Set([this.systemCssFile(), path9.join(this.dir, HTML_BOOT)]);
     for (const source of this.project.sources()) {
       if (source.format !== "module") continue;
       const file = this.entryFile(source);
@@ -1612,21 +1687,21 @@ hmr(import.meta.hot)
    * Vite bundle again and fail the requests in flight (504 Outdated Optimize Dep).
    */
   files() {
-    const files = [path8.join(this.dir, HTML_BOOT)];
+    const files = [path9.join(this.dir, HTML_BOOT)];
     for (const source of this.project.sources()) {
       if (source.format === "module") files.push(this.entryFile(source));
-      else if (!source.builtin && fs8.existsSync(source.file)) files.push(source.file);
+      else if (!source.builtin && fs9.existsSync(source.file)) files.push(source.file);
     }
     return files;
   }
   prune(dir, wanted) {
-    if (!fs8.existsSync(dir)) return;
-    for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
-      const full = path8.join(dir, entry.name);
+    if (!fs9.existsSync(dir)) return;
+    for (const entry of fs9.readdirSync(dir, { withFileTypes: true })) {
+      const full = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         this.prune(full, wanted);
-        if (fs8.readdirSync(full).length === 0) fs8.rmdirSync(full);
-      } else if (!wanted.has(full)) fs8.rmSync(full);
+        if (fs9.readdirSync(full).length === 0) fs9.rmdirSync(full);
+      } else if (!wanted.has(full)) fs9.rmSync(full);
     }
   }
 };
@@ -1694,68 +1769,132 @@ ${html}
 }
 
 // src/server/links.ts
-import fs9 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path10 from "path";
 var SHIPPED_PACKAGES = ["react", "react-dom", "motion", "lucide-react", "clsx", "tailwind-merge"];
 function findPackageDir(fromDir, name, skip) {
-  let dir = path9.resolve(fromDir);
+  let dir = path10.resolve(fromDir);
   for (; ; ) {
-    const modules = path9.join(dir, "node_modules");
-    const candidate = path9.join(modules, name);
-    if (modules !== skip && fs9.existsSync(path9.join(candidate, "package.json"))) return candidate;
-    const parent = path9.dirname(dir);
+    const modules = path10.join(dir, "node_modules");
+    const candidate = path10.join(modules, name);
+    if (modules !== skip && fs10.existsSync(path10.join(candidate, "package.json"))) return candidate;
+    const parent = path10.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 function isLink(file) {
   try {
-    return fs9.lstatSync(file).isSymbolicLink();
+    return fs10.lstatSync(file).isSymbolicLink();
   } catch {
     return false;
   }
 }
-function linkShippedPackages(paths) {
-  const modules = path9.join(paths.design, "node_modules");
+function ensureLink(link, target) {
+  let current = null;
+  try {
+    current = fs10.realpathSync(link);
+  } catch {
+  }
+  if (current === target) return;
+  if (isLink(link)) fs10.unlinkSync(link);
+  fs10.mkdirSync(path10.dirname(link), { recursive: true });
+  fs10.symlinkSync(target, link, process.platform === "win32" ? "junction" : "dir");
+}
+function appPackages(appDir) {
+  const found = /* @__PURE__ */ new Map();
+  const modules = path10.join(appDir, "node_modules");
+  const add = (name, dir) => {
+    try {
+      if (fs10.existsSync(path10.join(dir, "package.json"))) found.set(name, fs10.realpathSync(dir));
+    } catch {
+    }
+  };
+  let entries = [];
+  try {
+    entries = fs10.readdirSync(modules, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const dir = path10.join(modules, entry.name);
+    if (!entry.name.startsWith("@")) {
+      add(entry.name, dir);
+      continue;
+    }
+    try {
+      for (const scoped of fs10.readdirSync(dir))
+        if (!scoped.startsWith(".")) add(`${entry.name}/${scoped}`, path10.join(dir, scoped));
+    } catch {
+    }
+  }
+  return found;
+}
+var APP_LINKS = ".foss-design-app.json";
+function linkShippedPackages(paths, appDir = null) {
+  const modules = path10.join(paths.design, "node_modules");
   const linked = [];
   const allow = /* @__PURE__ */ new Set();
+  const app = appDir ? appPackages(appDir) : /* @__PURE__ */ new Map();
+  const placedByUser = (link) => fs10.existsSync(link) && !isLink(link);
   for (const name of SHIPPED_PACKAGES) {
-    const link = path9.join(modules, name);
-    const placedByUser = fs9.existsSync(link) && !isLink(link);
-    const own = placedByUser ? link : findPackageDir(paths.design, name, modules);
+    const link = path10.join(modules, name);
+    if (app.has(name) && !placedByUser(link)) continue;
+    const own = placedByUser(link) ? link : findPackageDir(paths.design, name, modules);
     if (own) {
-      allow.add(path9.dirname(fs9.realpathSync(own)));
-      if (isLink(link)) fs9.unlinkSync(link);
+      allow.add(path10.dirname(fs10.realpathSync(own)));
+      if (isLink(link)) fs10.unlinkSync(link);
       continue;
     }
     const shipped = findPackageDir(PKG_ROOT, name);
     if (!shipped) continue;
-    const target2 = fs9.realpathSync(shipped);
-    allow.add(path9.dirname(target2));
-    let current2 = null;
-    try {
-      current2 = fs9.realpathSync(link);
-    } catch {
-    }
-    if (current2 !== target2) {
-      if (isLink(link)) fs9.unlinkSync(link);
-      fs9.mkdirSync(path9.dirname(link), { recursive: true });
-      fs9.symlinkSync(target2, link, process.platform === "win32" ? "junction" : "dir");
-    }
+    const target2 = fs10.realpathSync(shipped);
+    allow.add(path10.dirname(target2));
+    ensureLink(link, target2);
     linked.push(name);
   }
-  const self = path9.join(modules, "foss-design");
-  const target = fs9.realpathSync(PKG_ROOT);
+  const fromApp = [];
+  for (const [name, target2] of app) {
+    const link = path10.join(modules, name);
+    if (placedByUser(link)) continue;
+    ensureLink(link, target2);
+    allow.add(path10.dirname(target2));
+    fromApp.push(name);
+  }
+  const record2 = path10.join(modules, APP_LINKS);
+  let before = [];
+  try {
+    before = JSON.parse(fs10.readFileSync(record2, "utf8"));
+  } catch {
+  }
+  for (const name of before) {
+    const link = path10.join(modules, name);
+    if (!app.has(name) && !SHIPPED_PACKAGES.includes(name) && isLink(link)) {
+      fs10.unlinkSync(link);
+      if (name.startsWith("@"))
+        try {
+          fs10.rmdirSync(path10.dirname(link));
+        } catch {
+        }
+    }
+  }
+  if (fromApp.length || before.length) {
+    fs10.mkdirSync(modules, { recursive: true });
+    fs10.writeFileSync(record2, JSON.stringify(fromApp.sort()));
+  }
+  const self = path10.join(modules, "foss-design");
+  const target = fs10.realpathSync(PKG_ROOT);
   let current = null;
   try {
-    current = fs9.realpathSync(self);
+    current = fs10.realpathSync(self);
   } catch {
   }
   if (current !== target) {
-    if (isLink(self)) fs9.unlinkSync(self);
-    if (!fs9.existsSync(self)) {
-      fs9.mkdirSync(modules, { recursive: true });
-      fs9.symlinkSync(target, self, process.platform === "win32" ? "junction" : "dir");
+    if (isLink(self)) fs10.unlinkSync(self);
+    if (!fs10.existsSync(self)) {
+      fs10.mkdirSync(modules, { recursive: true });
+      fs10.symlinkSync(target, self, process.platform === "win32" ? "junction" : "dir");
     }
   }
   allow.add(target);
@@ -1764,8 +1903,8 @@ function linkShippedPackages(paths) {
 
 // src/server/vite.ts
 import { createHash as createHash2 } from "crypto";
-import fs10 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path11 from "path";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 var escapeRegExp = (text2) => text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1777,30 +1916,31 @@ function aliases(project) {
     { find: /^@system\//, replacement: `${toPosix(paths.system)}/` }
   ];
   for (const [key, target] of Object.entries(project.config().config.alias ?? {})) {
-    const replacement = toPosix(path10.resolve(paths.root, target));
+    const replacement = toPosix(path11.resolve(paths.root, target));
     list.push(
       key.endsWith("/") ? { find: new RegExp(`^${escapeRegExp(key)}`), replacement: `${replacement.replace(/\/$/, "")}/` } : { find: new RegExp(`^${escapeRegExp(key)}(?=/|$)`), replacement }
     );
   }
   return list;
 }
-function dropStaleDepCache(paths) {
-  const dir = path10.join(paths.cache, "vite");
-  const stamp = path10.join(paths.cache, "vite-runtime");
+function dropStaleDepCache(paths, appDir = null) {
+  const dir = path11.join(paths.cache, "vite");
+  const stamp = path11.join(paths.cache, "vite-runtime");
   let runtime = "";
   try {
-    runtime = createHash2("sha256").update(fs10.readFileSync(PKG.runtime)).digest("hex");
+    runtime = createHash2("sha256").update(fs11.readFileSync(PKG.runtime)).digest("hex");
   } catch {
   }
+  if (appDir) runtime += ` ${appDir}`;
   let seen = "";
   try {
-    seen = fs10.readFileSync(stamp, "utf8");
+    seen = fs11.readFileSync(stamp, "utf8");
   } catch {
   }
   if (seen === runtime) return;
-  fs10.rmSync(dir, { recursive: true, force: true });
-  fs10.mkdirSync(paths.cache, { recursive: true });
-  fs10.writeFileSync(stamp, runtime);
+  fs11.rmSync(dir, { recursive: true, force: true });
+  fs11.mkdirSync(paths.cache, { recursive: true });
+  fs11.writeFileSync(stamp, runtime);
 }
 function baseConfig(project) {
   const { paths } = project;
@@ -1808,7 +1948,7 @@ function baseConfig(project) {
     configFile: false,
     envDir: false,
     root: paths.design,
-    cacheDir: path10.join(paths.cache, "vite"),
+    cacheDir: path11.join(paths.cache, "vite"),
     // design.json `public`: served under the frames' base, so HTML and CSS paths such as `/logo.png` resolve.
     publicDir: project.publicDir() ?? false,
     logLevel: "warn",
@@ -1828,7 +1968,7 @@ var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".jsx", ".mts", ".cts",
 var BUNDLED_REF = /<(script|link|img|source|video|audio|image|use|input)\b[^>]*>/gi;
 var encodePath2 = (rel) => rel.split("/").map(encodeURIComponent).join("/");
 function relUrl(fromDir, file) {
-  const rel = toPosix(path11.relative(fromDir, file));
+  const rel = toPosix(path12.relative(fromDir, file));
   return rel.startsWith(".") ? rel : `./${rel}`;
 }
 function staticSnapshots(paths) {
@@ -1838,7 +1978,7 @@ function staticSnapshots(paths) {
     let data = metaCache.get(canvas);
     if (!data) {
       try {
-        data = JSON.parse(fs11.readFileSync(path11.join(paths.snapshots, canvas, "meta.json"), "utf8"));
+        data = JSON.parse(fs12.readFileSync(path12.join(paths.snapshots, canvas, "meta.json"), "utf8"));
       } catch {
       }
       data ??= {};
@@ -1852,8 +1992,8 @@ function staticSnapshots(paths) {
     const urls = {};
     const thumbs = {};
     for (const theme2 of THEMES) {
-      const file = path11.join(paths.snapshots, canvas, `${id2}.${theme2}.png`);
-      if (!entry[theme2] || !fs11.existsSync(file)) continue;
+      const file = path12.join(paths.snapshots, canvas, `${id2}.${theme2}.png`);
+      if (!entry[theme2] || !fs12.existsSync(file)) continue;
       const rel = `_snap/${canvas}/${id2}.${theme2}.png`;
       copies.set(file, rel);
       urls[theme2] = `${encodePath2(rel)}?v=${entry[theme2]}`;
@@ -1877,29 +2017,29 @@ function rewriteRefs(html, originalDir, stagedDir) {
       (whole, attr2, quote, value) => {
         if (!value || /^(?:[a-z][a-z0-9+.-]*:|\/|#|\{)/i.test(value)) return whole;
         const [pathname = "", suffix = ""] = /^([^?#]*)(.*)$/.exec(value).slice(1);
-        const target = path11.resolve(originalDir, decodeURIComponent(pathname));
-        if (!fs11.existsSync(target)) return whole;
+        const target = path12.resolve(originalDir, decodeURIComponent(pathname));
+        if (!fs12.existsSync(target)) return whole;
         return `${attr2}${quote}${relUrl(stagedDir, target)}${suffix}${quote}`;
       }
     );
   });
 }
 function copyTree(from, to, filter) {
-  if (!fs11.existsSync(from)) return;
-  for (const entry of fs11.readdirSync(from, { withFileTypes: true })) {
+  if (!fs12.existsSync(from)) return;
+  for (const entry of fs12.readdirSync(from, { withFileTypes: true })) {
     if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-    const source = path11.join(from, entry.name);
-    const target = path11.join(to, entry.name);
+    const source = path12.join(from, entry.name);
+    const target = path12.join(to, entry.name);
     if (entry.isDirectory()) copyTree(source, target, filter);
-    else if (filter(source) && !fs11.existsSync(target)) {
-      fs11.mkdirSync(path11.dirname(target), { recursive: true });
-      fs11.copyFileSync(source, target);
+    else if (filter(source) && !fs12.existsSync(target)) {
+      fs12.mkdirSync(path12.dirname(target), { recursive: true });
+      fs12.copyFileSync(source, target);
     }
   }
 }
 function writeJson(file, value) {
-  fs11.mkdirSync(path11.dirname(file), { recursive: true });
-  fs11.writeFileSync(file, JSON.stringify(value));
+  fs12.mkdirSync(path12.dirname(file), { recursive: true });
+  fs12.writeFileSync(file, JSON.stringify(value));
 }
 async function buildSite(paths, out, options = {}) {
   const snapshots = staticSnapshots(paths);
@@ -1914,21 +2054,21 @@ async function buildSite(paths, out, options = {}) {
   const system = options.includeSystem === false ? null : loadedSystem;
   const entries = new Entries(project);
   entries.sync();
-  linkShippedPackages(paths);
+  linkShippedPackages(paths, project.appDir());
   const publicDir = project.publicDir();
   const publicFiles2 = project.publicFiles();
-  const staging = path11.join(paths.cache, "build", "src");
-  fs11.rmSync(staging, { recursive: true, force: true });
+  const staging = path12.join(paths.cache, "build", "src");
+  fs12.rmSync(staging, { recursive: true, force: true });
   const fonts = loadedSystem?.doc.fonts ?? [];
   const sources = [...system?.specimens ?? [], ...canvases.flatMap((canvas) => canvas.screens)];
   const inputs = [];
   const htmlScreens = [];
   for (const source of sources) {
-    if (!source.builtin && !fs11.existsSync(source.file)) continue;
-    const siteDir = path11.join("_s", source.canvas, source.id);
-    const dir = path11.join(staging, siteDir);
-    const file = path11.join(dir, "index.html");
-    fs11.mkdirSync(dir, { recursive: true });
+    if (!source.builtin && !fs12.existsSync(source.file)) continue;
+    const siteDir = path12.join("_s", source.canvas, source.id);
+    const dir = path12.join(staging, siteDir);
+    const file = path12.join(dir, "index.html");
+    fs12.mkdirSync(dir, { recursive: true });
     const canvasTheme = source.canvas === SYSTEM_CANVAS ? void 0 : project.canvas(source.canvas)?.doc.theme;
     const head = {
       source,
@@ -1937,24 +2077,24 @@ async function buildSite(paths, out, options = {}) {
       snapshots: false,
       autoHeight: source.autoHeight ?? false,
       // The public folder lands at the site root, which frames reach through `../`.
-      public: publicFiles2.length ? { base: `${toPosix(path11.relative(dir, staging))}/`, files: publicFiles2 } : void 0
+      public: publicFiles2.length ? { base: `${toPosix(path12.relative(dir, staging))}/`, files: publicFiles2 } : void 0
     };
     if (source.format === "module") {
-      fs11.writeFileSync(file, moduleShell(head, relUrl(dir, entries.entryFile(source))));
+      fs12.writeFileSync(file, moduleShell(head, relUrl(dir, entries.entryFile(source))));
     } else {
-      const raw = rewriteRefs(fs11.readFileSync(source.file, "utf8"), path11.dirname(source.file), dir);
+      const raw = rewriteRefs(fs12.readFileSync(source.file, "utf8"), path12.dirname(source.file), dir);
       const withSystem = source.system && !optsOutOfSystem(raw);
       const html = injectIntoHtml(raw, {
         ...head,
         systemCss: withSystem ? relUrl(dir, entries.systemCssFile()) : void 0,
-        boot: relUrl(dir, path11.join(entries.dir, HTML_BOOT))
+        boot: relUrl(dir, path12.join(entries.dir, HTML_BOOT))
       });
-      fs11.writeFileSync(file, html);
+      fs12.writeFileSync(file, html);
       htmlScreens.push({ source, dir: siteDir });
     }
     inputs.push(file);
   }
-  fs11.mkdirSync(out, { recursive: true });
+  fs12.mkdirSync(out, { recursive: true });
   if (inputs.length) {
     const base = baseConfig(project);
     await build({
@@ -1975,14 +2115,14 @@ async function buildSite(paths, out, options = {}) {
       }
     });
   } else {
-    fs11.rmSync(out, { recursive: true, force: true });
-    fs11.mkdirSync(out, { recursive: true });
+    fs12.rmSync(out, { recursive: true, force: true });
+    fs12.mkdirSync(out, { recursive: true });
   }
   for (const { source, dir } of htmlScreens) {
     copyTree(
-      path11.dirname(source.file),
-      path11.join(out, dir),
-      (file) => !SOURCE_EXT.has(path11.extname(file).toLowerCase())
+      path12.dirname(source.file),
+      path12.join(out, dir),
+      (file) => !SOURCE_EXT.has(path12.extname(file).toLowerCase())
     );
   }
   const files = /* @__PURE__ */ new Set();
@@ -1992,38 +2132,40 @@ async function buildSite(paths, out, options = {}) {
         for (const item of section.items) if (item.kind === "image" && item.url.startsWith("_f/")) files.add(item.url);
   }
   for (const asset of system?.doc.assets ?? []) files.add(asset.url);
+  const icon = project.iconUrl();
+  if (icon) files.add(icon.split("?")[0]);
   for (const url of files) {
     const rel = url.slice("_f/".length).split("/").map(decodeURIComponent).join("/");
-    const from = path11.join(paths.design, rel);
-    if (!fs11.existsSync(from)) continue;
-    const to = path11.join(out, "_f", rel);
-    fs11.mkdirSync(path11.dirname(to), { recursive: true });
-    fs11.copyFileSync(from, to);
+    const from = path12.join(paths.design, rel);
+    if (!fs12.existsSync(from)) continue;
+    const to = path12.join(out, "_f", rel);
+    fs12.mkdirSync(path12.dirname(to), { recursive: true });
+    fs12.copyFileSync(from, to);
   }
   const info = project.info(true);
   const snapshotDirs = canvasIds.map((id2) => `_snap/${id2}/`);
   for (const [from, rel] of snapshots.copies) {
     if (!snapshotDirs.some((dir) => rel.startsWith(dir))) continue;
-    const to = path11.join(out, rel);
-    fs11.mkdirSync(path11.dirname(to), { recursive: true });
-    fs11.copyFileSync(from, to);
+    const to = path12.join(out, rel);
+    fs12.mkdirSync(path12.dirname(to), { recursive: true });
+    fs12.copyFileSync(from, to);
   }
   if (!system) info.system = null;
   info.canvases = info.canvases.filter((canvas) => canvasIds.includes(canvas.id));
-  writeJson(path11.join(out, "api", "project.json"), info);
-  for (const canvas of canvases) writeJson(path11.join(out, "api", "canvas", `${canvas.doc.id}.json`), canvas.doc);
+  writeJson(path12.join(out, "api", "project.json"), info);
+  for (const canvas of canvases) writeJson(path12.join(out, "api", "canvas", `${canvas.doc.id}.json`), canvas.doc);
   if (system) {
-    writeJson(path11.join(out, "api", "system.json"), system.doc);
+    writeJson(path12.join(out, "api", "system.json"), system.doc);
     const texts = {};
     for (const component of system.doc.components) {
       for (const rel of [component.specimen, ...component.sources]) {
-        const file = path11.join(paths.root, rel);
-        if (!(rel in texts) && fs11.existsSync(file)) texts[rel] = fs11.readFileSync(file, "utf8");
+        const file = path12.join(paths.root, rel);
+        if (!(rel in texts) && fs12.existsSync(file)) texts[rel] = fs12.readFileSync(file, "utf8");
       }
     }
-    writeJson(path11.join(out, "api", "sources.json"), texts);
+    writeJson(path12.join(out, "api", "sources.json"), texts);
   }
-  fs11.rmSync(staging, { recursive: true, force: true });
+  fs12.rmSync(staging, { recursive: true, force: true });
   const errors = [
     ...only ? [] : project.config().issues,
     ...system?.doc.issues ?? [],
@@ -2032,21 +2174,21 @@ async function buildSite(paths, out, options = {}) {
   const { absoluteAssets } = options.includeViewer === false ? { absoluteAssets: false } : copyViewer(PKG.viewer, out);
   if (publicDir) {
     for (const rel of publicFiles2) {
-      const to = path11.join(out, rel);
-      if (fs11.existsSync(to)) continue;
-      fs11.mkdirSync(path11.dirname(to), { recursive: true });
-      fs11.copyFileSync(path11.join(publicDir, rel), to);
+      const to = path12.join(out, rel);
+      if (fs12.existsSync(to)) continue;
+      fs12.mkdirSync(path12.dirname(to), { recursive: true });
+      fs12.copyFileSync(path12.join(publicDir, rel), to);
     }
   }
   return { out, canvases: canvasIds, frames: inputs.length, errors, absoluteAssets };
 }
 function copyViewer(viewerDir, out) {
   copyTree(viewerDir, out, () => true);
-  const index = path11.join(out, "index.html");
-  const html = fs11.readFileSync(index, "utf8");
+  const index = path12.join(out, "index.html");
+  const html = fs12.readFileSync(index, "utf8");
   const flag2 = "<script>window.__DESIGN_STATIC__=true</script>";
   const head = /<head(\s[^>]*)?>/i.exec(html);
-  fs11.writeFileSync(
+  fs12.writeFileSync(
     index,
     head ? html.slice(0, head.index + head[0].length) + flag2 + html.slice(head.index + head[0].length) : flag2 + html
   );
@@ -2128,8 +2270,8 @@ function progress() {
 // src/cli/commands/build.ts
 function pack(out) {
   const archive = `${out.replace(/[\\/]+$/, "")}.tar.gz`;
-  fs12.rmSync(archive, { force: true });
-  const entries = fs12.readdirSync(out);
+  fs13.rmSync(archive, { force: true });
+  const entries = fs13.readdirSync(out);
   const result = spawnSync("tar", ["-czf", archive, "-C", out, ...entries], {
     stdio: ["ignore", "ignore", "pipe"],
     env: { ...process.env, COPYFILE_DISABLE: "1" }
@@ -2139,10 +2281,10 @@ function pack(out) {
   return archive;
 }
 async function runBuild(paths, canvases, options) {
-  if (!fs12.existsSync(path12.join(PKG.viewer, "index.html"))) {
+  if (!fs13.existsSync(path13.join(PKG.viewer, "index.html"))) {
     throw new CliError("The viewer is missing from this foss-design install (dist/viewer). Rebuild or reinstall it.");
   }
-  const out = path12.resolve(options.out ?? path12.join(paths.cache, "site"));
+  const out = path13.resolve(options.out ?? path13.join(paths.cache, "site"));
   if (out === paths.root || out === paths.design) throw new CliError(`Refusing to build into ${out}`);
   print(dim(`Building ${canvases.length ? canvases.join(", ") : "every canvas"} and the design system\u2026`));
   let result;
@@ -2167,8 +2309,8 @@ import os from "os";
 
 // src/cloud/units.ts
 import { createHash as createHash3 } from "crypto";
-import fs13 from "fs";
-import path13 from "path";
+import fs14 from "fs";
+import path14 from "path";
 var SYSTEM_UNIT = "system";
 var CANVAS_PREFIX = "canvas/";
 var LOCAL_ONLY = /* @__PURE__ */ new Set(["cloud.json", "node_modules"]);
@@ -2196,7 +2338,7 @@ function caseClashes(keys) {
 }
 function unitRoot(paths, key) {
   const id2 = unitCanvasId(key);
-  return id2 === null ? paths.design : path13.join(paths.canvases, id2);
+  return id2 === null ? paths.design : path14.join(paths.canvases, id2);
 }
 function unitRelative(key, rel) {
   const id2 = unitCanvasId(key);
@@ -2214,7 +2356,7 @@ function hashBuffer(data) {
   return createHash3("sha256").update(data).digest("hex");
 }
 function hashFile(file) {
-  const data = fs13.readFileSync(file);
+  const data = fs14.readFileSync(file);
   return { hash: hashBuffer(data), size: data.length };
 }
 var warnedLinks = /* @__PURE__ */ new Set();
@@ -2227,34 +2369,34 @@ function warnLink(rel) {
 function walk(dir, base, out) {
   let entries;
   try {
-    entries = fs13.readdirSync(dir, { withFileTypes: true });
+    entries = fs14.readdirSync(dir, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-    const full = path13.join(dir, entry.name);
+    const full = path14.join(dir, entry.name);
     let isFile = entry.isFile();
     let isDir = entry.isDirectory();
     if (entry.isSymbolicLink()) {
       isDir = false;
       isFile = false;
       try {
-        const target = fs13.realpathSync(full);
-        const root = fs13.realpathSync(base);
-        if (target.startsWith(root + path13.sep)) isFile = fs13.statSync(target).isFile();
-        else warnLink(toPosix(path13.relative(base, full)));
+        const target = fs14.realpathSync(full);
+        const root = fs14.realpathSync(base);
+        if (target.startsWith(root + path14.sep)) isFile = fs14.statSync(target).isFile();
+        else warnLink(toPosix(path14.relative(base, full)));
       } catch {
       }
     }
     if (isDir) walk(full, base, out);
-    else if (isFile) out[toPosix(path13.relative(base, full))] = hashFile(full);
+    else if (isFile) out[toPosix(path14.relative(base, full))] = hashFile(full);
   }
 }
 function unitManifest(paths, key) {
   const manifest = {};
   if (key === SYSTEM_UNIT) {
-    if (fs13.existsSync(paths.config) && fs13.statSync(paths.config).isFile())
+    if (fs14.existsSync(paths.config) && fs14.statSync(paths.config).isFile())
       manifest["design.json"] = hashFile(paths.config);
     walk(paths.system, paths.design, manifest);
   } else walk(unitRoot(paths, key), paths.design, manifest);
@@ -2263,13 +2405,13 @@ function unitManifest(paths, key) {
 function buildManifest(dir) {
   const manifest = {};
   const visit = (current) => {
-    for (const entry of fs13.readdirSync(current, { withFileTypes: true })) {
-      const full = path13.join(current, entry.name);
+    for (const entry of fs14.readdirSync(current, { withFileTypes: true })) {
+      const full = path14.join(current, entry.name);
       if (entry.isDirectory()) visit(full);
-      else if (entry.isFile()) manifest[toPosix(path13.relative(dir, full))] = hashFile(full);
+      else if (entry.isFile()) manifest[toPosix(path14.relative(dir, full))] = hashFile(full);
     }
   };
-  if (fs13.existsSync(dir)) visit(dir);
+  if (fs14.existsSync(dir)) visit(dir);
   return sortManifest(manifest);
 }
 function sortManifest(manifest) {
@@ -2278,18 +2420,18 @@ function sortManifest(manifest) {
 function scanLocal(paths) {
   const units = /* @__PURE__ */ new Map();
   const notSynced = [];
-  if (!fs13.existsSync(paths.design)) return { units, notSynced };
+  if (!fs14.existsSync(paths.design)) return { units, notSynced };
   const system = unitManifest(paths, SYSTEM_UNIT);
   if (Object.keys(system).length) units.set(SYSTEM_UNIT, { key: SYSTEM_UNIT, kind: "system", manifest: system });
-  for (const entry of fs13.readdirSync(paths.design, { withFileTypes: true })) {
+  for (const entry of fs14.readdirSync(paths.design, { withFileTypes: true })) {
     const { name } = entry;
     if (name.startsWith(".") || LOCAL_ONLY.has(name)) continue;
     if (name === "design.json" && entry.isFile()) continue;
     if ((name === "system" || name === "canvas") && entry.isDirectory()) continue;
     notSynced.push(entry.isDirectory() ? `${name}/` : name);
   }
-  if (fs13.existsSync(paths.canvases) && fs13.statSync(paths.canvases).isDirectory()) {
-    for (const entry of fs13.readdirSync(paths.canvases, { withFileTypes: true })) {
+  if (fs14.existsSync(paths.canvases) && fs14.statSync(paths.canvases).isDirectory()) {
+    for (const entry of fs14.readdirSync(paths.canvases, { withFileTypes: true })) {
       if (entry.name.startsWith(".")) continue;
       if (!entry.isDirectory() || !ID_PATTERN.test(entry.name)) {
         notSynced.push(`canvas/${entry.name}${entry.isDirectory() ? "/" : ""}`);
@@ -2303,11 +2445,11 @@ function scanLocal(paths) {
   return { units, notSynced: notSynced.sort() };
 }
 function unitBuildDir(paths, key) {
-  return path13.join(paths.cache, "cloud", "build", ...key.split("/"));
+  return path14.join(paths.cache, "cloud", "build", ...key.split("/"));
 }
 async function buildUnit(paths, key, out = unitBuildDir(paths, key)) {
   const id2 = unitCanvasId(key);
-  fs13.rmSync(out, { recursive: true, force: true });
+  fs14.rmSync(out, { recursive: true, force: true });
   return buildSite(paths, out, {
     canvases: id2 === null ? [] : [id2],
     includeSystem: id2 === null,
@@ -2438,7 +2580,7 @@ var CloudClient = class {
   }
   host;
   token;
-  async send(method, path29, init) {
+  async send(method, path31, init) {
     const headers = {
       "User-Agent": `foss-design/${packageVersion()} (${os.platform()})`,
       Accept: "application/json"
@@ -2446,7 +2588,7 @@ var CloudClient = class {
     if (this.token) headers.Authorization = `Bearer ${this.token}`;
     if (init.type) headers["Content-Type"] = init.type;
     try {
-      return await fetch(`${this.host}/api${path29}`, {
+      return await fetch(`${this.host}/api${path31}`, {
         method,
         headers,
         body: init.body,
@@ -2467,8 +2609,8 @@ var CloudClient = class {
     throw errorFor(this.host, response.status, body, response.headers.get("retry-after"));
   }
   /** JSON in, JSON out; any non-2xx answer throws a CloudError. */
-  async request(method, path29, body) {
-    const response = await this.send(method, path29, {
+  async request(method, path31, body) {
+    const response = await this.send(method, path31, {
       body: body === void 0 ? void 0 : JSON.stringify(body),
       type: body === void 0 ? void 0 : "application/json",
       timeout: JSON_TIMEOUT
@@ -2480,7 +2622,7 @@ var CloudClient = class {
     try {
       return JSON.parse(text2);
     } catch {
-      throw new CloudError(`${this.host} answered ${method} ${path29} with something other than JSON`, 0, "bad_response");
+      throw new CloudError(`${this.host} answered ${method} ${path31} with something other than JSON`, 0, "bad_response");
     }
   }
   /** POST /device/code. */
@@ -2614,9 +2756,9 @@ var CloudClient = class {
 };
 
 // src/cloud/credentials.ts
-import fs14 from "fs";
+import fs15 from "fs";
 import os2 from "os";
-import path14 from "path";
+import path15 from "path";
 var DEFAULT_CLOUD = "https://app.fossdesign.dev";
 function normalizeHost(value) {
   let url;
@@ -2633,14 +2775,14 @@ function cloudHost() {
   return normalizeHost(process.env.FOSS_DESIGN_CLOUD || DEFAULT_CLOUD);
 }
 function credentialsFile() {
-  const base = process.platform === "win32" && process.env.APPDATA ? process.env.APPDATA : process.env.XDG_CONFIG_HOME || path14.join(os2.homedir(), ".config");
-  return path14.join(base, "foss-design", "credentials.json");
+  const base = process.platform === "win32" && process.env.APPDATA ? process.env.APPDATA : process.env.XDG_CONFIG_HOME || path15.join(os2.homedir(), ".config");
+  return path15.join(base, "foss-design", "credentials.json");
 }
 function readAll() {
   const file = credentialsFile();
-  if (!fs14.existsSync(file)) return {};
+  if (!fs15.existsSync(file)) return {};
   try {
-    const data = JSON.parse(fs14.readFileSync(file, "utf8"));
+    const data = JSON.parse(fs15.readFileSync(file, "utf8"));
     return data && typeof data === "object" && !Array.isArray(data) ? data : {};
   } catch (error) {
     throw new CliError(`${file} is not valid JSON (${error.message}); fix or delete it`);
@@ -2648,12 +2790,12 @@ function readAll() {
 }
 function writeAll(data) {
   const file = credentialsFile();
-  fs14.mkdirSync(path14.dirname(file), { recursive: true, mode: 448 });
+  fs15.mkdirSync(path15.dirname(file), { recursive: true, mode: 448 });
   const temp = `${file}.${process.pid}.tmp`;
-  fs14.writeFileSync(temp, `${JSON.stringify(data, null, 2)}
+  fs15.writeFileSync(temp, `${JSON.stringify(data, null, 2)}
 `, { mode: 384 });
-  fs14.chmodSync(temp, 384);
-  fs14.renameSync(temp, file);
+  fs15.chmodSync(temp, 384);
+  fs15.renameSync(temp, file);
 }
 function getCredential(host) {
   const entry = readAll()[host];
@@ -2676,17 +2818,17 @@ function requireCredential(host) {
 }
 
 // src/cloud/state.ts
-import fs15 from "fs";
-import path15 from "path";
-var linkFile = (paths) => path15.join(paths.design, "cloud.json");
-var cloudCache = (paths) => path15.join(paths.cache, "cloud");
-var incomingDir = (paths, key) => path15.join(cloudCache(paths), "incoming", ...key.split("/"));
+import fs16 from "fs";
+import path16 from "path";
+var linkFile = (paths) => path16.join(paths.design, "cloud.json");
+var cloudCache = (paths) => path16.join(paths.cache, "cloud");
+var incomingDir = (paths, key) => path16.join(cloudCache(paths), "incoming", ...key.split("/"));
 function readLink(paths) {
   const file = linkFile(paths);
-  if (!fs15.existsSync(file)) return null;
+  if (!fs16.existsSync(file)) return null;
   let data;
   try {
-    data = JSON.parse(fs15.readFileSync(file, "utf8"));
+    data = JSON.parse(fs16.readFileSync(file, "utf8"));
   } catch (error) {
     throw new CliError(`${file} is not valid JSON (${error.message}); run \`design link <project>\` again`);
   }
@@ -2716,9 +2858,9 @@ function writeLink(paths, link) {
     units: sorted(link.units),
     conflicts: sorted(link.conflicts)
   };
-  fs15.writeFileSync(temp, `${JSON.stringify(data, null, 2)}
+  fs16.writeFileSync(temp, `${JSON.stringify(data, null, 2)}
 `);
-  fs15.renameSync(temp, file);
+  fs16.renameSync(temp, file);
 }
 var hashes = (manifest) => Object.fromEntries(Object.entries(manifest).map(([file, entry]) => [file, entry.hash]));
 function diffFiles(a, b) {
@@ -2796,8 +2938,8 @@ var byUnit = (a, b) => a === SYSTEM_UNIT ? -1 : b === SYSTEM_UNIT ? 1 : a < b ?
 var plural = (count, word, many = `${word}s`) => `${count} ${count === 1 ? word : many}`;
 
 // src/cloud/pull.ts
-import fs16 from "fs";
-import path16 from "path";
+import fs17 from "fs";
+import path17 from "path";
 
 // src/capture/frames.ts
 var AUTO_VIEWPORT_HEIGHT = 900;
@@ -2880,34 +3022,34 @@ function checkManifest(key, manifest) {
   }
 }
 function writeInside(root, rel, data) {
-  const file = path16.join(root, rel);
+  const file = path17.join(root, rel);
   if (!isInside(root, file)) throw new CliError(`Refusing to write outside ${root}: ${rel}`);
-  fs16.mkdirSync(path16.dirname(file), { recursive: true });
-  if (!isInside(fs16.realpathSync(root), fs16.realpathSync(path16.dirname(file))))
+  fs17.mkdirSync(path17.dirname(file), { recursive: true });
+  if (!isInside(fs17.realpathSync(root), fs17.realpathSync(path17.dirname(file))))
     throw new CliError(`Refusing to write through a link out of ${root}: ${rel}`);
-  if (fs16.existsSync(file) && fs16.lstatSync(file).isSymbolicLink()) fs16.unlinkSync(file);
-  fs16.writeFileSync(file, data);
+  if (fs17.existsSync(file) && fs17.lstatSync(file).isSymbolicLink()) fs17.unlinkSync(file);
+  fs17.writeFileSync(file, data);
 }
 function pruneEmpty(dir, stop) {
   let current = dir;
   while (isInside(stop, current) && current !== stop) {
     try {
-      if (fs16.readdirSync(current).length) return;
-      fs16.rmdirSync(current);
+      if (fs17.readdirSync(current).length) return;
+      fs17.rmdirSync(current);
     } catch {
       return;
     }
-    current = path16.dirname(current);
+    current = path17.dirname(current);
   }
 }
 function applyUnit(paths, key, local, target, blobs) {
   const counts = { added: 0, changed: 0, removed: 0 };
-  const stop = key === SYSTEM_UNIT ? paths.design : path16.dirname(unitRoot(paths, key));
+  const stop = key === SYSTEM_UNIT ? paths.design : path17.dirname(unitRoot(paths, key));
   for (const rel of Object.keys(local)) {
     if (rel in target) continue;
-    const file = path16.join(paths.design, rel);
-    fs16.rmSync(file, { force: true });
-    pruneEmpty(path16.dirname(file), stop);
+    const file = path17.join(paths.design, rel);
+    fs17.rmSync(file, { force: true });
+    pruneEmpty(path17.dirname(file), stop);
     counts.removed++;
   }
   for (const [rel, entry] of Object.entries(target)) {
@@ -2970,7 +3112,7 @@ async function pull(ctx, options) {
     } else if (!s.ahead) {
       if (s.conflictRev !== void 0) {
         delete link.conflicts[key];
-        fs16.rmSync(incomingDir(paths, key), { recursive: true, force: true });
+        fs17.rmSync(incomingDir(paths, key), { recursive: true, force: true });
       }
       report.units.push({ ...reportFor("up_to_date"), rev: s.baseRev });
     } else if (!s.changed.length) {
@@ -3000,14 +3142,14 @@ async function pull(ctx, options) {
         headRev: unit.headRev,
         incoming: incomingDir(paths, key)
       };
-      entry.message = `changed here and in the cloud; the cloud version (r${unit.headRev}) is in ${path16.relative(paths.root, entry.incoming)}`;
-      if (s.conflictRev === unit.headRev && fs16.existsSync(entry.incoming)) report.units.push(entry);
+      entry.message = `changed here and in the cloud; the cloud version (r${unit.headRev}) is in ${path17.relative(paths.root, entry.incoming)}`;
+      if (s.conflictRev === unit.headRev && fs17.existsSync(entry.incoming)) report.units.push(entry);
       else plans.push({ key, kind: "incoming", remote: unit, report: entry });
     }
   }
   const byHash = /* @__PURE__ */ new Map();
   for (const unit of scan.units.values())
-    for (const [rel, entry] of Object.entries(unit.manifest)) byHash.set(entry.hash, path16.join(paths.design, rel));
+    for (const [rel, entry] of Object.entries(unit.manifest)) byHash.set(entry.hash, path17.join(paths.design, rel));
   const needed = /* @__PURE__ */ new Set();
   for (const plan of plans) {
     if (!plan.remote) continue;
@@ -3018,7 +3160,7 @@ async function pull(ctx, options) {
   const download = [];
   for (const hash of needed) {
     const file = byHash.get(hash);
-    if (file) blobs.set(hash, fs16.readFileSync(file));
+    if (file) blobs.set(hash, fs17.readFileSync(file));
     else download.push(hash);
   }
   if (download.length) {
@@ -3044,11 +3186,11 @@ async function pull(ctx, options) {
       if (plan.remote) link.units[key] = { rev: plan.remote.headRev, files: hashes(plan.remote.manifest) };
       else delete link.units[key];
       delete link.conflicts[key];
-      fs16.rmSync(incomingDir(paths, key), { recursive: true, force: true });
+      fs17.rmSync(incomingDir(paths, key), { recursive: true, force: true });
     } else {
       const dir = incomingDir(paths, key);
-      fs16.rmSync(dir, { recursive: true, force: true });
-      fs16.mkdirSync(dir, { recursive: true });
+      fs17.rmSync(dir, { recursive: true, force: true });
+      fs17.mkdirSync(dir, { recursive: true });
       for (const [rel, file] of Object.entries(plan.remote.manifest))
         writeInside(dir, unitRelative(key, rel), blobs.get(file.hash));
       link.conflicts[key] = plan.remote.headRev;
@@ -3069,8 +3211,8 @@ async function pull(ctx, options) {
 }
 
 // src/cloud/push.ts
-import fs17 from "fs";
-import path17 from "path";
+import fs18 from "fs";
+import path18 from "path";
 function blockedReport(status, message) {
   return {
     unit: status.key,
@@ -3176,7 +3318,7 @@ async function push(ctx, options) {
   for (const key of toPush) {
     const s = status(key);
     if (s.conflictRev !== void 0) {
-      const dir = path17.relative(paths.root, incomingDir(paths, key));
+      const dir = path18.relative(paths.root, incomingDir(paths, key));
       blocked.push(
         blockedReport(s, `pull left the cloud version in ${dir}; merge it, then \`design push --resolved ${key}\``)
       );
@@ -3220,7 +3362,7 @@ async function push(ctx, options) {
   const files = /* @__PURE__ */ new Map();
   const addFiles = (manifest, dir) => {
     for (const [rel, entry] of Object.entries(manifest))
-      if (!files.has(entry.hash)) files.set(entry.hash, path17.join(dir, rel));
+      if (!files.has(entry.hash)) files.set(entry.hash, path18.join(dir, rel));
   };
   for (const key of pushing) {
     const id2 = unitCanvasId(key);
@@ -3252,7 +3394,7 @@ async function push(ctx, options) {
   if (missing.length) {
     const unknown = missing.find((hash) => !files.has(hash));
     if (unknown) throw new CliError(`The cloud asked for ${unknown.slice(0, 12)}, which is not part of this push`);
-    const bytes = missing.reduce((sum, hash) => sum + fs17.statSync(files.get(hash)).size, 0);
+    const bytes = missing.reduce((sum, hash) => sum + fs18.statSync(files.get(hash)).size, 0);
     const bar = ctx.progress();
     const started = Date.now();
     let sentFiles = 0;
@@ -3261,12 +3403,12 @@ async function push(ctx, options) {
     bar.update(line());
     await mapLimit(missing, TRANSFERS, async (hash) => {
       const file = files.get(hash);
-      const data = fs17.readFileSync(file);
+      const data = fs18.readFileSync(file);
       try {
         await client.putBlob(link.project, hash, data);
       } catch (error) {
         if (error instanceof CloudError && error.status === 413)
-          throw new CliError(`${path17.relative(process.cwd(), file)} (${megabytes(data.length)}): ${error.message}`);
+          throw new CliError(`${path18.relative(process.cwd(), file)} (${megabytes(data.length)}): ${error.message}`);
         throw error;
       }
       sentFiles++;
@@ -3288,7 +3430,7 @@ async function push(ctx, options) {
       url: webUrl(link, unit.key)
     });
   }
-  for (const key of resolved) fs17.rmSync(incomingDir(paths, key), { recursive: true, force: true });
+  for (const key of resolved) fs18.rmSync(incomingDir(paths, key), { recursive: true, force: true });
   writeLink(paths, link);
   report.units.sort((a, b) => byUnit(a.unit, b.unit));
   return report;
@@ -3299,7 +3441,7 @@ function refuseLegacyGo(paths, keys) {
   for (const key of keys) {
     if (!key.startsWith("canvas/")) continue;
     const id2 = key.slice("canvas/".length);
-    for (const file of canvasCodeFiles(path17.join(paths.canvases, id2), project.canvas(id2)?.screens ?? [])) {
+    for (const file of canvasCodeFiles(path18.join(paths.canvases, id2), project.canvas(id2)?.screens ?? [])) {
       for (const line of legacyGoLines(file)) hits.add(`${relToRoot(paths, file)}:${line}`);
     }
   }
@@ -3620,7 +3762,7 @@ async function runMe(paths, options) {
 }
 
 // src/capture/chrome.ts
-import fs18 from "fs";
+import fs19 from "fs";
 var CANDIDATES = {
   darwin: [
     "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
@@ -3644,8 +3786,8 @@ var CANDIDATES = {
 };
 function findChrome() {
   const configured = process.env.DESIGN_CHROME;
-  if (configured && fs18.existsSync(configured)) return configured;
-  for (const candidate of CANDIDATES[process.platform] ?? []) if (fs18.existsSync(candidate)) return candidate;
+  if (configured && fs19.existsSync(configured)) return configured;
+  for (const candidate of CANDIDATES[process.platform] ?? []) if (fs19.existsSync(candidate)) return candidate;
   return null;
 }
 async function launchChrome() {
@@ -3717,26 +3859,26 @@ async function openFrame(page, url, options = {}) {
 }
 
 // src/server/state.ts
-import fs19 from "fs";
-import path18 from "path";
-var stateFile = (paths) => path18.join(paths.cache, "server.json");
-var logFile = (paths) => path18.join(paths.cache, "server.log");
+import fs20 from "fs";
+import path19 from "path";
+var stateFile = (paths) => path19.join(paths.cache, "server.json");
+var logFile = (paths) => path19.join(paths.cache, "server.log");
 function readState(paths) {
   try {
-    return JSON.parse(fs19.readFileSync(stateFile(paths), "utf8"));
+    return JSON.parse(fs20.readFileSync(stateFile(paths), "utf8"));
   } catch {
     return null;
   }
 }
 function writeState(paths, state) {
-  fs19.mkdirSync(paths.cache, { recursive: true });
-  fs19.writeFileSync(stateFile(paths), `${JSON.stringify(state, null, 2)}
+  fs20.mkdirSync(paths.cache, { recursive: true });
+  fs20.writeFileSync(stateFile(paths), `${JSON.stringify(state, null, 2)}
 `);
 }
 function clearState(paths, pid) {
   const state = readState(paths);
   if (pid !== void 0 && state && state.pid !== pid) return;
-  fs19.rmSync(stateFile(paths), { force: true });
+  fs20.rmSync(stateFile(paths), { force: true });
 }
 function pidAlive(pid) {
   try {
@@ -3761,18 +3903,18 @@ async function liveServer(paths) {
 
 // src/cli/commands/preview.ts
 import { spawn } from "child_process";
-import fs23 from "fs";
+import fs24 from "fs";
 
 // src/server/index.ts
-import fs22 from "fs";
+import fs23 from "fs";
 import http from "http";
-import path21 from "path";
+import path22 from "path";
 import sirv from "sirv";
 import { createServer, searchForWorkspaceRoot } from "vite";
 
 // src/server/api.ts
-import fs20 from "fs";
-import path19 from "path";
+import fs21 from "fs";
+import path20 from "path";
 function sendJson(res, status, body) {
   res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
   res.end(JSON.stringify(body));
@@ -3823,17 +3965,34 @@ async function handleApi(ctx, req, res, url) {
   }
   if (route2 === "/source") {
     const rel = url.searchParams.get("path") ?? "";
-    const file = path19.resolve(project.paths.root, rel);
-    if (!rel || !isInside(project.paths.root, file) || !fs20.existsSync(file) || fs20.statSync(file).isDirectory()) {
+    const file = path20.resolve(project.paths.root, rel);
+    if (!rel || !isInside(project.paths.root, file) || !fs21.existsSync(file) || fs21.statSync(file).isDirectory()) {
       sendJson(res, 404, { error: "not found" });
       return true;
     }
-    if (fs20.statSync(file).size > 2 * 1024 * 1024) {
+    if (fs21.statSync(file).size > 2 * 1024 * 1024) {
       sendJson(res, 413, { error: "file too large to show" });
       return true;
     }
     res.writeHead(200, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
-    res.end(fs20.readFileSync(file, "utf8"));
+    res.end(fs21.readFileSync(file, "utf8"));
+    return true;
+  }
+  if (route2 === "/icon" && (method === "PUT" || method === "DELETE")) {
+    try {
+      const body = method === "PUT" ? await readBody(req, MAX_ICON_BYTES * 4) : null;
+      const problem = body ? iconProblem(body) : null;
+      if (problem) {
+        sendJson(res, 400, { error: problem });
+        return true;
+      }
+      writeIcon(project.paths, body);
+      project.invalidateSystem();
+      events.send({ type: "project" });
+      sendJson(res, 200, { icon: project.iconUrl() });
+    } catch (error) {
+      sendJson(res, 400, { error: error.message });
+    }
     return true;
   }
   const snapshotPost = /^\/snapshots\/([^/]+)\/([^/]+)$/.exec(route2);
@@ -3863,7 +4022,7 @@ async function handleApi(ctx, req, res, url) {
       return true;
     }
     res.writeHead(200, { "content-type": "image/png", "cache-control": "public, max-age=31536000, immutable" });
-    fs20.createReadStream(file).pipe(res);
+    fs21.createReadStream(file).pipe(res);
     return true;
   }
   return false;
@@ -3903,8 +4062,8 @@ var EventHub = class {
 };
 
 // src/server/snapshots.ts
-import fs21 from "fs";
-import path20 from "path";
+import fs22 from "fs";
+import path21 from "path";
 var SAFE = /^@?[a-z0-9][a-z0-9_-]*$/i;
 function isSafeSegment(value) {
   return SAFE.test(value);
@@ -3918,14 +4077,14 @@ var SnapshotStore = class {
   urlBase;
   meta = /* @__PURE__ */ new Map();
   metaFile(canvas) {
-    return path20.join(this.dir, canvas, "meta.json");
+    return path21.join(this.dir, canvas, "meta.json");
   }
   load(canvas) {
     const cached = this.meta.get(canvas);
     if (cached) return cached;
     let data = {};
     try {
-      data = JSON.parse(fs21.readFileSync(this.metaFile(canvas), "utf8"));
+      data = JSON.parse(fs22.readFileSync(this.metaFile(canvas), "utf8"));
     } catch {
     }
     this.meta.set(canvas, data);
@@ -3951,21 +4110,21 @@ var SnapshotStore = class {
   };
   save(canvas, id2, theme2, png, height) {
     if (!isSafeSegment(canvas) || !isSafeSegment(id2)) throw new Error("bad snapshot key");
-    const dir = path20.join(this.dir, canvas);
-    fs21.mkdirSync(dir, { recursive: true });
-    fs21.writeFileSync(path20.join(dir, `${id2}.${theme2}.png`), png);
+    const dir = path21.join(this.dir, canvas);
+    fs22.mkdirSync(dir, { recursive: true });
+    fs22.writeFileSync(path21.join(dir, `${id2}.${theme2}.png`), png);
     const data = this.load(canvas);
     const version = Date.now();
     data[id2] = { ...data[id2], [theme2]: version, ...height ? { height } : {} };
-    fs21.writeFileSync(this.metaFile(canvas), JSON.stringify(data));
+    fs22.writeFileSync(this.metaFile(canvas), JSON.stringify(data));
     return { url: this.url(canvas, id2, theme2, version) };
   }
   /** Absolute path of `<id>.<theme>.png`, or of its thumbnail for `<id>.<theme>.thumb.png` (made on first use); null when missing. */
   file(canvas, name) {
     const match = /^(@?[a-z0-9][a-z0-9_-]*)\.(light|dark)(\.thumb)?\.png$/i.exec(name);
     if (!isSafeSegment(canvas) || !match) return null;
-    const file = path20.join(this.dir, canvas, `${match[1]}.${match[2]}.png`);
-    if (!fs21.existsSync(file)) return null;
+    const file = path21.join(this.dir, canvas, `${match[1]}.${match[2]}.png`);
+    if (!fs22.existsSync(file)) return null;
     return match[3] ? ensureThumb(file) : file;
   }
 };
@@ -4004,16 +4163,16 @@ function notFoundPage(res, title, text2) {
 }
 async function startDevServer(options) {
   const paths = designPaths(options.root);
-  if (!fs22.existsSync(paths.design)) throw new Error(`No .design folder in ${options.root}; run \`design init\``);
-  fs22.mkdirSync(paths.cache, { recursive: true });
+  if (!fs23.existsSync(paths.design)) throw new Error(`No .design folder in ${options.root}; run \`design init\``);
+  fs23.mkdirSync(paths.cache, { recursive: true });
   const snapshots = new SnapshotStore(paths.snapshots);
   const project = new DesignProject(paths, DEV_URLS, snapshots.lookup);
   const entries = new Entries(project);
   entries.sync();
-  const links = linkShippedPackages(paths);
+  const links = linkShippedPackages(paths, project.appDir());
   const events = new EventHub();
   const httpServer = http.createServer();
-  dropStaleDepCache(paths);
+  dropStaleDepCache(paths, project.appDir());
   const base = baseConfig(project);
   const vite = await createServer({
     ...base,
@@ -4031,8 +4190,8 @@ async function startDevServer(options) {
         // `.cache` is ours (server.log, snapshots, builds): a change there must not reload frames. The
         // generated entries are modules the frames load, so those stay watched.
         ignored: (file) => {
-          const rel = toPosix(path21.relative(paths.cache, file));
-          const inCache = rel !== "" && !rel.startsWith("..") && !path21.isAbsolute(rel);
+          const rel = toPosix(path22.relative(paths.cache, file));
+          const inCache = rel !== "" && !rel.startsWith("..") && !path22.isAbsolute(rel);
           return inCache && rel !== "entries" && !rel.startsWith("entries/");
         }
       },
@@ -4041,7 +4200,7 @@ async function startDevServer(options) {
       forwardConsole: false
     },
     optimizeDeps: {
-      entries: entries.files().map((file) => toPosix(path21.relative(paths.design, file)))
+      entries: entries.files().map((file) => toPosix(path22.relative(paths.design, file)))
     }
   });
   const publicDir = project.publicDir();
@@ -4053,16 +4212,16 @@ async function startDevServer(options) {
       return null;
     }
   };
-  const viewer = fs22.existsSync(PKG.viewer) ? sirv(PKG.viewer, { dev: true, etag: true }) : null;
-  const viewerIndex = path21.join(PKG.viewer, "index.html");
+  const viewer = fs23.existsSync(PKG.viewer) ? sirv(PKG.viewer, { dev: true, etag: true }) : null;
+  const viewerIndex = path22.join(PKG.viewer, "index.html");
   const serveViewerIndex = (res) => {
-    const html = fs22.readFileSync(viewerIndex, "utf8").replace(/<head>/i, '<head>\n<base href="/">');
+    const html = fs23.readFileSync(viewerIndex, "utf8").replace(/<head>/i, '<head>\n<base href="/">');
     res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
     res.end(html);
   };
   const ctx = { project, events, snapshots };
   const systemCssUrl = `/${relToDesign(paths, entries.systemCssFile())}`;
-  const bootUrl = `/${relToDesign(paths, path21.join(entries.dir, HTML_BOOT))}`;
+  const bootUrl = `/${relToDesign(paths, path22.join(entries.dir, HTML_BOOT))}`;
   const frameHead = (source, extra = {}) => {
     const canvasTheme = source.canvas === SYSTEM_CANVAS ? void 0 : project.canvas(source.canvas)?.doc.theme;
     return {
@@ -4083,7 +4242,7 @@ async function startDevServer(options) {
       notFoundPage(res, "Screen not found", `No screen "${id2}" in "${canvas}". Check canvas.json.`);
       return;
     }
-    if (!fs22.existsSync(entries.entryFile(source))) entries.sync();
+    if (!fs23.existsSync(entries.entryFile(source))) entries.sync();
     const entryUrl = `/${relToDesign(paths, entries.entryFile(source))}`;
     const html = await vite.transformIndexHtml(url2.pathname + url2.search, moduleShell(frameHead(source), entryUrl));
     res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
@@ -4092,8 +4251,8 @@ async function startDevServer(options) {
   };
   const serveHtmlScreen = async (res, url2) => {
     const rel = decodeURIComponent(url2.pathname.slice("/_fs/".length));
-    const file = path21.resolve(paths.design, rel);
-    if (!isInside(paths.design, file) || !fs22.existsSync(file)) {
+    const file = path22.resolve(paths.design, rel);
+    if (!isInside(paths.design, file) || !fs23.existsSync(file)) {
       notFoundPage(res, "Screen not found", `No file .design/${rel}`);
       return;
     }
@@ -4103,13 +4262,13 @@ async function startDevServer(options) {
       key: `${canvas}/${id2}`,
       canvas,
       id: id2,
-      title: path21.basename(file),
+      title: path22.basename(file),
       file,
       format: "html",
       props: {},
       system: true
     };
-    const raw = fs22.readFileSync(file, "utf8");
+    const raw = fs23.readFileSync(file, "utf8");
     const withSystem = source.system && !optsOutOfSystem(raw);
     const html = injectIntoHtml(
       raw,
@@ -4142,7 +4301,7 @@ async function startDevServer(options) {
       }
       if (url2.pathname.startsWith("/_fs/")) {
         const rel = publicRel(url2.pathname.slice("/_fs/".length));
-        if (publicDir && rel !== null && !project.isPublicFile(rel) && fs22.existsSync(path21.join(publicDir, rel))) {
+        if (publicDir && rel !== null && !project.isPublicFile(rel) && fs23.existsSync(path22.join(publicDir, rel))) {
           notFoundPage(res, "Not found", url2.pathname);
           return;
         }
@@ -4154,7 +4313,7 @@ async function startDevServer(options) {
           const rel = publicRel(url2.pathname.slice(1));
           if (servePublic && rel !== null && project.isPublicFile(rel))
             servePublic(req, res, () => notFoundPage(res, "Not found", url2.pathname));
-          else if (path21.extname(url2.pathname)) notFoundPage(res, "Not found", url2.pathname);
+          else if (path22.extname(url2.pathname)) notFoundPage(res, "Not found", url2.pathname);
           else serveViewerIndex(res);
         };
         if (url2.pathname === "/" || url2.pathname === "/index.html") serveViewerIndex(res);
@@ -4182,7 +4341,7 @@ async function startDevServer(options) {
   };
   vite.watcher.on("all", (event, file) => {
     if (publicDir && isInside(publicDir, file)) project.invalidatePublic();
-    const rel = toPosix(path21.relative(paths.design, file));
+    const rel = toPosix(path22.relative(paths.design, file));
     if (rel.startsWith("..") || rel.startsWith(".cache/") || rel.startsWith("node_modules/")) return;
     if (rel === "design.json") {
       queue("config", () => {
@@ -4290,15 +4449,15 @@ async function ensureServer(paths, options) {
   if (stale)
     print(dim(`Restarting the preview server: it runs foss-design ${live2.version}, this is ${packageVersion()}.`));
   if (live2) await stopServer(paths);
-  fs23.mkdirSync(paths.cache, { recursive: true });
-  const log = fs23.openSync(logFile(paths), "w");
+  fs24.mkdirSync(paths.cache, { recursive: true });
+  const log = fs24.openSync(logFile(paths), "w");
   const args = [PKG.cli, "preview", "--foreground", "--root", paths.root];
   if (options.port) args.push("--port", String(options.port));
   const child = spawn(process.execPath, args, { detached: true, stdio: ["ignore", log, log], cwd: paths.root });
   child.unref();
   const state = await waitForServer(paths, 4e4);
   if (!state) {
-    const tail = fs23.existsSync(logFile(paths)) ? fs23.readFileSync(logFile(paths), "utf8").split("\n").slice(-25) : [];
+    const tail = fs24.existsSync(logFile(paths)) ? fs24.readFileSync(logFile(paths), "utf8").split("\n").slice(-25) : [];
     throw new CliError(`The preview server did not start.
 ${tail.join("\n")}`);
   }
@@ -4477,9 +4636,9 @@ function printLinkIssues(issues, project) {
 }
 
 // src/cli/commands/cloud.ts
-import fs24 from "fs";
+import fs25 from "fs";
 import os3 from "os";
-import path22 from "path";
+import path23 from "path";
 var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function runLogin() {
   const host = cloudHost();
@@ -4580,7 +4739,7 @@ async function runLink(paths, wanted, options) {
     print(`${dim("Already linked to")} ${project.name} ${dim(`(${project.id}, ${project.role})`)}`);
   } else {
     writeLink(paths, { host, project: project.id, units: {}, conflicts: {} });
-    fs24.rmSync(path22.join(cloudCache(paths), "incoming"), { recursive: true, force: true });
+    fs25.rmSync(path23.join(cloudCache(paths), "incoming"), { recursive: true, force: true });
     const replaced = current ? dim(` (replacing the link to ${current.project})`) : "";
     print(`${green("linked")} .design \u2192 ${bold(project.name)} ${dim(`(${project.id}, ${project.role})`)}${replaced}`);
   }
@@ -4604,13 +4763,41 @@ async function runLink(paths, wanted, options) {
   else if (remote) print(dim("Everything is in sync."));
 }
 
-// src/cli/commands/import.ts
+// src/cli/commands/icon.ts
 import fs26 from "fs";
 import path24 from "path";
+function runIcon(paths, file, options) {
+  if (options.remove) {
+    const had = iconFile(paths);
+    writeIcon(paths, null);
+    print(had ? `${green("Removed")} ${path24.relative(process.cwd(), had)}` : "The project has no icon.");
+    return;
+  }
+  if (!file) {
+    const current = iconFile(paths);
+    if (!current) return print("The project has no icon. Set one with `design icon <file.svg|png|webp>`.");
+    return print(`${path24.relative(process.cwd(), current)} ${dim(`${Math.ceil(fs26.statSync(current).size / 1024)} KB`)}`);
+  }
+  let data;
+  try {
+    data = fs26.readFileSync(file);
+  } catch {
+    throw new CliError(`No file ${file}`);
+  }
+  const problem = iconProblem(data, path24.extname(file).slice(1).toLowerCase() || void 0);
+  if (problem) throw new CliError(`${file}: ${problem}`);
+  const written = writeIcon(paths, data);
+  print(`${green("Set")} the project icon: ${path24.relative(process.cwd(), written)}`);
+  print(dim("It syncs with the design system unit: `design push` takes it to the cloud."));
+}
+
+// src/cli/commands/import.ts
+import fs28 from "fs";
+import path26 from "path";
 
 // src/import/claude-design.ts
-import fs25 from "fs";
-import path23 from "path";
+import fs27 from "fs";
+import path25 from "path";
 
 // src/import/markup.ts
 var VOID = /* @__PURE__ */ new Set([
@@ -5218,11 +5405,11 @@ function boardId(file, used) {
   return id2;
 }
 function importClaudeDesign(dir, options = {}) {
-  const canvasFile = path23.join(dir, "canvas.json");
-  if (!fs25.existsSync(canvasFile))
+  const canvasFile = path25.join(dir, "canvas.json");
+  if (!fs27.existsSync(canvasFile))
     throw new Error(`No canvas.json in ${dir}: point at the exported Claude Design project folder`);
-  const source = JSON.parse(fs25.readFileSync(canvasFile, "utf8"));
-  const templates = fs25.readdirSync(dir).filter((file) => file.endsWith(EXT));
+  const source = JSON.parse(fs27.readFileSync(canvasFile, "utf8"));
+  const templates = fs27.readdirSync(dir).filter((file) => file.endsWith(EXT));
   if (!templates.length) throw new Error(`No ${EXT} files in ${dir}`);
   const known = new Set(templates.map((file) => file.slice(0, -EXT.length)));
   const warnings = /* @__PURE__ */ new Map();
@@ -5249,7 +5436,7 @@ function importClaudeDesign(dir, options = {}) {
     try {
       files.set(
         `${name}.jsx`,
-        convertFile(name, fs25.readFileSync(path23.join(dir, file), "utf8"), { known, routes, warn: warn2 })
+        convertFile(name, fs27.readFileSync(path25.join(dir, file), "utf8"), { known, routes, warn: warn2 })
       );
     } catch (error) {
       warn2(`could not be converted: ${error.message}`);
@@ -5297,7 +5484,7 @@ function importClaudeDesign(dir, options = {}) {
     screens++;
   }
   const canvas = {
-    title: options.title ?? source.title ?? path23.basename(path23.resolve(dir)),
+    title: options.title ?? source.title ?? path25.basename(path25.resolve(dir)),
     description: "Imported from Claude Design.",
     // The templates bring their own styles; the design system's reset would restyle them.
     system: false,
@@ -5309,21 +5496,21 @@ function importClaudeDesign(dir, options = {}) {
 // src/cli/commands/import.ts
 var slug = (text2) => text2.normalize("NFKD").replace(/[^\w\s-]/g, "").trim().replace(/[\s_]+/g, "-").toLowerCase();
 function runImport(paths, from, options) {
-  const dir = path24.resolve(from);
-  if (!fs26.existsSync(dir) || !fs26.statSync(dir).isDirectory()) throw new CliError(`No folder ${from}`);
+  const dir = path26.resolve(from);
+  if (!fs28.existsSync(dir) || !fs28.statSync(dir).isDirectory()) throw new CliError(`No folder ${from}`);
   let result;
   try {
     result = importClaudeDesign(dir, { title: options.title });
   } catch (error) {
     throw new CliError(error.message);
   }
-  const id2 = options.canvas ?? (slug(String(result.canvas.title)) || slug(path24.basename(dir)) || "imported");
+  const id2 = options.canvas ?? (slug(String(result.canvas.title)) || slug(path26.basename(dir)) || "imported");
   if (!ID_PATTERN.test(id2)) throw new CliError(`"${id2}" is no canvas id; pass one with --canvas <id>`);
-  const out = path24.join(paths.canvases, id2);
-  if (fs26.existsSync(out)) throw new CliError(`.design/canvas/${id2} exists; pick another id with --canvas <id>`);
-  fs26.mkdirSync(path24.join(out, "screens"), { recursive: true });
-  for (const [name, content] of result.files) fs26.writeFileSync(path24.join(out, "screens", name), content);
-  fs26.writeFileSync(path24.join(out, "canvas.json"), `${JSON.stringify(result.canvas, null, 2)}
+  const out = path26.join(paths.canvases, id2);
+  if (fs28.existsSync(out)) throw new CliError(`.design/canvas/${id2} exists; pick another id with --canvas <id>`);
+  fs28.mkdirSync(path26.join(out, "screens"), { recursive: true });
+  for (const [name, content] of result.files) fs28.writeFileSync(path26.join(out, "screens", name), content);
+  fs28.writeFileSync(path26.join(out, "canvas.json"), `${JSON.stringify(result.canvas, null, 2)}
 `);
   print(`${green("Imported")} ${bold(String(result.canvas.title))} \u2192 .design/canvas/${id2}`);
   print(
@@ -5342,8 +5529,8 @@ function runImport(paths, from, options) {
 }
 
 // src/cli/commands/scaffold.ts
-import fs27 from "fs";
-import path25 from "path";
+import fs29 from "fs";
+import path27 from "path";
 
 // src/cli/templates.ts
 var TOKENS_CSS = `/*
@@ -5554,89 +5741,91 @@ function mainScreen(canvasId) {
 
 // src/cli/commands/scaffold.ts
 function write(file, content, root) {
-  if (fs27.existsSync(file)) {
-    print(`  ${dim("exists ")} ${path25.relative(root, file)}`);
+  if (fs29.existsSync(file)) {
+    print(`  ${dim("exists ")} ${path27.relative(root, file)}`);
     return false;
   }
-  fs27.mkdirSync(path25.dirname(file), { recursive: true });
-  fs27.writeFileSync(file, content);
-  print(`  ${green("created")} ${path25.relative(root, file)}`);
+  fs29.mkdirSync(path27.dirname(file), { recursive: true });
+  fs29.writeFileSync(file, content);
+  print(`  ${green("created")} ${path27.relative(root, file)}`);
   return true;
 }
 function ensureGitignored(root) {
-  const file = path25.join(root, ".gitignore");
-  const current = fs27.existsSync(file) ? fs27.readFileSync(file, "utf8") : "";
+  const file = path27.join(root, ".gitignore");
+  const current = fs29.existsSync(file) ? fs29.readFileSync(file, "utf8") : "";
   const covered = current.split(/\r?\n/).map((line) => line.trim()).some((line) => [".design", ".design/", "/.design", "/.design/", ".design/*"].includes(line));
   if (covered) return "present";
   const prefix = current && !current.endsWith("\n") ? "\n" : "";
-  fs27.writeFileSync(file, `${current}${prefix}${current ? "\n" : ""}# Design canvases (foss-design)
+  fs29.writeFileSync(file, `${current}${prefix}${current ? "\n" : ""}# Design canvases (foss-design)
 .design/
 `);
   return "added";
 }
 function projectName(root) {
   try {
-    const manifest = JSON.parse(fs27.readFileSync(path25.join(root, "package.json"), "utf8"));
+    const manifest = JSON.parse(fs29.readFileSync(path27.join(root, "package.json"), "utf8"));
     if (typeof manifest.name === "string" && manifest.name) return manifest.name;
   } catch {
   }
-  return path25.basename(root);
+  return path27.basename(root);
 }
 function runInit(root, options) {
   const paths = designPaths(root);
   print(`Setting up ${DESIGN_DIR} in ${root}`);
   write(paths.config, `${JSON.stringify({ name: options.name ?? projectName(root) }, null, 2)}
 `, root);
-  fs27.mkdirSync(paths.canvases, { recursive: true });
+  fs29.mkdirSync(paths.canvases, { recursive: true });
   if (options.gitignore) {
     const result = ensureGitignored(root);
     print(`  ${result === "added" ? green("ignored") : dim("ignored")} .design/ in .gitignore`);
   }
   print();
-  print("Next: `design system init` for a design system, `design new <canvas>` for a canvas, `design preview` to look.");
+  print(
+    "Next: `design system init` for a design system, `design new <canvas>` for a canvas, `design icon <file.svg>` for the project icon, `design preview` to look."
+  );
 }
 function runSystemInit(root, options) {
   const paths = designPaths(root);
   let base = projectName(root);
   try {
-    base = JSON.parse(fs27.readFileSync(paths.config, "utf8")).name || base;
+    base = JSON.parse(fs29.readFileSync(paths.config, "utf8")).name || base;
   } catch {
   }
   const name = options.name ?? `${base} design system`;
-  print(`Scaffolding the design system in ${path25.relative(root, paths.system)}`);
-  write(path25.join(paths.system, "system.json"), `${JSON.stringify({ name }, null, 2)}
+  print(`Scaffolding the design system in ${path27.relative(root, paths.system)}`);
+  write(path27.join(paths.system, "system.json"), `${JSON.stringify({ name }, null, 2)}
 `, root);
-  write(path25.join(paths.system, "tokens.css"), TOKENS_CSS, root);
+  write(path27.join(paths.system, "tokens.css"), TOKENS_CSS, root);
   if (!options.empty) {
-    write(path25.join(paths.system, "guidelines", "01-overview.md"), OVERVIEW_MD, root);
-    write(path25.join(paths.system, "components", "button.tsx"), BUTTON_TSX, root);
-    write(path25.join(paths.system, "specimens", "button.tsx"), BUTTON_SPECIMEN_TSX, root);
+    write(path27.join(paths.system, "guidelines", "01-overview.md"), OVERVIEW_MD, root);
+    write(path27.join(paths.system, "components", "button.tsx"), BUTTON_TSX, root);
+    write(path27.join(paths.system, "specimens", "button.tsx"), BUTTON_SPECIMEN_TSX, root);
   }
 }
 function runNew(root, id2, options) {
   if (!ID_PATTERN.test(id2)) throw new CliError(`"${id2}" is not a valid canvas id: use letters, digits, "-" and "_"`);
   const paths = designPaths(root);
-  const dir = path25.join(paths.canvases, id2);
-  if (fs27.existsSync(path25.join(dir, "canvas.json"))) throw new CliError(`Canvas "${id2}" already exists in ${dir}`);
+  const dir = path27.join(paths.canvases, id2);
+  if (fs29.existsSync(path27.join(dir, "canvas.json"))) throw new CliError(`Canvas "${id2}" already exists in ${dir}`);
   print(`Creating canvas "${id2}"`);
   const title = options.title ?? titleize(id2);
   if (options.empty) {
     write(
-      path25.join(dir, "canvas.json"),
+      path27.join(dir, "canvas.json"),
       `${JSON.stringify({ title, pages: [{ id: "main", title: "Main", sections: [] }] }, null, 2)}
 `,
       root
     );
-    fs27.mkdirSync(path25.join(dir, "screens"), { recursive: true });
+    fs29.mkdirSync(path27.join(dir, "screens"), { recursive: true });
   } else {
-    write(path25.join(dir, "canvas.json"), canvasJson(title), root);
-    write(path25.join(dir, "screens", "Main.tsx"), mainScreen(id2), root);
+    write(path27.join(dir, "canvas.json"), canvasJson(title), root);
+    write(path27.join(dir, "screens", "Main.tsx"), mainScreen(id2), root);
   }
 }
 
 // src/cli/commands/shot.ts
-import fs28 from "fs";
-import path26 from "path";
+import fs30 from "fs";
+import path28 from "path";
 var OVERVIEW_TIMEOUT = 9e4;
 async function runShot(paths, target, options) {
   const [canvasId = "", screenId] = target.split("/");
@@ -5652,15 +5841,15 @@ async function runShot(paths, target, options) {
     throw new CliError(`No page "${options.page}" in "${canvasId}". Pages: ${doc.pages.map((p) => p.id).join(", ")}`);
   }
   const theme2 = options.theme ?? doc.theme ?? "light";
-  const outBase = path26.resolve(options.out ?? paths.shots);
-  const outDir = path26.join(outBase, canvasId);
-  fs28.mkdirSync(outDir, { recursive: true });
+  const outBase = path28.resolve(options.out ?? paths.shots);
+  const outDir = path28.join(outBase, canvasId);
+  fs30.mkdirSync(outDir, { recursive: true });
   const base = await serverBase(paths);
   const browser = await launchChrome();
   let failed = false;
   try {
     if (options.overview) {
-      if (!fs28.existsSync(PKG.viewer)) throw new CliError("The viewer is not built, so there is no canvas to shoot.");
+      if (!fs30.existsSync(PKG.viewer)) throw new CliError("The viewer is not built, so there is no canvas to shoot.");
       const pages = options.page ? [options.page] : screenId ? doc.pages.filter((page) => page.sections.some((section) => section.items.some((item) => item.id === screenId))).map((page) => page.id) : doc.pages.map((page) => page.id);
       for (const pageId of pages) {
         const page = await browser.newPage({ viewport: { width: 1920, height: 1200 } });
@@ -5676,7 +5865,7 @@ async function runShot(paths, target, options) {
           warn(`page "${pageId}": not every frame reported ready within ${OVERVIEW_TIMEOUT / 1e3}s; shooting anyway`);
         }
         await page.waitForTimeout(400);
-        const file = path26.join(outDir, `${pageId}.overview.png`);
+        const file = path28.join(outDir, `${pageId}.overview.png`);
         await page.screenshot({ path: file });
         await page.close();
         print(file);
@@ -5705,7 +5894,7 @@ async function shootFrames(browser, jobs, outDir) {
   let failed = false;
   const results = await mapLimit(jobs, 4, async (job) => {
     const page = await browser.newPage({ viewport: { width: job.width, height: job.height } });
-    const file = path26.join(outDir, `${job.id}.${job.theme}.png`);
+    const file = path28.join(outDir, `${job.id}.${job.theme}.png`);
     try {
       const report = await openFrame(page, job.url, { waitForReady: job.waitForReady });
       await page.screenshot({ path: file, fullPage: job.fullPage });
@@ -5737,8 +5926,8 @@ async function shootSystem(paths, project, id2, options) {
   if (id2 && !all.some((job) => job.id === id2)) {
     throw new CliError(`No specimen "${id2}" in the design system. Specimens: ${all.map((job) => job.id).join(", ")}`);
   }
-  const outDir = path26.join(path26.resolve(options.out ?? paths.shots), SYSTEM_CANVAS);
-  fs28.mkdirSync(outDir, { recursive: true });
+  const outDir = path28.join(path28.resolve(options.out ?? paths.shots), SYSTEM_CANVAS);
+  fs30.mkdirSync(outDir, { recursive: true });
   const base = await serverBase(paths);
   const jobs = systemFrames(system.doc, base, theme2).filter((job) => !id2 || job.id === id2);
   const browser = await launchChrome();
@@ -5750,7 +5939,7 @@ async function shootSystem(paths, project, id2, options) {
 }
 
 // src/cli/commands/cloud-status.ts
-import path27 from "path";
+import path29 from "path";
 var STATE_TEXT = {
   in_sync: green,
   local_changes: yellow,
@@ -5773,7 +5962,7 @@ function detail(paths, status) {
   if (status.state === "remote_ahead" && !status.local && !status.baseRev) parts.push("not pulled yet");
   if (status.state === "remote_ahead" && status.changed.length && !status.deletedRemotely)
     parts.push(`${plural(status.changed.length, "file")} changed here; the cloud only rebuilt it`);
-  if (status.conflictRev !== void 0) parts.push(`merge ${path27.relative(paths.root, incomingDir(paths, status.key))}`);
+  if (status.conflictRev !== void 0) parts.push(`merge ${path29.relative(paths.root, incomingDir(paths, status.key))}`);
   return parts.join(" \xB7 ");
 }
 async function printCloudStatus(paths, label) {
@@ -5888,6 +6077,9 @@ ${bold("Project")}
   init [--name <name>] [--no-gitignore]      Create .design and add it to .gitignore
   system init [--name <name>] [--empty]      Scaffold .design/system: tokens, a guideline, a component
   new <canvas> [--title <title>] [--empty]   Scaffold .design/canvas/<canvas>
+  icon [<file>] [--remove]                   Show, set or remove the project icon: an SVG, PNG or WebP of
+                                             at most 256 KB, kept as .design/system/icon.* and pushed
+                                             with the design system
   import <folder> [--canvas <id>]            Turn an exported Claude Design project (canvas.json and
          [--title <title>]                   *.dc.html) into a canvas of React screens, once
   canvases [--json]                          Every canvas: pages and screens; with a cloud link also its
@@ -5949,7 +6141,7 @@ ${bold("Environment")}
   FOSS_DESIGN_CLOUD  Cloud to sign in and link to (default https://app.fossdesign.dev)
 `;
 function projectPaths(rootOption, requireDesign = true) {
-  const found = rootOption ? path28.resolve(rootOption) : findProjectRoot();
+  const found = rootOption ? path30.resolve(rootOption) : findProjectRoot();
   if (!found) {
     if (!requireDesign) return designPaths(process.cwd());
     throw new CliError("No .design folder here or above. Run `design init` in the project root first.");
@@ -5967,6 +6159,7 @@ async function main(argv) {
       name: { type: "string" },
       title: { type: "string" },
       canvas: { type: "string" },
+      remove: { type: "boolean" },
       "no-gitignore": { type: "boolean" },
       empty: { type: "boolean" },
       open: { type: "boolean" },
@@ -5996,7 +6189,7 @@ async function main(argv) {
   if (values.theme && !theme2) throw new CliError("--theme is light or dark");
   switch (command) {
     case "init":
-      return runInit(values.root ? path28.resolve(values.root) : process.cwd(), {
+      return runInit(values.root ? path30.resolve(values.root) : process.cwd(), {
         name: values.name,
         gitignore: !values["no-gitignore"]
       });
@@ -6008,6 +6201,8 @@ async function main(argv) {
       if (!rest[0]) throw new CliError("Usage: design new <canvas> [--title <title>]");
       return runNew(projectPaths(values.root).root, rest[0], { title: values.title, empty: !!values.empty });
     }
+    case "icon":
+      return runIcon(projectPaths(values.root), rest[0], { remove: !!values.remove });
     case "import": {
       if (!rest[0]) throw new CliError("Usage: design import <folder> [--canvas <id>] [--title <title>]");
       return runImport(projectPaths(values.root), rest[0], { canvas: values.canvas, title: values.title });