foss-design 0.9.5 → 0.9.6

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import path34 from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import fs37 from "fs";
+import path35 from "path";
 import { parseArgs } from "util";
 
 // src/core/paths.ts
@@ -346,8 +348,8 @@ function routeError(pattern) {
   }
   return null;
 }
-function split(path35) {
-  return path35.split("/").filter(Boolean);
+function split(path36) {
+  return path36.split("/").filter(Boolean);
 }
 function compileRoute(pattern) {
   return {
@@ -366,8 +368,8 @@ function decode2(part) {
     return part;
   }
 }
-function scoreRoute(route2, path35) {
-  const parts = split(path35.split(/[?#]/)[0] ?? "").map(decode2);
+function scoreRoute(route2, path36) {
+  const parts = split(path36.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 +387,11 @@ function scoreRoute(route2, path35) {
   };
   return walk2(0, 0);
 }
-function matchRoute(entries, path35) {
+function matchRoute(entries, path36) {
   let best = null;
   for (const entry of entries) {
     for (const route2 of entry.routes) {
-      const score = scoreRoute(route2, path35);
+      const score = scoreRoute(route2, path36);
       if (score !== null && (!best || score > best.score)) best = { score, value: entry.value };
     }
   }
@@ -516,9 +518,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, path35) {
+function formatPath(base, path36) {
   let out = base;
-  for (const part of path35) out += typeof part === "number" ? `[${part}]` : out ? `.${String(part)}` : String(part);
+  for (const part of path36) out += typeof part === "number" ? `[${part}]` : out ? `.${String(part)}` : String(part);
   return out;
 }
 function describeZodError(error, base = "") {
@@ -2632,7 +2634,7 @@ var CloudClient = class {
   }
   host;
   token;
-  async send(method, path35, init) {
+  async send(method, path36, init) {
     const headers = {
       "User-Agent": `foss-design/${packageVersion()} (${os.platform()})`,
       Accept: "application/json"
@@ -2640,7 +2642,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${path35}`, {
+      return await fetch(`${this.host}/api${path36}`, {
         method,
         headers,
         body: init.body,
@@ -2661,8 +2663,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, path35, body) {
-    const response = await this.send(method, path35, {
+  async request(method, path36, body) {
+    const response = await this.send(method, path36, {
       body: body === void 0 ? void 0 : JSON.stringify(body),
       type: body === void 0 ? void 0 : "application/json",
       timeout: JSON_TIMEOUT
@@ -2674,7 +2676,7 @@ var CloudClient = class {
     try {
       return JSON.parse(text2);
     } catch {
-      throw new CloudError(`${this.host} answered ${method} ${path35} with something other than JSON`, 0, "bad_response");
+      throw new CloudError(`${this.host} answered ${method} ${path36} with something other than JSON`, 0, "bad_response");
     }
   }
   /** POST /device/code. */
@@ -3273,51 +3275,84 @@ async function mapLimit(items, limit, fn) {
 
 // src/capture/cover.ts
 var SNAPSHOT_WIDTH = 900;
-async function refreshCovers(paths, canvasIds, base) {
+var TABS = 4;
+var THEMES2 = ["light", "dark"];
+function staleSnapshots(paths, canvasIds, filter = {}) {
   const store = new SnapshotStore(paths.snapshots);
   const project = new DesignProject(paths, DEV_URLS, store.lookup);
   const stale = [];
   for (const id2 of canvasIds) {
     const canvas = project.canvas(id2);
-    if (!canvas || canvas.doc.cover && "url" in canvas.doc.cover) continue;
-    const screen = canvas.doc.cover?.screen ?? canvas.screens[0]?.id;
-    const source = canvas.screens.find((item) => item.id === screen);
-    if (!screen || !source || !fs19.existsSync(source.file)) continue;
-    const taken = store.version(id2, screen, "light");
-    if (!taken || taken < fs19.statSync(source.file).mtimeMs) stale.push({ canvas: id2, screen });
-  }
-  if (!stale.length) return [];
-  if (!findChrome()) return ["No Chrome here, so canvas covers keep their last snapshot."];
+    if (!canvas) continue;
+    const inLight = canvasFrames(canvas.doc, "", "light", { page: filter.page, includeUrls: false });
+    const inDark = new Map(
+      canvasFrames(canvas.doc, "", "dark", { page: filter.page, includeUrls: false }).map((job) => [job.id, job.theme])
+    );
+    const files = new Map(canvas.screens.map((screen) => [screen.id, screen.file]));
+    for (const job of inLight) {
+      if (filter.screens && !filter.screens.has(job.id)) continue;
+      const file = files.get(job.id);
+      if (!file || !fs19.existsSync(file)) continue;
+      const changed = fs19.statSync(file).mtimeMs;
+      const pinned = inDark.get(job.id) === job.theme;
+      const themes = pinned ? [job.theme] : THEMES2;
+      const screen = { id: job.id };
+      for (const theme2 of themes) {
+        const taken = store.version(id2, screen.id, theme2);
+        if (!taken || taken < changed) stale.push({ canvas: id2, screen: screen.id, theme: theme2 });
+      }
+    }
+  }
+  return stale;
+}
+async function takeSnapshots(paths, targets, base, progress2) {
+  if (!targets.length) return [];
+  if (!findChrome()) return ["No Chrome here, so screens keep the snapshots they have."];
+  const store = new SnapshotStore(paths.snapshots);
+  const project = new DesignProject(paths, DEV_URLS, store.lookup);
   const url = await base();
   const browser = await launchChrome();
-  const lines = [];
+  const failed = [];
+  const started = Date.now();
+  let done = 0;
+  const line = () => `Snapshots ${done}/${targets.length} (both themes, as the viewer and the cloud show them)`;
+  progress2.update(line());
   try {
-    for (const { canvas, screen } of stale) {
-      const doc = project.canvas(canvas).doc;
-      const job = canvasFrames(doc, url, "light", { id: screen })[0];
-      if (!job) continue;
-      const page = await browser.newPage({
-        viewport: { width: job.width, height: job.height },
-        deviceScaleFactor: Math.min(1, SNAPSHOT_WIDTH / job.width)
-      });
-      try {
-        const report = await openFrame(page, job.url, { waitForReady: job.waitForReady });
-        if (!report.ready) {
-          lines.push(`${canvas}: ${screen} did not finish rendering, so its cover keeps the last snapshot`);
-          continue;
-        }
-        const png = await page.screenshot({ fullPage: job.fullPage });
-        const height = job.fullPage ? await page.evaluate(() => document.documentElement.scrollHeight) : void 0;
-        store.save(canvas, screen, "light", png, height);
-      } finally {
-        await page.close().catch(() => {
+    await mapLimit([...targets], TABS, async ({ canvas, screen, theme: theme2 }) => {
+      const job = canvasFrames(project.canvas(canvas).doc, url, theme2, { id: screen })[0];
+      if (job) {
+        const page = await browser.newPage({
+          viewport: { width: job.width, height: job.height },
+          deviceScaleFactor: Math.min(1, SNAPSHOT_WIDTH / job.width),
+          colorScheme: theme2
         });
+        try {
+          const report = await openFrame(page, job.url, { waitForReady: job.waitForReady });
+          if (report.ready) {
+            const png = await page.screenshot({ fullPage: job.fullPage });
+            const height = job.fullPage ? await page.evaluate(() => document.documentElement.scrollHeight) : void 0;
+            store.save(canvas, screen, theme2, png, height);
+          } else failed.push(`${canvas}/${screen} (${theme2})`);
+        } catch {
+          failed.push(`${canvas}/${screen} (${theme2})`);
+        } finally {
+          await page.close().catch(() => {
+          });
+        }
       }
-    }
+      done++;
+      progress2.update(line());
+    });
   } finally {
     await browser.close();
   }
-  return lines;
+  const seconds2 = Math.round((Date.now() - started) / 1e3);
+  progress2.done(`Took ${targets.length - failed.length} snapshot${targets.length === 1 ? "" : "s"} in ${seconds2}s`);
+  if (!failed.length) return [];
+  const shown = failed.slice(0, 5).join(", ");
+  return [
+    `${failed.length} screen${failed.length === 1 ? "" : "s"} did not finish rendering, so they keep their last snapshot: ${shown}${failed.length > 5 ? ", \u2026" : ""}. \`design check --render\` says why.`
+  ];
 }
 
 // src/cloud/pull.ts
@@ -3975,7 +4010,18 @@ async function push(ctx, options) {
     bar.done(`Uploaded ${plural(missing.length, "file")} (${megabytes(bytes)}) in ${seconds(started)}`);
   }
   log(`Pushing ${plural(units.length, "unit")}\u2026`);
-  const revs2 = await client.push(link.project, units);
+  let revs2;
+  try {
+    revs2 = await client.push(link.project, units);
+  } catch (error) {
+    if (!(error instanceof CloudError) || error.status !== 409 || error.error !== "conflict") throw error;
+    report.ok = false;
+    report.error = {
+      code: "pull_first",
+      message: "Nothing was pushed: someone pushed first. Run `design pull`, then push again."
+    };
+    return report;
+  }
   for (const unit of units) {
     const rev = revs2.get(unit.key) ?? unit.baseRev + 1;
     link.units[unit.key] = { rev, files: hashes(unit.source) };
@@ -4174,6 +4220,7 @@ var EventHub = class {
 
 // src/server/state.ts
 import fs26 from "fs";
+import os3 from "os";
 import path24 from "path";
 var stateFile2 = (paths) => path24.join(paths.cache, "server.json");
 var logFile = (paths) => path24.join(paths.cache, "server.log");
@@ -4184,16 +4231,71 @@ function readState(paths) {
     return null;
   }
 }
+function registryDir() {
+  const base = process.platform === "win32" ? process.env.LOCALAPPDATA || process.env.APPDATA || path24.join(os3.homedir(), "AppData", "Local") : process.env.XDG_CACHE_HOME || path24.join(os3.homedir(), ".cache");
+  return path24.join(base, "foss-design", "previews");
+}
+var entryFile = (pid) => path24.join(registryDir(), `${pid}.json`);
 function writeState(paths, state) {
   fs26.mkdirSync(paths.cache, { recursive: true });
   fs26.writeFileSync(stateFile2(paths), `${JSON.stringify(state, null, 2)}
 `);
+  try {
+    fs26.mkdirSync(registryDir(), { recursive: true });
+    fs26.writeFileSync(entryFile(state.pid), `${JSON.stringify(state, null, 2)}
+`);
+  } catch {
+  }
 }
 function clearState(paths, pid) {
   const state = readState(paths);
+  fs26.rmSync(entryFile(pid ?? state?.pid ?? -1), { force: true });
   if (pid !== void 0 && state && state.pid !== pid) return;
   fs26.rmSync(stateFile2(paths), { force: true });
 }
+function listPreviews() {
+  let files = [];
+  try {
+    files = fs26.readdirSync(registryDir()).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const name of files) {
+    const file = path24.join(registryDir(), name);
+    let state = null;
+    try {
+      state = JSON.parse(fs26.readFileSync(file, "utf8"));
+    } catch {
+    }
+    if (!state?.pid || !pidAlive(state.pid)) {
+      fs26.rmSync(file, { force: true });
+      continue;
+    }
+    let recorded = null;
+    try {
+      recorded = JSON.parse(fs26.readFileSync(path24.join(state.root, ".design", ".cache", "server.json"), "utf8"));
+    } catch {
+    }
+    found.push({ ...state, tracked: recorded?.pid === state.pid });
+  }
+  return found.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
+async function stopPreview(entry) {
+  try {
+    process.kill(entry.pid, "SIGTERM");
+  } catch {
+  }
+  const until = Date.now() + 5e3;
+  while (Date.now() < until && pidAlive(entry.pid)) await new Promise((resolve) => setTimeout(resolve, 100));
+  fs26.rmSync(entryFile(entry.pid), { force: true });
+  const stateAt = path24.join(entry.root, ".design", ".cache", "server.json");
+  try {
+    if (JSON.parse(fs26.readFileSync(stateAt, "utf8")).pid === entry.pid)
+      fs26.rmSync(stateAt, { force: true });
+  } catch {
+  }
+}
 function pidAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -4487,7 +4589,7 @@ async function startDevServer(options) {
 // src/cli/commands/preview.ts
 function openBrowser(url) {
   const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url]] : ["xdg-open", [url]];
-  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
   child.on("error", () => {
   });
   child.unref();
@@ -4535,11 +4637,19 @@ 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);
+  const recorded = readState(paths);
+  if (recorded && pidAlive(recorded.pid)) await stopPreview(recorded);
+  for (const other of listPreviews()) if (other.root === paths.root) await stopPreview(other);
   fs28.mkdirSync(paths.cache, { recursive: true });
   const log = fs28.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 });
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", log, log],
+    cwd: paths.root
+  });
   child.unref();
   const state = await waitForServer(paths, 4e4);
   if (!state) {
@@ -4569,6 +4679,27 @@ async function runPreview(paths, options) {
 async function runStop(paths) {
   print(await stopServer(paths) ? "Stopped the preview server." : "No preview server is running for this project.");
 }
+var since = (iso) => {
+  const minutes = Math.max(0, Math.round((Date.now() - new Date(iso).getTime()) / 6e4));
+  return minutes < 60 ? `${minutes}m` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+};
+function runPreviews(options) {
+  const previews = listPreviews();
+  if (options.json) return print(JSON.stringify({ previews }, null, 2));
+  if (!previews.length) return print("No preview servers are running.");
+  for (const preview of previews) {
+    const orphan = preview.tracked ? "" : ` ${bold("orphan")} ${dim("(its project names another server)")}`;
+    print(`${preview.url}  ${preview.root}${orphan}`);
+    print(dim(`  foss-design ${preview.version} \xB7 pid ${preview.pid} \xB7 up ${since(preview.startedAt)}`));
+  }
+}
+async function runStopAll() {
+  const previews = listPreviews();
+  for (const preview of previews) await stopPreview(preview);
+  print(
+    previews.length ? `Stopped ${previews.length} preview server${previews.length === 1 ? "" : "s"}.` : "No preview servers are running."
+  );
+}
 
 // src/cli/commands/sync.ts
 var GOOD = /* @__PURE__ */ new Set(["pushed", "created", "updated", "deleted"]);
@@ -4649,11 +4780,19 @@ async function runSync(paths, command, json, run) {
   if (!report.ok && report.error) throw new CliError(report.error.message, 2);
 }
 function runPush(paths, units, options) {
-  const beforeBuild = (canvasIds) => refreshCovers(paths, canvasIds, async () => `http://127.0.0.1:${(await ensureServer(paths, {})).port}`);
   return runSync(paths, "push", options.json, async (ctx) => {
+    const beforeBuild = (canvasIds) => takeSnapshots(
+      paths,
+      staleSnapshots(paths, canvasIds),
+      async () => `http://127.0.0.1:${(await ensureServer(paths, {})).port}`,
+      ctx.progress()
+    );
     const first = await push(ctx, { units, resolved: options.resolved, beforeBuild });
     if (first.ok || first.error?.code !== "pull_first") return first;
-    ctx.log("The cloud is ahead: merging its changes first\u2026");
+    const raced = first.error.message.includes("someone pushed first");
+    ctx.log(
+      raced ? "Someone pushed while this push was uploading: merging their changes first\u2026" : "The cloud is ahead: merging its changes first\u2026"
+    );
     const pulled = await pull(ctx, { units: [], theirs: [] });
     if (!pulled.ok) {
       pulled.error = {
@@ -4665,7 +4804,7 @@ function runPush(paths, units, options) {
     ctx.link = readLink(paths);
     const second = await push(ctx, { units, resolved: [], beforeBuild });
     second.hints.unshift(
-      `Merged the cloud's changes first: ${pulled.units.filter((entry) => entry.action !== "up_to_date").map((entry) => `${entry.unit} (${entry.action.replaceAll("_", " ")})`).join(", ")}`
+      `${raced ? "Someone pushed while this push was uploading; merged" : "Merged"} the cloud's changes first: ${pulled.units.filter((entry) => entry.action !== "up_to_date").map((entry) => `${entry.unit} (${entry.action.replaceAll("_", " ")})`).join(", ")}`
     );
     return second;
   });
@@ -4896,6 +5035,10 @@ async function runMe(paths, options) {
 }
 
 // src/cli/commands/check.ts
+import fs29 from "fs";
+import http2 from "http";
+import path26 from "path";
+import sirv2 from "sirv";
 var plural2 = (count, word, many = `${word}s`) => `${count} ${count === 1 ? word : many}`;
 function printIssues(issues) {
   const byFile = /* @__PURE__ */ new Map();
@@ -4935,29 +5078,103 @@ async function renderFrames(jobs) {
     await browser.close();
   }
 }
-async function runCheck(paths, canvases, options) {
+async function runCheck(paths, targets, options) {
   const project = new DesignProject(paths, DEV_URLS);
   const known = project.canvasIds();
-  const unknown = canvases.filter((id2) => !known.includes(id2));
-  if (unknown.length) {
-    throw new CliError(
-      `No canvas ${unknown.map((id2) => `"${id2}"`).join(", ")}. Canvases: ${known.join(", ") || "none yet"}`
-    );
+  const picked = /* @__PURE__ */ new Map();
+  for (const target of targets) {
+    const [canvasId = "", screenId] = target.split("/");
+    if (!known.includes(canvasId))
+      throw new CliError(`No canvas "${canvasId}". Canvases: ${known.join(", ") || "none yet"}`);
+    const screens = picked.has(canvasId) ? picked.get(canvasId) : /* @__PURE__ */ new Set();
+    if (!screenId || screens === null) picked.set(canvasId, null);
+    else picked.set(canvasId, screens.add(screenId));
+  }
+  const canvases = [...picked.keys()];
+  if (options.page) {
+    if (canvases.length !== 1)
+      throw new CliError("--page needs exactly one canvas: `design check <canvas> --page <id>`");
+    const doc = project.canvas(canvases[0]).doc;
+    if (!doc.pages.some((page) => page.id === options.page))
+      throw new CliError(`No page "${options.page}" in "${doc.id}". Pages: ${doc.pages.map((p) => p.id).join(", ")}`);
+  }
+  for (const [canvasId, screens] of picked) {
+    if (!screens) continue;
+    const doc = project.canvas(canvasId).doc;
+    const ids = new Set(canvasFrames(doc, "", "light", { page: options.page, skipMissing: false }).map((job) => job.id));
+    const missing = [...screens].filter((id2) => !ids.has(id2));
+    if (missing.length)
+      throw new CliError(
+        `No screen ${missing.map((id2) => `"${id2}"`).join(", ")} in "${canvasId}"${options.page ? ` on page "${options.page}"` : ""}. Screens: ${[...ids].slice(0, 30).join(", ")}${ids.size > 30 ? ", \u2026" : ""}`
+      );
   }
   const issues = canvases.length ? canvases.flatMap((id2) => project.canvas(id2)?.doc.issues ?? []) : project.issues();
   let frames = [];
   if (options.render) {
-    const wasRunning = await liveServer(paths);
-    const server = await ensureServer(paths, {});
-    if (!wasRunning && !options.json)
-      print(dim(`Started the preview server at ${server.url} (\`design stop\` stops it).`));
-    const base = `http://127.0.0.1:${server.port}`;
-    const docs = (canvases.length ? canvases : known).map((id2) => project.canvas(id2).doc);
-    const jobs = docs.flatMap((doc) => canvasFrames(doc, base, doc.theme ?? "light", { includeUrls: false }));
-    const system = project.system();
-    if (!canvases.length && system) jobs.unshift(...systemFrames(system.doc, base, "light"));
-    if (!options.json) print(dim(`Loading ${plural2(jobs.length, "frame")} in Chrome via ${server.url}\u2026`));
-    frames = await renderFrames(jobs);
+    let base;
+    let docOf = (id2) => project.canvas(id2).doc;
+    let systemDoc = project.system()?.doc ?? null;
+    let close = async () => {
+    };
+    if (options.built) {
+      const out = path26.join(paths.cache, "check-build");
+      fs29.rmSync(out, { recursive: true, force: true });
+      if (!options.json) print(dim("Building the screens as design push does\u2026"));
+      await buildSite(paths, out, {
+        canvases: canvases.length ? canvases : void 0,
+        includeSystem: !canvases.length,
+        includeViewer: false
+      });
+      const read = (rel) => {
+        try {
+          return JSON.parse(fs29.readFileSync(path26.join(out, rel), "utf8"));
+        } catch {
+          return null;
+        }
+      };
+      docOf = (id2) => read(`api/canvas/${id2}.json`) ?? project.canvas(id2).doc;
+      systemDoc = canvases.length ? null : read("api/system.json");
+      const files = sirv2(out, { dev: true });
+      const server = http2.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const segments = url.pathname.split("/").map((segment) => {
+          try {
+            return decodeURIComponent(segment);
+          } catch {
+            return segment;
+          }
+        });
+        req.url = segments.join("/") + url.search;
+        files(req, res, () => {
+          res.statusCode = 404;
+          res.end("Not found");
+        });
+      });
+      await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+      base = `http://127.0.0.1:${server.address().port}`;
+      close = () => new Promise((resolve) => server.close(() => resolve()));
+      if (!options.json) print(dim(`Serving the build at ${base}`));
+    } else {
+      const wasRunning = await liveServer(paths);
+      const server = await ensureServer(paths, {});
+      if (!wasRunning && !options.json)
+        print(dim(`Started the preview server at ${server.url} (\`design stop\` stops it).`));
+      base = `http://127.0.0.1:${server.port}`;
+    }
+    const jobs = (canvases.length ? canvases : known).flatMap((id2) => {
+      const doc = docOf(id2);
+      const theme2 = doc.theme ?? "light";
+      const screens = picked.get(id2);
+      const filter = { includeUrls: false, page: options.page };
+      return screens ? [...screens].flatMap((screen) => canvasFrames(doc, base, theme2, { ...filter, id: screen })) : canvasFrames(doc, base, theme2, filter);
+    });
+    if (!canvases.length && systemDoc) jobs.unshift(...systemFrames(systemDoc, base, "light"));
+    if (!options.json) print(dim(`Loading ${plural2(jobs.length, "frame")} in Chrome\u2026`));
+    try {
+      frames = await renderFrames(jobs);
+    } finally {
+      await close();
+    }
   }
   const linkIssues = options.render ? unroutedLinks(frames, project, canvases.length ? canvases : known) : [];
   const errors = issues.filter((issue) => issue.severity === "error").length;
@@ -4978,7 +5195,8 @@ async function runCheck(paths, canvases, options) {
       }
     }
     if (linkIssues.length) printLinkIssues(linkIssues, project);
-    const scope = canvases.length ? plural2(canvases.length, "canvas", "canvases") : "the project";
+    const screens = [...picked.values()].reduce((sum, set) => sum + (set?.size ?? 0), 0);
+    const scope = !canvases.length ? "the project" : screens && [...picked.values()].every(Boolean) ? plural2(screens, "screen") : options.page ? `page "${options.page}" of ${canvases[0]}` : plural2(canvases.length, "canvas", "canvases");
     if (!errors && !warnings && !broken.length) {
       print(
         green(
@@ -5047,14 +5265,14 @@ function printLinkIssues(issues, project) {
 }
 
 // src/cli/commands/cloud.ts
-import fs29 from "fs";
-import os3 from "os";
-import path26 from "path";
+import fs30 from "fs";
+import os4 from "os";
+import path27 from "path";
 var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function runLogin() {
   const host = cloudHost();
   const client = new CloudClient(host, null);
-  const code = await client.deviceCode(os3.hostname());
+  const code = await client.deviceCode(os4.hostname());
   const url = new URL(code.verification_uri_complete || code.verification_uri, host).toString();
   const expiresIn = code.expires_in ?? 600;
   print(`${bold("Sign in to foss-design Cloud")} ${dim(host)}`);
@@ -5150,7 +5368,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: {} });
-    fs29.rmSync(path26.join(cloudCache(paths), "incoming"), { recursive: true, force: true });
+    fs30.rmSync(path27.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}`);
   }
@@ -5177,8 +5395,8 @@ async function runLink(paths, wanted, options) {
 }
 
 // src/cli/commands/icon.ts
-import fs30 from "fs";
-import path27 from "path";
+import fs31 from "fs";
+import path28 from "path";
 async function toCloud(paths, file) {
   const link = readLink(paths);
   if (!link) return;
@@ -5189,10 +5407,10 @@ async function toCloud(paths, file) {
   }
   const client = new CloudClient(link.host, credential.token);
   try {
-    const ext = file ? path27.extname(file).slice(1) : null;
+    const ext = file ? path28.extname(file).slice(1) : null;
     await client.setProjectIcon(
       link.project,
-      file && ext ? { data: fs30.readFileSync(file), type: ICON_TYPES[ext] } : null
+      file && ext ? { data: fs31.readFileSync(file), type: ICON_TYPES[ext] } : null
     );
     link.icon = file ? iconHash(file) : null;
     writeLink(paths, link);
@@ -5205,35 +5423,35 @@ async function runIcon(paths, file, options) {
   if (options.remove) {
     const had = iconFile(paths);
     writeIcon(paths, null);
-    print(had ? `${green("Removed")} ${path27.relative(process.cwd(), had)}` : "The project has no icon.");
+    print(had ? `${green("Removed")} ${path28.relative(process.cwd(), had)}` : "The project has no icon.");
     await toCloud(paths, null);
     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(`${path27.relative(process.cwd(), current)} ${dim(`${Math.ceil(fs30.statSync(current).size / 1024)} KB`)}`);
+    return print(`${path28.relative(process.cwd(), current)} ${dim(`${Math.ceil(fs31.statSync(current).size / 1024)} KB`)}`);
   }
   let data;
   try {
-    data = fs30.readFileSync(file);
+    data = fs31.readFileSync(file);
   } catch {
     throw new CliError(`No file ${file}`);
   }
-  const problem = iconProblem(data, path27.extname(file).slice(1).toLowerCase() || void 0);
+  const problem = iconProblem(data, path28.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: ${path27.relative(process.cwd(), written)}`);
+  print(`${green("Set")} the project icon: ${path28.relative(process.cwd(), written)}`);
   await toCloud(paths, written);
 }
 
 // src/cli/commands/import.ts
-import fs32 from "fs";
-import path29 from "path";
+import fs33 from "fs";
+import path30 from "path";
 
 // src/import/claude-design.ts
-import fs31 from "fs";
-import path28 from "path";
+import fs32 from "fs";
+import path29 from "path";
 
 // src/import/markup.ts
 var VOID = /* @__PURE__ */ new Set([
@@ -5841,11 +6059,11 @@ function boardId(file, used) {
   return id2;
 }
 function importClaudeDesign(dir, options = {}) {
-  const canvasFile = path28.join(dir, "canvas.json");
-  if (!fs31.existsSync(canvasFile))
+  const canvasFile = path29.join(dir, "canvas.json");
+  if (!fs32.existsSync(canvasFile))
     throw new Error(`No canvas.json in ${dir}: point at the exported Claude Design project folder`);
-  const source = JSON.parse(fs31.readFileSync(canvasFile, "utf8"));
-  const templates = fs31.readdirSync(dir).filter((file) => file.endsWith(EXT));
+  const source = JSON.parse(fs32.readFileSync(canvasFile, "utf8"));
+  const templates = fs32.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();
@@ -5872,7 +6090,7 @@ function importClaudeDesign(dir, options = {}) {
     try {
       files.set(
         `${name}.jsx`,
-        convertFile(name, fs31.readFileSync(path28.join(dir, file), "utf8"), { known, routes, warn: warn2 })
+        convertFile(name, fs32.readFileSync(path29.join(dir, file), "utf8"), { known, routes, warn: warn2 })
       );
     } catch (error) {
       warn2(`could not be converted: ${error.message}`);
@@ -5920,7 +6138,7 @@ function importClaudeDesign(dir, options = {}) {
     screens++;
   }
   const canvas = {
-    title: options.title ?? source.title ?? path28.basename(path28.resolve(dir)),
+    title: options.title ?? source.title ?? path29.basename(path29.resolve(dir)),
     description: "Imported from Claude Design.",
     // The templates bring their own styles; the design system's reset would restyle them.
     system: false,
@@ -5932,21 +6150,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 = path29.resolve(from);
-  if (!fs32.existsSync(dir) || !fs32.statSync(dir).isDirectory()) throw new CliError(`No folder ${from}`);
+  const dir = path30.resolve(from);
+  if (!fs33.existsSync(dir) || !fs33.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(path29.basename(dir)) || "imported");
+  const id2 = options.canvas ?? (slug(String(result.canvas.title)) || slug(path30.basename(dir)) || "imported");
   if (!ID_PATTERN.test(id2)) throw new CliError(`"${id2}" is no canvas id; pass one with --canvas <id>`);
-  const out = path29.join(paths.canvases, id2);
-  if (fs32.existsSync(out)) throw new CliError(`.design/canvas/${id2} exists; pick another id with --canvas <id>`);
-  fs32.mkdirSync(path29.join(out, "screens"), { recursive: true });
-  for (const [name, content] of result.files) fs32.writeFileSync(path29.join(out, "screens", name), content);
-  fs32.writeFileSync(path29.join(out, "canvas.json"), `${JSON.stringify(result.canvas, null, 2)}
+  const out = path30.join(paths.canvases, id2);
+  if (fs33.existsSync(out)) throw new CliError(`.design/canvas/${id2} exists; pick another id with --canvas <id>`);
+  fs33.mkdirSync(path30.join(out, "screens"), { recursive: true });
+  for (const [name, content] of result.files) fs33.writeFileSync(path30.join(out, "screens", name), content);
+  fs33.writeFileSync(path30.join(out, "canvas.json"), `${JSON.stringify(result.canvas, null, 2)}
 `);
   print(`${green("Imported")} ${bold(String(result.canvas.title))} \u2192 .design/canvas/${id2}`);
   print(
@@ -5966,7 +6184,7 @@ function runImport(paths, from, options) {
 
 // src/cli/commands/merge.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import path30 from "path";
+import path31 from "path";
 import { createInterface } from "readline/promises";
 var KIND = {
   text: "both sides changed lines, the markers show them",
@@ -5982,7 +6200,7 @@ function matchTargets(paths, states, targets) {
       for (const conflict of openConflicts(paths, unit)) picked.push({ state: unit, conflict });
       continue;
     }
-    const rel = [path30.relative(paths.design, path30.resolve(target)), target.replace(/^\.design\//, "")];
+    const rel = [path31.relative(paths.design, path31.resolve(target)), target.replace(/^\.design\//, "")];
     const found = states.flatMap(
       (state) => state.conflicts.filter((item) => rel.includes(item.path)).map((conflict) => ({ state, conflict }))
     );
@@ -5998,7 +6216,7 @@ function printOpen(paths, states) {
     print(`${bold(state.unit)} ${dim(`merged with cloud r${state.headRev}`)}`);
     for (const conflict of open2) {
       print(`  ${red("\u2717")} ${conflict.path}  ${dim(KIND[conflict.kind])}`);
-      const sides = ["here", "cloud", "base"].map((side) => `${side}: ${path30.relative(process.cwd(), sideFile(paths, state.unit, conflict.path, side))}`).join(" \xB7 ");
+      const sides = ["here", "cloud", "base"].map((side) => `${side}: ${path31.relative(process.cwd(), sideFile(paths, state.unit, conflict.path, side))}`).join(" \xB7 ");
       print(`      ${dim(sides)}`);
     }
   }
@@ -6079,7 +6297,7 @@ async function runMerge(paths, targets, options) {
           if (answer === "s") break;
           if (answer === "e" && edit) {
             const editor = process.env.VISUAL || process.env.EDITOR || "vi";
-            spawnSync2(editor, [path30.join(paths.design, conflict.path)], { stdio: "inherit", shell: true });
+            spawnSync2(editor, [path31.join(paths.design, conflict.path)], { stdio: "inherit", shell: true });
             if (!openConflicts(paths, state).some((item) => item.path === conflict.path)) break;
             print(yellow("  Conflict markers are still there."));
           }
@@ -6098,7 +6316,7 @@ async function runMerge(paths, targets, options) {
 }
 
 // src/cli/commands/rename.ts
-import fs33 from "fs";
+import fs34 from "fs";
 async function runRename(paths, name) {
   const trimmed = name.trim();
   if (!trimmed) throw new CliError("Usage: design rename <name>");
@@ -6113,17 +6331,17 @@ async function runRename(paths, name) {
   }
   let config = {};
   try {
-    config = JSON.parse(fs33.readFileSync(paths.config, "utf8"));
+    config = JSON.parse(fs34.readFileSync(paths.config, "utf8"));
   } catch {
   }
-  fs33.writeFileSync(paths.config, `${JSON.stringify({ ...config, name: trimmed }, null, 2)}
+  fs34.writeFileSync(paths.config, `${JSON.stringify({ ...config, name: trimmed }, null, 2)}
 `);
   print(`${green("Renamed")} the project to ${trimmed} (.design/design.json)`);
 }
 
 // src/cli/commands/scaffold.ts
-import fs34 from "fs";
-import path31 from "path";
+import fs35 from "fs";
+import path32 from "path";
 
 // src/cli/templates.ts
 var TOKENS_CSS = `/*
@@ -6334,40 +6552,40 @@ function mainScreen(canvasId) {
 
 // src/cli/commands/scaffold.ts
 function write(file, content, root) {
-  if (fs34.existsSync(file)) {
-    print(`  ${dim("exists ")} ${path31.relative(root, file)}`);
+  if (fs35.existsSync(file)) {
+    print(`  ${dim("exists ")} ${path32.relative(root, file)}`);
     return false;
   }
-  fs34.mkdirSync(path31.dirname(file), { recursive: true });
-  fs34.writeFileSync(file, content);
-  print(`  ${green("created")} ${path31.relative(root, file)}`);
+  fs35.mkdirSync(path32.dirname(file), { recursive: true });
+  fs35.writeFileSync(file, content);
+  print(`  ${green("created")} ${path32.relative(root, file)}`);
   return true;
 }
 function ensureGitignored(root) {
-  const file = path31.join(root, ".gitignore");
-  const current = fs34.existsSync(file) ? fs34.readFileSync(file, "utf8") : "";
+  const file = path32.join(root, ".gitignore");
+  const current = fs35.existsSync(file) ? fs35.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" : "";
-  fs34.writeFileSync(file, `${current}${prefix}${current ? "\n" : ""}# Design canvases (foss-design)
+  fs35.writeFileSync(file, `${current}${prefix}${current ? "\n" : ""}# Design canvases (foss-design)
 .design/
 `);
   return "added";
 }
 function projectName(root) {
   try {
-    const manifest = JSON.parse(fs34.readFileSync(path31.join(root, "package.json"), "utf8"));
+    const manifest = JSON.parse(fs35.readFileSync(path32.join(root, "package.json"), "utf8"));
     if (typeof manifest.name === "string" && manifest.name) return manifest.name;
   } catch {
   }
-  return path31.basename(root);
+  return path32.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);
-  fs34.mkdirSync(paths.canvases, { recursive: true });
+  fs35.mkdirSync(paths.canvases, { recursive: true });
   if (options.gitignore) {
     const result = ensureGitignored(root);
     print(`  ${result === "added" ? green("ignored") : dim("ignored")} .design/ in .gitignore`);
@@ -6381,44 +6599,44 @@ function runSystemInit(root, options) {
   const paths = designPaths(root);
   let base = projectName(root);
   try {
-    base = JSON.parse(fs34.readFileSync(paths.config, "utf8")).name || base;
+    base = JSON.parse(fs35.readFileSync(paths.config, "utf8")).name || base;
   } catch {
   }
   const name = options.name ?? `${base} design system`;
-  print(`Scaffolding the design system in ${path31.relative(root, paths.system)}`);
-  write(path31.join(paths.system, "system.json"), `${JSON.stringify({ name }, null, 2)}
+  print(`Scaffolding the design system in ${path32.relative(root, paths.system)}`);
+  write(path32.join(paths.system, "system.json"), `${JSON.stringify({ name }, null, 2)}
 `, root);
-  write(path31.join(paths.system, "tokens.css"), TOKENS_CSS, root);
+  write(path32.join(paths.system, "tokens.css"), TOKENS_CSS, root);
   if (!options.empty) {
-    write(path31.join(paths.system, "guidelines", "01-overview.md"), OVERVIEW_MD, root);
-    write(path31.join(paths.system, "components", "button.tsx"), BUTTON_TSX, root);
-    write(path31.join(paths.system, "specimens", "button.tsx"), BUTTON_SPECIMEN_TSX, root);
+    write(path32.join(paths.system, "guidelines", "01-overview.md"), OVERVIEW_MD, root);
+    write(path32.join(paths.system, "components", "button.tsx"), BUTTON_TSX, root);
+    write(path32.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 = path31.join(paths.canvases, id2);
-  if (fs34.existsSync(path31.join(dir, "canvas.json"))) throw new CliError(`Canvas "${id2}" already exists in ${dir}`);
+  const dir = path32.join(paths.canvases, id2);
+  if (fs35.existsSync(path32.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(
-      path31.join(dir, "canvas.json"),
+      path32.join(dir, "canvas.json"),
       `${JSON.stringify({ title, pages: [{ id: "main", title: "Main", sections: [] }] }, null, 2)}
 `,
       root
     );
-    fs34.mkdirSync(path31.join(dir, "screens"), { recursive: true });
+    fs35.mkdirSync(path32.join(dir, "screens"), { recursive: true });
   } else {
-    write(path31.join(dir, "canvas.json"), canvasJson(title), root);
-    write(path31.join(dir, "screens", "Main.tsx"), mainScreen(id2), root);
+    write(path32.join(dir, "canvas.json"), canvasJson(title), root);
+    write(path32.join(dir, "screens", "Main.tsx"), mainScreen(id2), root);
   }
 }
 
 // src/cli/commands/shot.ts
-import fs35 from "fs";
-import path32 from "path";
+import fs36 from "fs";
+import path33 from "path";
 var OVERVIEW_TIMEOUT = 9e4;
 async function runShot(paths, target, options) {
   const [canvasId = "", screenId] = target.split("/");
@@ -6434,15 +6652,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 = path32.resolve(options.out ?? paths.shots);
-  const outDir = path32.join(outBase, canvasId);
-  fs35.mkdirSync(outDir, { recursive: true });
+  const outBase = path33.resolve(options.out ?? paths.shots);
+  const outDir = path33.join(outBase, canvasId);
+  fs36.mkdirSync(outDir, { recursive: true });
   const base = await serverBase(paths);
   const browser = await launchChrome();
   let failed = false;
   try {
     if (options.overview) {
-      if (!fs35.existsSync(PKG.viewer)) throw new CliError("The viewer is not built, so there is no canvas to shoot.");
+      if (!fs36.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 } });
@@ -6458,7 +6676,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 = path32.join(outDir, `${pageId}.overview.png`);
+        const file = path33.join(outDir, `${pageId}.overview.png`);
         await page.screenshot({ path: file });
         await page.close();
         print(file);
@@ -6487,7 +6705,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 = path32.join(outDir, `${job.id}.${job.theme}.png`);
+    const file = path33.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 });
@@ -6519,8 +6737,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 = path32.join(path32.resolve(options.out ?? paths.shots), SYSTEM_CANVAS);
-  fs35.mkdirSync(outDir, { recursive: true });
+  const outDir = path33.join(path33.resolve(options.out ?? paths.shots), SYSTEM_CANVAS);
+  fs36.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();
@@ -6531,8 +6749,36 @@ async function shootSystem(paths, project, id2, options) {
   }
 }
 
+// src/cli/commands/snapshots.ts
+async function runSnapshots(paths, targets, options) {
+  const known = new DesignProject(paths, DEV_URLS).canvasIds();
+  const picked = /* @__PURE__ */ new Map();
+  for (const target of targets) {
+    const [canvas = "", screen] = target.split("/");
+    if (!known.includes(canvas))
+      throw new CliError(`No canvas "${canvas}". Canvases: ${known.join(", ") || "none yet"}`);
+    const screens = picked.has(canvas) ? picked.get(canvas) : /* @__PURE__ */ new Set();
+    picked.set(canvas, !screen || screens === null ? null : screens.add(screen));
+  }
+  if (options.page && picked.size !== 1)
+    throw new CliError("--page needs exactly one canvas: `design snapshots <canvas> --page <id>`");
+  const canvases = picked.size ? [...picked.keys()] : known;
+  const stale = canvases.flatMap(
+    (canvas) => staleSnapshots(paths, [canvas], { page: options.page, screens: picked.get(canvas) ?? void 0 })
+  );
+  if (!stale.length) return print(green("\u2713 Every screen has current snapshots in both themes."));
+  print(dim(`${stale.length} snapshot${stale.length === 1 ? "" : "s"} to take`));
+  const lines = await takeSnapshots(
+    paths,
+    stale,
+    async () => `http://127.0.0.1:${(await ensureServer(paths, {})).port}`,
+    progress()
+  );
+  for (const line of lines) print(line);
+}
+
 // src/cli/commands/cloud-status.ts
-import path33 from "path";
+import path34 from "path";
 var STATE_TEXT = {
   in_sync: green,
   local_changes: yellow,
@@ -6555,7 +6801,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 ${path33.relative(paths.root, incomingDir(paths, status.key))}`);
+  if (status.conflictRev !== void 0) parts.push(`merge ${path34.relative(paths.root, incomingDir(paths, status.key))}`);
   return parts.join(" \xB7 ");
 }
 async function printCloudStatus(paths, label) {
@@ -6685,15 +6931,23 @@ ${bold("Preview")}
                                              it; one from another version restarts) and print its URL;
                                              --open also opens a browser
           [--restart] [--foreground]
-  stop                                       Stop the viewer
+  stop [--all]                               Stop the viewer; --all stops every preview on this machine
+  previews [--json]                          Every preview running on this machine: project, URL,
+                                             version, uptime; orphans (a project's untracked server) marked
   status                                     Viewer state, a project summary and, with a cloud link, the
                                              account, the linked project and each unit: in sync, local
                                              changes, remote ahead, conflict or archived
 
 ${bold("Verify")}
-  check [canvas\u2026] [--render] [--json]        Validate canvas.json and the system (go() is an error);
-                                             --render loads every screen in Chrome and reports runtime
-                                             errors and links that lead to no screen
+  check [<canvas>[/<screen>]\u2026] [--page <id>] Validate canvas.json and the system (go() is an error);
+        [--render [--built]] [--json]        --render loads every screen in Chrome and reports runtime
+                                             errors and links that lead to no screen; --built renders
+                                             the production build design push uploads instead of the
+                                             dev server. Narrow it to canvases, one page (--page) or
+                                             single screens
+  snapshots [<canvas>[/<screen>]\u2026]           Take the snapshots screens lack, in both themes, for the
+            [--page <id>]                    viewer to show while frames do not run (push does this
+                                             for the canvases it pushes)
   shot <canvas>[/<screen>] [--page <id>]     Screenshot screens with Chrome (PNG paths are printed);
        [--theme light|dark] [--out <dir>]    @system or @system/<id> shoots the design system specimens
        [--overview]
@@ -6712,7 +6966,7 @@ ${bold("Cloud")}  ${dim("units: system (design.json + system/) and canvas/<id>;
   push [canvas\u2026] [--json]                    Build and upload what changed here (or the named units); a
        [--resolved <unit>]                   system change pushes every active canvas with it. When the
                                              cloud is ahead it pulls and merges first, then pushes; it
-                                             stops on conflicts. Refreshes each canvas's cover snapshot.
+                                             stops on conflicts. Takes missing snapshots (both themes).
                                              Prints the web link of every pushed canvas; refuses screens
                                              that still call go()
   pull [canvas\u2026] [--json]                    Take cloud changes into .design; a unit changed on both sides
@@ -6742,7 +6996,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 ? path34.resolve(rootOption) : findProjectRoot();
+  const found = rootOption ? path35.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.");
@@ -6769,6 +7023,8 @@ async function main(argv) {
       open: { type: "boolean" },
       port: { type: "string" },
       restart: { type: "boolean" },
+      all: { type: "boolean" },
+      built: { type: "boolean" },
       foreground: { type: "boolean" },
       render: { type: "boolean" },
       json: { type: "boolean" },
@@ -6793,7 +7049,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 ? path34.resolve(values.root) : process.cwd(), {
+      return runInit(values.root ? path35.resolve(values.root) : process.cwd(), {
         name: values.name,
         gitignore: !values["no-gitignore"]
       });
@@ -6831,11 +7087,20 @@ async function main(argv) {
       });
     }
     case "stop":
-      return runStop(projectPaths(values.root));
+      return values.all ? runStopAll() : runStop(projectPaths(values.root));
+    case "previews":
+      return runPreviews({ json: !!values.json });
     case "status":
       return runStatus(projectPaths(values.root));
     case "check":
-      return runCheck(projectPaths(values.root), rest, { render: !!values.render, json: !!values.json });
+      return runCheck(projectPaths(values.root), rest, {
+        render: !!values.render,
+        json: !!values.json,
+        page: values.page,
+        built: !!values.built
+      });
+    case "snapshots":
+      return runSnapshots(projectPaths(values.root), rest, { page: values.page });
     case "shot": {
       if (!rest[0]) throw new CliError("Usage: design shot <canvas>[/<screen>] [--page <id>] [--theme light|dark]");
       return runShot(projectPaths(values.root), rest[0], {
@@ -6884,20 +7149,42 @@ async function main(argv) {
       throw new CliError(`Unknown command "${command}". Run \`design --help\`.`);
   }
 }
-main(process.argv.slice(2)).catch((error) => {
-  endLine();
-  if (error instanceof CliError) {
-    process.stderr.write(`${red("error")} ${error.message}
-`);
-    process.exit(error.code);
+function relaunchFromRealPath() {
+  if (process.platform !== "win32" || process.env.FOSS_DESIGN_RELAUNCHED) return false;
+  const script = process.argv[1];
+  if (!script) return false;
+  let realScript;
+  let realCwd;
+  try {
+    realScript = fs37.realpathSync.native(script);
+    realCwd = fs37.realpathSync.native(process.cwd());
+  } catch {
+    return false;
   }
-  if (error.code?.startsWith("ERR_PARSE_ARGS")) {
-    process.stderr.write(`${red("error")} ${error.message}
+  const same = (a, b) => path35.resolve(a).toLowerCase() === path35.resolve(b).toLowerCase();
+  if (same(realScript, script) && same(realCwd, process.cwd())) return false;
+  const result = spawnSync3(process.execPath, [...process.execArgv, realScript, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: realCwd,
+    env: { ...process.env, FOSS_DESIGN_RELAUNCHED: "1" }
+  });
+  process.exit(result.status ?? 1);
+}
+if (!relaunchFromRealPath())
+  main(process.argv.slice(2)).catch((error) => {
+    endLine();
+    if (error instanceof CliError) {
+      process.stderr.write(`${red("error")} ${error.message}
+`);
+      process.exit(error.code);
+    }
+    if (error.code?.startsWith("ERR_PARSE_ARGS")) {
+      process.stderr.write(`${red("error")} ${error.message}
 Run \`design --help\`.
 `);
-    process.exit(2);
-  }
-  process.stderr.write(`${red("error")} ${error?.stack ?? String(error)}
+      process.exit(2);
+    }
+    process.stderr.write(`${red("error")} ${error?.stack ?? String(error)}
 `);
-  process.exit(1);
-});
+    process.exit(1);
+  });

package/dist/runtime/index.js

@@ -1,3 +1,57 @@
+// src/runtime/storage.ts
+var frame = new URLSearchParams(location.search).get("__design") || location.pathname;
+function memoryStorage() {
+  const data = /* @__PURE__ */ new Map();
+  const api = {
+    get length() {
+      return data.size;
+    },
+    clear: () => data.clear(),
+    getItem: (key) => data.get(String(key)) ?? null,
+    key: (index) => [...data.keys()][index] ?? null,
+    removeItem: (key) => void data.delete(String(key)),
+    setItem: (key, value) => void data.set(String(key), String(value))
+  };
+  return new Proxy(api, {
+    get: (target, prop) => typeof prop === "string" && !(prop in target) ? data.get(prop) ?? void 0 : Reflect.get(target, prop),
+    set: (target, prop, value) => {
+      if (typeof prop === "string" && !(prop in target)) data.set(prop, String(value));
+      return true;
+    },
+    deleteProperty: (_, prop) => typeof prop === "string" ? data.delete(prop) || true : true,
+    has: (target, prop) => typeof prop === "string" && data.has(prop) || prop in target,
+    ownKeys: () => [...data.keys()],
+    getOwnPropertyDescriptor: (_, prop) => typeof prop === "string" && data.has(prop) ? { value: data.get(prop), writable: true, enumerable: true, configurable: true } : void 0
+  });
+}
+for (const name of ["localStorage", "sessionStorage"]) {
+  try {
+    Object.defineProperty(window, name, { configurable: true, value: memoryStorage() });
+  } catch {
+  }
+}
+var idb = window.indexedDB;
+if (idb) {
+  const own = `design:${frame}:`;
+  const prefix = `${own}${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}:`;
+  const open = idb.open.bind(idb);
+  const remove = idb.deleteDatabase.bind(idb);
+  const list = idb.databases?.bind(idb);
+  idb.open = (name, version) => open(prefix + name, version);
+  idb.deleteDatabase = (name) => remove(prefix + name);
+  if (list) {
+    idb.databases = async () => (await list()).filter((db) => db.name?.startsWith(prefix)).map((db) => ({ ...db, name: db.name.slice(prefix.length) }));
+    void list().then((dbs) => {
+      for (const db of dbs) {
+        if (!db.name?.startsWith(own) || db.name.startsWith(prefix)) continue;
+        const born = Number.parseInt(db.name.slice(own.length).split(":")[0].slice(0, -4), 36);
+        if (!Number.isFinite(born) || Date.now() - born > 10 * 60 * 1e3) remove(db.name);
+      }
+    }).catch(() => {
+    });
+  }
+}
+
 // src/runtime/index.tsx
 import { Component, useSyncExternalStore as useSyncExternalStore2 } from "react";
 import { createRoot } from "react-dom/client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foss-design",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Design canvases and design systems for coding agents: live, animated, clickable screens on an infinite canvas, served locally from a .design folder.",
   "type": "module",
   "license": "MIT",