@sudajs/cli 0.8.1 → 0.9.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createThemeAgentManifest, createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, validateAgentPageContentWithManifest, agentValidationResultSchema, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
-import { themeManifestSchema, FileSystemThemeRegistry } from '@sudajs/theme-engine/server';
+import { themeManifestSchema } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build } from 'esbuild';
 import { z } from 'zod';
@@ -409,6 +409,10 @@ function createThemeObjectKey(themeKey, version, relativePath) {
 function resolveThemeRoot(options) {
   return path2.resolve(options.themeRoot ?? process.cwd());
 }
+function collectOption(value, previous) {
+  previous.push(value);
+  return previous;
+}
 async function pathExists(filePath) {
   try {
     await stat(filePath);
@@ -491,12 +495,12 @@ ${issues}`);
   if (!module.manifest.key || !module.manifest.version || !module.manifest.name) {
     throw new Error("manifest.key, manifest.version and manifest.name are required.");
   }
-  if (module.manifest.entry !== "dist/index.js") {
-    throw new Error('manifest.entry must be artifact-local: "dist/index.js".');
+  if (module.manifest.entry !== "index.js") {
+    throw new Error('manifest.entry must be artifact-local: "index.js".');
   }
-  if (module.manifest.clientEntry !== void 0 && module.manifest.clientEntry !== "dist/runtime.client.js") {
+  if (module.manifest.clientEntry !== void 0 && module.manifest.clientEntry !== "runtime.client.js") {
     throw new Error(
-      'manifest.clientEntry must be artifact-local: "dist/runtime.client.js" when provided.'
+      'manifest.clientEntry must be artifact-local: "runtime.client.js" when provided.'
     );
   }
   assertRecord(module.pageConfig?.components, "pageConfig.components");
@@ -631,7 +635,7 @@ async function buildViteTheme(root) {
       }
     }
   });
-  await copyThemeSourceAssets(root);
+  await copyThemeAssets(root);
   const stylesheetEntry = path2.join(root, ".suda-build", "styles-entry.ts");
   await mkdir(path2.dirname(stylesheetEntry), { recursive: true });
   await writeFile(stylesheetEntry, 'import "../src/styles.css";\n', "utf8");
@@ -659,8 +663,8 @@ async function buildViteTheme(root) {
   });
   await rm(path2.join(root, "dist", "chunks", "theme-styles.js"), { force: true });
 }
-async function copyThemeSourceAssets(root) {
-  const sourceAssets = path2.join(root, "src", "assets");
+async function copyThemeAssets(root) {
+  const sourceAssets = path2.join(root, "assets");
   if (!await pathExists(sourceAssets)) {
     return;
   }
@@ -827,13 +831,17 @@ function runFooterContractCheck(theme, renderer) {
   return issues;
 }
 var __testUtils = {
+  createThemeProjectRequire,
   createRemotePageDraft,
   findAnchorTagByHref,
   loadThemeScopedRenderer,
+  normalizePlaywrightModule,
+  normalizeSharpModule,
   initThemeWithKey,
   performActivateTheme,
   performConfirmedPageOperation,
   renderDevStarterPageHtml,
+  resolveScreenshotOptions,
   slugifyThemeName,
   validateThemeKey,
   validateThemeName,
@@ -843,7 +851,8 @@ var __testUtils = {
 async function runThemeCheck(theme) {
   const result = checkThemeModule(theme.module);
   const footerIssues = result.ok ? runFooterContractCheck(theme, await loadThemeScopedRenderer(theme.root)) : [];
-  const ok = result.ok && footerIssues.length === 0;
+  const previewIssues = await runPreviewContractCheck(theme);
+  const ok = result.ok && footerIssues.length === 0 && previewIssues.length === 0;
   const lines = [formatThemeCheckResult(result)];
   if (footerIssues.length === 0 && result.ok) {
     lines.push("Footer contract check passed: whiteLabel and ICP metadata render correctly.");
@@ -853,6 +862,14 @@ async function runThemeCheck(theme) {
     }
     lines.push(`Footer contract check: ${footerIssues.length} error(s).`);
   }
+  if (previewIssues.length === 0) {
+    lines.push("Preview contract check passed: desktop, tablet, and mobile screenshots exist.");
+  } else {
+    for (const issue of previewIssues) {
+      lines.push(`  error  assets.preview: ${issue}`);
+    }
+    lines.push(`Preview contract check: ${previewIssues.length} error(s).`);
+  }
   const text = lines.join("\n");
   if (ok) {
     console.log(text);
@@ -861,7 +878,27 @@ async function runThemeCheck(theme) {
   }
   return ok;
 }
+async function runPreviewContractCheck(theme) {
+  const issues = [];
+  for (const relativePath of REQUIRED_PREVIEW_ARTIFACTS) {
+    const filePath = path2.join(theme.root, "dist", relativePath);
+    try {
+      const info = await stat(filePath);
+      if (info.size <= 0) {
+        issues.push(`${relativePath} is empty. Run \`suda theme capture\` and rebuild.`);
+      }
+    } catch {
+      issues.push(`Missing ${relativePath}. Run \`suda theme capture\`, then \`suda theme build\`.`);
+    }
+  }
+  return issues;
+}
 async function watchTheme(root, port) {
+  const handle = await startViteDevPreviewServer(root, port);
+  console.log(`previewing Vite theme at ${handle.url}`);
+  await new Promise(() => void 0);
+}
+async function startViteDevPreviewServer(root, port) {
   const viteConfig = await findViteConfig(root);
   const vite = await loadThemeVite(root);
   const host = "127.0.0.1";
@@ -876,8 +913,11 @@ async function watchTheme(root, port) {
   });
   await server.listen(port);
   const url = server.resolvedUrls?.local.find((candidate) => candidate.includes("127.0.0.1")) ?? server.resolvedUrls?.local[0] ?? `http://${host}:${port}/`;
