@sudajs/cli 0.8.2 → 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(
@@ -1965,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;
@@ -1978,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");
@@ -2017,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.`
       );
     }
   }
@@ -2090,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",
@@ -2107,7 +2098,7 @@ async function publishTheme(root, skipBuild, force) {
       manifest: theme.module.manifest,
       agentManifest,
       bundleArtifactRelative,
-      previewArtifactRelative: previewArtifactExists ? previewArtifactRelative : void 0
+      previewArtifactRelative
     })
   });
   if (!completeRes.ok) {
@@ -2304,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."
       );
     }
   });
@@ -2333,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(