-  console.log(`previewing Vite theme at ${url}`);
-  await new Promise(() => void 0);
+  return {
+    url: url.replace(/\/$/, ""),
+    port,
+    close: () => server.close()
+  };
 }
 function createSudaPreviewVitePlugin(root) {
   return {
@@ -888,7 +928,7 @@ function createSudaPreviewVitePlugin(root) {
           const url = new URL(request.url ?? "/", "http://localhost");
           const assetPrefixMatch = url.pathname.match(/^\/api\/themes\/[^/]+\/[^/]+\/assets\/(.+)$/);
           if (assetPrefixMatch?.[1]) {
-            request.url = `/src/assets/${assetPrefixMatch[1]}${url.search}`;
+            request.url = `/assets/${assetPrefixMatch[1]}${url.search}`;
             next();
             return;
           }
@@ -906,11 +946,15 @@ function createSudaPreviewVitePlugin(root) {
                 response.end("No starter pages declared by this theme.");
                 return;
               }
-              const requested = url.searchParams.get("page");
-              const activeSlug = requested && findStarterPage(theme, requested) ? requested : fallbackSlug;
+              const starter2 = findStarterPage(theme, fallbackSlug);
+              if (!starter2) {
+                response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+                response.end(`Unknown starter page: ${fallbackSlug}`);
+                return;
+              }
               const html2 = await server.transformIndexHtml(
                 url.pathname,
-                renderPreviewShellHtml(theme, activeSlug)
+                renderDevStarterPageHtml(theme, starter2, renderer)
               );
               response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
               response.end(html2);
@@ -979,10 +1023,6 @@ function createPreviewAssetResolver(resolveAssetPath) {
     });
   };
 }
-function createPreviewThemeAssetUrl(themeKey, themeVersion, relativePath) {
-  const normalizedRelativePath = relativePath.replace(/^\/+/, "");
-  return `${PREVIEW_PUBLIC_BASE_PATH}/${themeKey}/${themeVersion}/assets/${normalizedRelativePath}?v=${encodeURIComponent(themeVersion)}`;
-}
 async function loadThemeScopedRenderer(themeRoot) {
   const themeRequire = createRequire(path2.join(themeRoot, "package.json"));
   const reactPath = themeRequire.resolve("react");
@@ -1001,45 +1041,6 @@ async function loadThemeScopedRenderer(themeRoot) {
     renderToString: reactDomServerModule.renderToString
   };
 }
-function renderStarterPageHtml(theme, resolved, page, renderer) {
-  const chrome = renderer.extractLayoutChrome(theme.module.defaultLayout);
-  const metadata = {
-    resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath)
-  };
-  const body = renderer.renderToString(
-    renderer.createElement(renderer.ThemeRender, {
-      theme: theme.module,
-      pageData: page.data,
-      layoutData: theme.module.defaultLayout,
-      metadata
-    })
-  );
-  const cssVarStyle = Object.entries(chrome.cssVariables).map(([key, value]) => `${key}: ${value};`).join(" ");
-  const stylesheetUrl = resolved.runtime?.stylesheet ? createPreviewThemeAssetUrl(
-    theme.module.manifest.key,
-    theme.module.manifest.version,
-    resolved.runtime.stylesheet
-  ) : null;
-  const stylesheetTag = stylesheetUrl ? `<link rel="stylesheet" href="${escapeHtml(stylesheetUrl)}" />` : "";
-  const customHead = chrome.customHeadCode ?? "";
-  const customBody = chrome.customBodyCode ?? "";
-  return [
-    "<!doctype html>",
-    '<html lang="en">',
-    "<head>",
-    '<meta charset="utf-8" />',
-    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
-    `<title>${escapeHtml(`${theme.module.manifest.name} \u2014 ${page.title}`)}</title>`,
-    stylesheetTag,
-    customHead,
-    "</head>",
-    `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
-    body,
-    customBody,
-    "</body>",
-    "</html>"
-  ].join("");
-}
 function renderDevStarterPageHtml(theme, page, renderer) {
   const chrome = renderer.extractLayoutChrome(theme.module.defaultLayout);
   const metadata = {
@@ -1073,152 +1074,49 @@ function renderDevStarterPageHtml(theme, page, renderer) {
     "</html>"
   ].join("");
 }
-function renderPreviewShellHtml(theme, activeSlug) {
-  const items = theme.module.starterPages.map((page) => {
-    const slug = page.slug;
-    const label = `${page.title}${page.isHome ? " (home)" : ""}`;
-    const active = slug === activeSlug;
-    const href = `/?page=${encodeURIComponent(slug)}`;
-    const className = active ? "suda-preview-tab suda-preview-tab--active" : "suda-preview-tab";
-    return `<a class="${className}" href="${escapeHtml(href)}" target="_self">${escapeHtml(label)}</a>`;
-  }).join("");
-  const frameSrc = `/pages/${encodeURIComponent(activeSlug)}`;
-  return [
-    "<!doctype html>",
-    '<html lang="en">',
-    "<head>",
-    '<meta charset="utf-8" />',
-    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
-    `<title>${escapeHtml(theme.module.manifest.name)} \u2014 preview</title>`,
-    "<style>",
-    "html,body{margin:0;height:100%;font-family:system-ui,sans-serif;background:#0b0d12;color:#e6e8ee;}",
-    ".suda-preview-bar{display:flex;flex-wrap:wrap;gap:.25rem;padding:.5rem .75rem;background:#0b0d12;border-bottom:1px solid #1f2330;position:sticky;top:0;z-index:10;}",
-    ".suda-preview-tab{display:inline-flex;align-items:center;padding:.35rem .75rem;border-radius:.5rem;font-size:.875rem;color:#c9cdd6;text-decoration:none;border:1px solid transparent;}",
-    ".suda-preview-tab:hover{background:#1a1d27;}",
-    ".suda-preview-tab--active{background:#222633;color:#fff;border-color:#2c3142;}",
-    ".suda-preview-frame{display:block;border:0;width:100%;height:calc(100vh - 2.5rem);background:#fff;}",
-    "</style>",
-    "</head>",
-    "<body>",
-    `<nav class="suda-preview-bar">${items}</nav>`,
-    `<iframe class="suda-preview-frame" src="${escapeHtml(frameSrc)}" title="theme preview"></iframe>`,
-    "</body>",
-    "</html>"
-  ].join("");
-}
-async function startPreviewServer(theme, port) {
-  const { createServer } = await import('http');
-  const renderer = await loadThemeScopedRenderer(theme.root);
-  const registry = new FileSystemThemeRegistry({
-    artifacts: [
-      {
-        rootPath: theme.root,
-        serverEntryPath: theme.serverEntryPath,
-        module: theme.module
-      }
-    ]
-  });
-  const themeKey = theme.module.manifest.key;
-  const themeVersion = theme.module.manifest.version;
-  const assetPathPrefix = `${PREVIEW_PUBLIC_BASE_PATH}/${themeKey}/${themeVersion}/assets/`;
-  const clientRuntimePrefix = `${PREVIEW_PUBLIC_BASE_PATH}/${themeKey}/${themeVersion}/runtime/client`;
-  const server = createServer((request, response) => {
-    void (async () => {
-      const url = new URL(request.url ?? "/", `http://localhost:${port}`);
-      const pathname = url.pathname;
-      if (pathname === "/" || pathname === "/index.html") {
-        const fallbackSlug = pickStarterSlug(theme);
-        if (!fallbackSlug) {
-          response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-          response.end("No starter pages declared by this theme.");
-          return;
-        }
-        const requested = url.searchParams.get("page");
-        const activeSlug = requested && findStarterPage(theme, requested) ? requested : fallbackSlug;
-        response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-        response.end(renderPreviewShellHtml(theme, activeSlug));
-        return;
-      }
-      if (pathname.startsWith("/pages/")) {
-        const slug = decodeURIComponent(pathname.slice("/pages/".length));
-        const starter = findStarterPage(theme, slug);
-        if (!starter) {
-          response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-          response.end(`Unknown starter page: ${slug}`);
-          return;
-        }
-        const resolved = await registry.resolve(themeKey, themeVersion);
-        if (!resolved) {
-          response.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
-          response.end("Failed to resolve theme via FileSystemThemeRegistry.");
-          return;
-        }
-        const html = renderStarterPageHtml(theme, resolved, starter, renderer);
-        response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-        response.end(html);
-        return;
-      }
-      if (pathname.startsWith(assetPathPrefix)) {
-        const relativePath = decodeURIComponent(pathname.slice(assetPathPrefix.length));
-        const filePath = await registry.resolveAssetPath(themeKey, themeVersion, relativePath);
-        if (!filePath) {
-          response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-          response.end("Not found");
-          return;
-        }
-        const body = await readFile(filePath);
-        response.writeHead(200, {
-          "Content-Type": contentTypeFor(relativePath),
-          "Cache-Control": "no-cache"
-        });
-        response.end(body);
-        return;
-      }
-      if (pathname === clientRuntimePrefix) {
-        const filePath = await registry.resolveClientEntryPath(themeKey, themeVersion);
-        if (!filePath) {
-          response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-          response.end("Theme has no client runtime bundle.");
-          return;
-        }
-        const body = await readFile(filePath);
-        response.writeHead(200, {
-          "Content-Type": "application/javascript; charset=utf-8",
-          "Cache-Control": "no-cache"
-        });
-        response.end(body);
-        return;
+var SCREENSHOT_DEVICES = ["desktop", "tablet", "mobile"];
+var SCREENSHOT_DEVICE_CONFIG = {
+  desktop: {
+    viewport: { width: 1440, height: 900 },
+    outputRelativePath: path2.join("assets", "preview", "desktop.png")
+  },
+  tablet: {
+    viewport: { width: 834, height: 1112 },
+    outputRelativePath: path2.join("assets", "preview", "tablet.png")
+  },
+  mobile: {
+    viewport: { width: 390, height: 844 },
+    outputRelativePath: path2.join("assets", "preview", "mobile.png")
+  }
+};
+var REQUIRED_PREVIEW_ARTIFACTS = SCREENSHOT_DEVICES.map(
+  (device) => `assets/preview/${device}.png`
+);
+function isScreenshotDevice(value) {
+  return SCREENSHOT_DEVICES.includes(value);
+}
+function parseScreenshotDevices(value) {
+  if (value === void 0) {
+    return [...SCREENSHOT_DEVICES];
+  }
+  const rawValues = Array.isArray(value) ? value : [value];
+  const devices = [];
+  for (const raw of rawValues) {
+    for (const part of raw.split(",")) {
+      const device = part.trim();
+      if (!device) continue;
+      if (!isScreenshotDevice(device)) {
+        throw new Error(
+          `Unknown screenshot device "${device}". Use one of: ${SCREENSHOT_DEVICES.join(", ")}.`
+        );
       }
-      response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-      response.end("Not found");
-    })().catch((error) => {
-      if (!response.headersSent) {
-        response.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+      if (!devices.includes(device)) {
+        devices.push(device);
       }
-      response.end(error instanceof Error ? error.message : "Internal error");
-    });
-  });
-  await new Promise((resolve, reject) => {
-    const onError = (err) => {
-      reject(err);
-    };
-    server.once("error", onError);
-    server.listen(port, () => {
-      server.off("error", onError);
-      resolve();
-    });
-  });
-  return {
-    url: `http://localhost:${port}`,
-    port,
-    close: () => new Promise((resolve) => {
-      server.close(() => {
-        resolve();
-      });
-    })
-  };
+    }
+  }
+  return devices.length > 0 ? devices : [...SCREENSHOT_DEVICES];
 }
-var DEFAULT_SCREENSHOT_RELATIVE = path2.join("dist", "preview", "desktop.png");
 function parsePositiveInt(value, fallback) {
   if (!value) {
     return fallback;
@@ -1227,25 +1125,68 @@ function parsePositiveInt(value, fallback) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 function resolveScreenshotOptions(root, options) {
+  const devices = parseScreenshotDevices(options.device);
+  if (options.output && devices.length !== 1) {
+    throw new Error("`--output` can only be used when exactly one `--device` is selected.");
+  }
   return {
-    outputPath: path2.resolve(root, options.output ?? DEFAULT_SCREENSHOT_RELATIVE),
-    viewport: {
-      width: parsePositiveInt(options.width, 1280),
-      height: parsePositiveInt(options.height, 800)
-    },
+    targets: devices.map((device) => {
+      const config = SCREENSHOT_DEVICE_CONFIG[device];
+      const viewport = {
+        width: parsePositiveInt(options.width, config.viewport.width),
+        height: parsePositiveInt(options.height, config.viewport.height)
+      };
+      return {
+        device,
+        outputPath: path2.resolve(root, options.output ?? config.outputRelativePath),
+        viewport
+      };
+    }),
     port: parsePositiveInt(options.port, 4178),
-    skipBuild: options.skipBuild === true
+    fullPage: options.fullPage === true
   };
 }
-async function loadPlaywright() {
+function createThemeProjectRequire(themeRoot) {
+  return createRequire(path2.join(themeRoot, "package.json"));
+}
+function normalizePlaywrightModule(moduleValue) {
+  if (typeof moduleValue !== "object" || moduleValue === null) {
+    return null;
+  }
+  if ("chromium" in moduleValue) {
+    const chromium = moduleValue.chromium;
+    if (typeof chromium === "object" && chromium !== null && "launch" in chromium) {
+      return moduleValue;
+    }
+  }
+  if ("default" in moduleValue) {
+    return normalizePlaywrightModule(moduleValue.default);
+  }
+  return null;
+}
+function normalizeSharpModule(moduleValue) {
+  if (typeof moduleValue === "function") {
+    return moduleValue;
+  }
+  if (typeof moduleValue !== "object" || moduleValue === null) {
+    return null;
+  }
+  if ("default" in moduleValue) {
+    return normalizeSharpModule(moduleValue.default);
+  }
+  return null;
+}
+async function loadPlaywright(themeRoot) {
+  const themeRequire = createThemeProjectRequire(themeRoot);
   const candidates = ["playwright", "@playwright/test"];
   for (const id of candidates) {
     try {
-      const mod = await import(
-        /* @vite-ignore */
-        id
-      );
-      return mod;
+      const resolvedId = themeRequire.resolve(id);
+      const mod = await import(pathToFileURL(resolvedId).href);
+      const playwright = normalizePlaywrightModule(mod);
+      if (playwright) {
+        return playwright;
+      }
     } catch {
     }
   }
@@ -1253,33 +1194,81 @@ async function loadPlaywright() {
     "Playwright is required for screenshot capture. Install it as a dev dependency: `pnpm add -D playwright && pnpm exec playwright install chromium`."
   );
 }
-async function captureScreenshot(theme, options) {
-  const playwright = await loadPlaywright();
-  const handle = await startPreviewServer(theme, options.port);
+var warnedMissingSharp = false;
+var warnedSharpOptimizeFailure = false;
+async function loadOptionalSharp(themeRoot) {
+  const resolvers = [
+    createThemeProjectRequire(themeRoot),
+    createRequire(path2.join(packageRoot, "package.json"))
+  ];
+  for (const resolver of resolvers) {
+    try {
+      const sharpModulePath = resolver.resolve("sharp");
+      const mod = await import(pathToFileURL(sharpModulePath).href);
+      const sharp = normalizeSharpModule(mod);
+      if (sharp) {
+        return sharp;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function optimizePngIfAvailable(themeRoot, filePath) {
+  const sharp = await loadOptionalSharp(themeRoot);
+  if (!sharp) {
+    if (!warnedMissingSharp) {
+      console.warn(
+        "warning: PNG optimization skipped because optional dependency `sharp` is not installed. Install it in the theme project to enable preview compression."
+      );
+      warnedMissingSharp = true;
+    }
+    return;
+  }
+  try {
+    const optimized = await sharp(filePath).png({ compressionLevel: 9, palette: true }).toBuffer();
+    await writeFile(filePath, optimized);
+  } catch {
+    if (!warnedSharpOptimizeFailure) {
+      console.warn(
+        "warning: PNG optimization failed. The screenshot was saved uncompressed."
+      );
+      warnedSharpOptimizeFailure = true;
+    }
+  }
+}
+async function captureScreenshot(root, options) {
+  const playwright = await loadPlaywright(root);
+  const handle = await startViteDevPreviewServer(root, options.port);
   try {
-    await mkdir(path2.dirname(options.outputPath), { recursive: true });
     const browser = await playwright.chromium.launch({ headless: true });
     try {
-      const context = await browser.newContext({
-        viewport: options.viewport,
-        deviceScaleFactor: 1
-      });
-      const page = await context.newPage();
-      await page.goto(handle.url, { waitUntil: "networkidle" });
-      await page.screenshot({ path: options.outputPath, fullPage: false });
-      await context.close();
+      for (const target of options.targets) {
+        await mkdir(path2.dirname(target.outputPath), { recursive: true });
+        const context = await browser.newContext({
+          viewport: target.viewport,
+          deviceScaleFactor: 1
+        });
+        try {
+          const page = await context.newPage();
+          await page.goto(handle.url, { waitUntil: "networkidle" });
+          await page.screenshot({ path: target.outputPath, fullPage: options.fullPage });
+        } finally {
+          await context.close();
+        }
+        await optimizePngIfAvailable(root, target.outputPath);
+        console.log(`captured ${target.device} ${path2.relative(root, target.outputPath)}`);
+      }
     } finally {
       await browser.close();
     }
   } finally {
     await handle.close();
   }
-  console.log(`captured ${path2.relative(theme.root, options.outputPath)}`);
 }
 async function screenshotTheme(root, options) {
   const resolved = resolveScreenshotOptions(root, options);
-  const theme = resolved.skipBuild ? await validateTheme(root) : await buildTheme(root);
-  await captureScreenshot(theme, resolved);
+  await captureScreenshot(root, resolved);
 }
 async function loadLocalAgentManifest(root) {
   const built = await readJsonIfExists(
@@ -1405,34 +1394,38 @@ async function createAgentPage(options) {
     return;
   }
   const auth = await requireCliBaseUrl();
-  const response = await createRemotePageDraft(
-    auth,
-    {
-      projectId: options.projectId,
-      title: options.title,
-      slug: options.slug,
-      themeKey: manifest.manifest.key,
-      themeVersion: manifest.manifest.version,
-      data: pageContent
-    },
-    fetchJson
-  );
+  const request = {
+    projectId: options.projectId,
+    title: options.title,
+    slug: options.slug,
+    themeKey: manifest.manifest.key,
+    themeVersion: manifest.manifest.version,
+    data: pageContent
+  };
+  if (options.home === true) {
+    request.isHome = true;
+  }
+  const response = await createRemotePageDraft(auth, request, fetchJson);
   printJson({ success: true, ...response });
 }
 async function createRemotePageDraft(auth, input, fetcher = fetchJson) {
+  const body = {
+    title: input.title,
+    slug: input.slug,
+    themeKey: input.themeKey,
+    themeVersion: input.themeVersion,
+    data: input.data
+  };
+  if (input.isHome !== void 0) {
+    body.isHome = input.isHome;
+  }
   return fetcher(
     `${auth.baseUrl}/api/cli/agent/projects/${encodeURIComponent(input.projectId)}/pages`,
     {
       method: "POST",
       token: auth.token,
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        title: input.title,
-        slug: input.slug,
-        themeKey: input.themeKey,
-        themeVersion: input.themeVersion,
-        data: input.data
-      })
+      body: JSON.stringify(body)
     }
   );
 }
@@ -1701,18 +1694,19 @@ async function startMcpServer() {
   server.registerTool(
     "create_page_draft",
     {
-      description: "Create a new workspace page draft from AI-generated Suda page content.",
+      description: "Create a new workspace page draft from AI-generated Suda page content. When creating a complete website, mark exactly one primary landing page with isHome: true so it becomes the public homepage at `/`. After this tool succeeds, tell the user the page is only a draft, explain that they can review it in the SudaCloud workspace by navigating to Pages, opening the created page, previewing it, then clicking Publish, and ask whether they want you to publish it now. Do not call publish_page until the user explicitly confirms.",
       inputSchema: {
         projectId: z.string(),
         title: z.string(),
         slug: z.string(),
+        isHome: z.boolean().optional().describe("Set true for exactly one page that should serve as the public homepage at `/`."),
         theme: z.string(),
         data: z.unknown(),
         version: z.string().optional()
       },
       outputSchema: createPageDraftOutputSchema
     },
-    async ({ projectId, title, slug, theme, data, version }) => {
+    async ({ projectId, title, slug, isHome, theme, data, version }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId });
       const validation = validateAgentPageContentWithManifest(data, manifest);
       if (!validation.valid) {
@@ -1730,12 +1724,13 @@ async function startMcpServer() {
         projectId,
         title,
         slug,
+        isHome,
         themeKey: manifest.manifest.key,
         themeVersion: manifest.manifest.version,
         data
       });
       return mcpStructured(
-        "Created Suda page draft.",
+        "Created Suda page draft. Tell the user they can review it in the SudaCloud workspace under Pages by opening the created page, previewing it, then clicking Publish. Ask whether they want you to publish it now before calling publish_page.",
         createPageDraftOutputSchema.parse({ status: "created", ...response })
       );
     }
@@ -1810,7 +1805,7 @@ async function startMcpServer() {
   server.registerTool(
     "publish_page",
     {
-      description: "Publish the current saved draft for a Suda page by slug. This affects the public site: first call without confirm to get the exact project, slug, and impact; only call again with confirm: true after the user explicitly agrees.",
+      description: "Publish the current saved draft for a Suda page by slug. This affects the public site: first call without confirm to get the exact project, slug, and impact; only call again with confirm: true after the user explicitly agrees. If the user wants to review manually first, tell them to open the SudaCloud workspace, navigate to Pages, open the created page, preview it, then click Publish.",
       inputSchema: {
         projectId: z.string(),
         slug: z.string(),
@@ -1959,10 +1954,11 @@ async function collectFiles(root, directory) {
       continue;
     }
     const relativePath = path2.relative(root, absolutePath).replaceAll(path2.sep, "/");
+    const publishRelativePath = relativePath.startsWith("dist/") ? relativePath.slice("dist/".length) : relativePath;
     files.push({
       absolutePath,
-      relativePath,
-      contentType: contentTypeFor(relativePath)
+      relativePath: publishRelativePath,
+      contentType: contentTypeFor(publishRelativePath)
     });
   }
   return files;
@@ -1972,10 +1968,12 @@ async function collectThemeArtifactFiles(theme) {
   return files;
 }
 var SSR_REQUIRED_ARTIFACTS = [
-  "dist/index.js",
-  "dist/runtime.client.js",
-  "dist/manifest.json",
-  "dist/styles.css"
+  "index.js",
+  "runtime.client.js",
+  "manifest.json",
+  "styles.css",
+  "agent-manifest.json",
+  ...REQUIRED_PREVIEW_ARTIFACTS
 ];
 async function checksum(files) {
   const hash = createHash("sha256");
@@ -2011,13 +2009,13 @@ async function publishTheme(root, skipBuild, force) {
   }
   const files = await collectThemeArtifactFiles(theme);
   if (!theme.clientEntryPath) {
-    throw new Error("Missing dist/runtime.client.js. Run `suda theme build` first.");
+    throw new Error("Missing runtime.client.js. Run `suda theme build` first.");
   }
   const collectedPaths = new Set(files.map((f) => f.relativePath));
   for (const required of SSR_REQUIRED_ARTIFACTS) {
     if (!collectedPaths.has(required)) {
       throw new Error(
-        `Missing required SSR artifact: ${required}. Run \`suda theme build\` and ensure ${required === "dist/styles.css" ? "`dist/styles.css` is generated" : `\`${required}\` is generated`}.`
+        `Missing required theme artifact: ${required}. Run \`suda theme build\` and ensure \`${required}\` is generated.`
       );
     }
   }
@@ -2084,9 +2082,8 @@ async function publishTheme(root, skipBuild, force) {
     }
     console.log(`uploaded ${createThemeObjectKey(key, version, file.relativePath)}`);
   }
-  const bundleArtifactRelative = "dist/index.js";
-  const previewArtifactRelative = "dist/preview/desktop.png";
-  const previewArtifactExists = await pathExists(path2.join(theme.root, previewArtifactRelative));
+  const bundleArtifactRelative = "index.js";
+  const previewArtifactRelative = "assets/preview/desktop.png";
   const agentManifest = createThemeAgentManifest(theme.module);
   const completeRes = await fetch(`${baseUrl}/api/cli/themes/publish-complete`, {
     method: "POST",
@@ -2101,7 +2098,7 @@ async function publishTheme(root, skipBuild, force) {
       manifest: theme.module.manifest,
       agentManifest,
       bundleArtifactRelative,
-      previewArtifactRelative: previewArtifactExists ? previewArtifactRelative : void 0
+      previewArtifactRelative
     })
   });
   if (!completeRes.ok) {
@@ -2298,7 +2295,7 @@ function buildProgram() {
     console.log(`valid ${result.module.manifest.key}@${result.module.manifest.version}`);
     if (!result.clientEntryPath) {
       console.warn(
-        "warning: dist/runtime.client.js is missing; editor runtime will not load until `suda theme build` runs."
+        "warning: runtime.client.js is missing; editor runtime will not load until `suda theme build` runs."
       );
     }
   });
@@ -2327,7 +2324,12 @@ function buildProgram() {
     const port = Number(options.port ?? "4177");
     await watchTheme(resolveThemeRoot(options), Number.isFinite(port) ? port : 4177);
   });
-  theme.command("screenshot").description("Capture a desktop preview screenshot of the home starter page using Playwright.").option("--theme-root <path>", "Theme source/artifact root.").option("--output <path>", "Output PNG path relative to theme root.").option("--width <px>", "Viewport width in pixels.", "1280").option("--height <px>", "Viewport height in pixels.", "800").option("--port <port>", "Preview server port used during capture.", "4178").option("--skip-build", "Skip rebuilding the theme before capturing.").action(async (options) => {
+  theme.command("screenshot").alias("capture").description("Capture preview screenshots of the home starter page using Playwright.").option("--theme-root <path>", "Theme source/artifact root.").option(
+    "--device <device>",
+    "Device to capture: desktop, tablet, mobile. Repeat or use comma-separated values.",
+    collectOption,
+    []
+  ).option("--output <path>", "Output PNG path relative to theme root. Requires exactly one device.").option("--width <px>", "Override viewport width in pixels.").option("--height <px>", "Override viewport height in pixels.").option("--full-page", "Capture the full page instead of the viewport.").option("--port <port>", "Preview server port used during capture.", "4178").action(async (options) => {
     await screenshotTheme(resolveThemeRoot(options), options);
   });
   theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option(
@@ -2386,7 +2388,9 @@ function buildProgram() {
   agentPage.command("validate").description("Validate an AI-generated Suda page content JSON document.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
     await validateAgentPage(options.theme, options.input, options);
   });
-  agentPage.command("create").description("Create a workspace page draft from AI-generated Suda page content JSON.").requiredOption("--project-id <projectId>", "Project id.").requiredOption("--title <title>", "Page title.").requiredOption("--slug <slug>", "Page slug.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").action(async (options) => {
+  agentPage.command("create").description(
+    "Create a workspace page draft from AI-generated Suda page content JSON. Review it in Pages, then preview and publish from the workspace."
+  ).requiredOption("--project-id <projectId>", "Project id.").requiredOption("--title <title>", "Page title.").requiredOption("--slug <slug>", "Page slug.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").option("--home", "Mark this page draft as the project's homepage.").action(async (options) => {
     await createAgentPage(options);
   });
   const agentSection = agent.command("section").description("Inspect a single section.");