@numueg/theme-cli 0.2.0 → 0.4.1

package/dist/index.js

@@ -715,8 +715,147 @@ var init_touch_target = __esm({
   }
 });
 
+// src/lint/rules/_render-path.ts
+function computeBrowserOnlyRanges(source) {
+  const lines = source.split("\n");
+  const ranges = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!CALLBACK_OPENERS.test(lines[i])) continue;
+    let depth = 0;
+    let started = false;
+    let end = i;
+    for (let j = i; j < lines.length; j++) {
+      for (const ch of lines[j]) {
+        if (ch === "(" || ch === "{") {
+          depth++;
+          started = true;
+        } else if (ch === ")" || ch === "}") {
+          depth--;
+        }
+      }
+      if (started && depth <= 0) {
+        end = j;
+        break;
+      }
+      end = j;
+    }
+    ranges.push([i + 1, end + 1]);
+  }
+  return ranges;
+}
+function inRanges(line, ranges) {
+  return ranges.some(([start, end]) => line >= start && line <= end);
+}
+function isGuardedNearby(lines, idx) {
+  for (let i = Math.max(0, idx - 3); i <= idx; i++) {
+    if (/typeof\s+(window|document|navigator|localStorage|sessionStorage)\b/.test(lines[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+function isCommentLine(line) {
+  const t = line.trim();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+function isImportLine(line) {
+  return /^\s*import\b/.test(line);
+}
+var CALLBACK_OPENERS;
+var init_render_path = __esm({
+  "src/lint/rules/_render-path.ts"() {
+    "use strict";
+    CALLBACK_OPENERS = /\b(useEffect|useLayoutEffect|useInsertionEffect|addEventListener|removeEventListener|setTimeout|setInterval|requestAnimationFrame|requestIdleCallback)\s*\(|\bon[A-Z]\w*\s*=\s*\{/;
+  }
+});
+
+// src/lint/rules/ssr-unsafe-globals.ts
+var ssr_unsafe_globals_exports = {};
+__export(ssr_unsafe_globals_exports, {
+  default: () => ssr_unsafe_globals_default
+});
+var BROWSER_GLOBAL, rule13, ssr_unsafe_globals_default;
+var init_ssr_unsafe_globals = __esm({
+  "src/lint/rules/ssr-unsafe-globals.ts"() {
+    "use strict";
+    init_render_path();
+    BROWSER_GLOBAL = /\b(window|document|navigator)\s*\.|\b(localStorage|sessionStorage)\b/;
+    rule13 = {
+      id: "ssr-unsafe-globals",
+      description: "browser globals in the render path crash or de-SSR server rendering",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          if (!BROWSER_GLOBAL.test(source)) continue;
+          const lines = source.split("\n");
+          const browserOnly = computeBrowserOnlyRanges(source);
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!BROWSER_GLOBAL.test(line)) continue;
+            if (isCommentLine(line) || isImportLine(line)) continue;
+            if (inRanges(i + 1, browserOnly)) continue;
+            if (isGuardedNearby(lines, i)) continue;
+            issues.push({
+              rule: rule13.id,
+              severity: "warning",
+              file,
+              line: i + 1,
+              message: "Runs during server render once this theme is SSR-capable \u2014 browser globals don't exist there.",
+              suggestion: 'Guard with `typeof window !== "undefined"`, or move the access into useEffect / an event handler.'
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    ssr_unsafe_globals_default = rule13;
+  }
+});
+
+// src/lint/rules/ssr-nondeterministic-render.ts
+var ssr_nondeterministic_render_exports = {};
+__export(ssr_nondeterministic_render_exports, {
+  default: () => ssr_nondeterministic_render_default
+});
+var NONDETERMINISTIC, rule14, ssr_nondeterministic_render_default;
+var init_ssr_nondeterministic_render = __esm({
+  "src/lint/rules/ssr-nondeterministic-render.ts"() {
+    "use strict";
+    init_render_path();
+    NONDETERMINISTIC = /\bDate\.now\s*\(|\bnew\s+Date\s*\(\s*\)|\bMath\.random\s*\(|\bcrypto\.randomUUID\s*\(/;
+    rule14 = {
+      id: "ssr-nondeterministic-render",
+      description: "time/random calls in the render path differ between server and client \u2192 hydration mismatch",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          if (!NONDETERMINISTIC.test(source)) continue;
+          const lines = source.split("\n");
+          const browserOnly = computeBrowserOnlyRanges(source);
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!NONDETERMINISTIC.test(line)) continue;
+            if (isCommentLine(line) || isImportLine(line)) continue;
+            if (inRanges(i + 1, browserOnly)) continue;
+            issues.push({
+              rule: rule14.id,
+              severity: "warning",
+              file,
+              line: i + 1,
+              message: "Produces a different value on the server than on the client \u2192 hydration mismatch once this theme is SSR-capable.",
+              suggestion: "Read time/randomness inside useEffect and store it in state (initial render uses a deterministic placeholder)."
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    ssr_nondeterministic_render_default = rule14;
+  }
+});
+
 // src/index.ts
-var import_commander17 = require("commander");
+var import_commander18 = require("commander");
 
 // src/commands/init.ts
 var import_commander = require("commander");
@@ -912,36 +1051,23 @@ export default function Hero({ settings }: SectionProps) {
   );
   fs.writeFileSync(
     path.join(dir, "src/main.tsx"),
-    `import { createRoot, type Root } from "react-dom/client";
-import type {
-  ThemeSettingsV3,
-  Page,
-  Product,
-  Collection,
-  Store,
-} from "@numueg/theme-sdk";
-import {
-  usePage,
-  PageContext,
-  ProductProvider,
-  CollectionProvider,
-  NuMuProvider,
-} from "@numueg/theme-sdk";
+    `import type { ComponentType } from "react";
+import { defineThemeEntry } from "@numueg/theme-sdk";
+import type { ThemeSettingsV3 } from "@numueg/theme-sdk";
 import Hero from "./sections/Hero";
 
+const SECTION_REGISTRY: Record<string, ComponentType<any>> = {
+  hero: Hero,
+};
+
 interface ThemeProps {
   themeSettings: ThemeSettingsV3;
+  currentTemplate: string;
 }
 
-const SECTION_REGISTRY: Record<string, React.ComponentType<any>> = {
-  hero: Hero,
-};
-
-export default function Theme({ themeSettings }: ThemeProps) {
-  const page = usePage();
-  const pageType = page?.type || "home";
+export default function Theme({ themeSettings, currentTemplate }: ThemeProps) {
   const template =
-    themeSettings.templates?.[pageType] || themeSettings.templates?.home;
+    themeSettings.templates?.[currentTemplate] || themeSettings.templates?.home;
 
   return (
     <main>
@@ -963,106 +1089,15 @@ export default function Theme({ themeSettings }: ThemeProps) {
   );
 }
 
-// \u2500\u2500 BYOT mount helper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-// Required by Next.js storefront's <ByotThemeBoundary>. Owns the React
-// render cycle for the bundle's subtree so hooks work.
-
-interface MountProps {
-  themeSettings: ThemeSettingsV3;
-  storeData?: Store;
-  page?: Page & { data?: Record<string, unknown> };
-}
-
-// Fallback Store used only when host didn't pass storeData. NuMuProvider
-// hard-requires Store.currency for Intl.NumberFormat \u2014 synthesize one
-// instead of crashing.
-const FALLBACK_STORE: Store = {
-  id: "",
-  name: "",
-  slug: "",
-  currency: "USD",
-  default_language: "en",
-  use_nextjs_storefront: true,
-};
-
-function ThemeWithContext({ themeSettings, storeData, page }: MountProps) {
-  // Storefront returns snake_case \`default_currency\` / \`default_language\`
-  // but SDK Store expects \`currency\`. Map both shapes so NuMuProvider's
-  // Intl.NumberFormat doesn't blow up on an empty currency code.
-  const raw = (storeData ?? FALLBACK_STORE) as Record<string, unknown> & Store;
-  const store: Store = {
-    ...raw,
-    currency:
-      (raw.currency as string) ||
-      (raw.default_currency as string) ||
-      FALLBACK_STORE.currency,
-    default_language:
-      (raw.default_language as string) || FALLBACK_STORE.default_language,
-  };
-
-  const product = page?.data?.product as Product | undefined;
-  const collection = page?.data?.collection as Collection | undefined;
-  const pageValue: Page = page
-    ? {
-        type: page.type,
-        title: page.title || "",
-        handle: page.handle,
-        data: page.data,
-      }
-    : { type: "home", title: "" };
-
-  let tree = <Theme themeSettings={themeSettings} />;
-  if (collection)
-    tree = <CollectionProvider collection={collection}>{tree}</CollectionProvider>;
-  if (product)
-    tree = <ProductProvider product={product}>{tree}</ProductProvider>;
-
-  return (
-    <NuMuProvider store={store} themeSettings={themeSettings} locale={store.default_language}>
-      <PageContext.Provider value={pageValue}>{tree}</PageContext.Provider>
-    </NuMuProvider>
-  );
-}
-
-// The host (\`ByotThemeBoundary\`) prefers the object-shape return:
-//   { unmount, update }
-// When \`update\` is present, the customizer forwards prop-only changes
-// (themeSettings / storeData / page) into the SAME React tree without
-// re-importing the bundle. Without \`update\`, every settings tweak
-// would trigger a full remount \u2014 fine, but visibly slower.
-export interface MountHandle {
-  unmount: () => void;
-  update: (next: MountProps) => void;
-}
-
-export function mount(el: HTMLElement, props: MountProps): MountHandle {
-  const root: Root = createRoot(el);
-  let current: MountProps = props;
-  root.render(<ThemeWithContext {...current} />);
-
-  // Live preview: the storefront's PreviewBridge forwards customizer edits
-  // as \`numu:theme-update\` window events. Re-render with the new payload.
-  // Also covered by the \`update\` method below \u2014 both paths funnel into
-  // the same root.render() so they can't drift.
-  function handleUpdate(e: Event) {
-    const detail = (e as CustomEvent<ThemeSettingsV3>).detail;
-    if (!detail || typeof detail !== "object") return;
-    current = { ...current, themeSettings: detail };
-    root.render(<ThemeWithContext {...current} />);
-  }
-  window.addEventListener("numu:theme-update", handleUpdate);
+// SSR rule of thumb: everything rendered above must be deterministic and
+// browser-free (no window/document/Date.now in the render path \u2014 put those
+// in useEffect). \`numu-theme lint\` checks this for you.
+const entry = defineThemeEntry(({ themeSettings, currentTemplate }) => (
+  <Theme themeSettings={themeSettings} currentTemplate={currentTemplate} />
+));
 
-  return {
-    unmount: () => {
-      window.removeEventListener("numu:theme-update", handleUpdate);
-      root.unmount();
-    },
-    update: (next: MountProps) => {
-      current = next;
-      root.render(<ThemeWithContext {...current} />);
-    },
-  };
-}
+export const mount = entry.mount;
+export const createApp = entry.createApp;
 `
   );
   fs.writeFileSync(
@@ -1102,7 +1137,10 @@ const placeholder = {
 };
 
 const root = document.getElementById("root");
-if (root) createRoot(root).render(<Theme themeSettings={placeholder as any} />);
+if (root)
+  createRoot(root).render(
+    <Theme themeSettings={placeholder as any} currentTemplate="home" />,
+  );
 `
   );
   fs.writeFileSync(
@@ -1159,12 +1197,14 @@ export default defineConfig({
         scripts: {
           dev: "numu-theme dev",
           build: "numu-theme build",
-          check: "numu-theme check"
+          check: "numu-theme check",
+          // Render-verify every template against fixtures (Phase 2).
+          verify: "numu-theme verify"
         },
-        dependencies: { "@numueg/theme-sdk": "^0.2.0" },
+        dependencies: { "@numueg/theme-sdk": "^0.4.0" },
         devDependencies: {
-          "@numueg/theme-cli": "^0.2.0",
-          "@numueg/theme-plugin": "^0.2.0",
+          "@numueg/theme-cli": "^0.4.0",
+          "@numueg/theme-plugin": "^0.4.0",
           "@vitejs/plugin-react": "^4.3.0",
           vite: "^6.0.0",
           typescript: "^5.8.0",
@@ -1274,12 +1314,12 @@ function assertHttpsOrLocalhost(urlStr) {
   }
   throw new Error(`Unsupported protocol: ${url.protocol}`);
 }
-async function apiRequest(method, path15, body) {
+async function apiRequest(method, path16, body) {
   const config = loadConfig();
-  const url = assertHttpsOrLocalhost(`${config.api_url}${path15}`);
+  const url = assertHttpsOrLocalhost(`${config.api_url}${path16}`);
   const isHttps = url.protocol === "https:";
   const transport = isHttps ? https : http;
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const headers = {};
     if (config.token) headers["Authorization"] = `Bearer ${config.token}`;
     let postData;
@@ -1301,7 +1341,7 @@ async function apiRequest(method, path15, body) {
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve9({
+          resolve10({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1334,7 +1374,7 @@ Content-Type: application/zip\r
   const fullBody = Buffer.concat([head, fileBuffer, tail]);
   const isHttps = url.protocol === "https:";
   const transport = isHttps ? https : http;
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const headers = {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
       "Content-Length": String(fullBody.byteLength)
@@ -1357,7 +1397,7 @@ Content-Type: application/zip\r
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve9({
+          resolve10({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1532,6 +1572,48 @@ function validateTheme(themeDir) {
   if (!themeJson.presets || Object.keys(themeJson.presets).length === 0) {
     warnings.push("theme.json has no presets \u2014 merchants will start with an empty page");
   }
+  const REQUIRED_TEMPLATES = [
+    "home",
+    "product",
+    "collection",
+    "cart",
+    "page",
+    "search",
+    "404"
+  ];
+  if (themeJson.presets && typeof themeJson.presets === "object") {
+    const referenced = /* @__PURE__ */ new Set();
+    for (const bucket of [
+      themeJson.presets.templates,
+      themeJson.presets.section_groups
+    ]) {
+      if (!bucket || typeof bucket !== "object") continue;
+      for (const entry of Object.values(bucket)) {
+        const sections = entry?.sections;
+        const instances = Array.isArray(sections) ? sections : sections && typeof sections === "object" ? Object.values(sections) : [];
+        for (const inst of instances) {
+          if (inst && typeof inst.type === "string") {
+            referenced.add(inst.type.toLowerCase());
+          }
+        }
+      }
+    }
+    for (const type of referenced) {
+      if (!schemaNames.has(type)) {
+        errors.push(
+          `theme.json preset references section type "${type}" but there is no schemas/sections/${type}.json \u2014 the storefront drops unknown sections at render.`
+        );
+      }
+    }
+    const templates = themeJson.presets.templates && typeof themeJson.presets.templates === "object" ? themeJson.presets.templates : {};
+    for (const tpl of REQUIRED_TEMPLATES) {
+      if (!(tpl in templates)) {
+        warnings.push(
+          `theme.json has no preset for the "${tpl}" template \u2014 the storefront will use its built-in fallback.`
+        );
+      }
+    }
+  }
   return { valid: errors.length === 0, errors, warnings };
 }
 
@@ -1641,7 +1723,9 @@ async function runAllRules(themeDir, options) {
     () => Promise.resolve().then(() => (init_use_app_no_availability_check(), use_app_no_availability_check_exports)),
     () => Promise.resolve().then(() => (init_manifest_required_fields(), manifest_required_fields_exports)),
     () => Promise.resolve().then(() => (init_contrast_hint(), contrast_hint_exports)),
-    () => Promise.resolve().then(() => (init_touch_target(), touch_target_exports))
+    () => Promise.resolve().then(() => (init_touch_target(), touch_target_exports)),
+    () => Promise.resolve().then(() => (init_ssr_unsafe_globals(), ssr_unsafe_globals_exports)),
+    () => Promise.resolve().then(() => (init_ssr_nondeterministic_render(), ssr_nondeterministic_render_exports))
   ];
   const issues = [];
   for (const load of ruleLoaders) {
@@ -1656,14 +1740,14 @@ async function runAllRules(themeDir, options) {
       });
       continue;
     }
-    const rule13 = mod.default;
-    if (options.enabledRules && !options.enabledRules.has(rule13.id)) continue;
+    const rule15 = mod.default;
+    if (options.enabledRules && !options.enabledRules.has(rule15.id)) continue;
     try {
-      const ruleIssues = await rule13.check(ctx);
+      const ruleIssues = await rule15.check(ctx);
       for (const issue of ruleIssues) issues.push(issue);
     } catch (e) {
       issues.push({
-        rule: rule13.id,
+        rule: rule15.id,
         severity: "warning",
         message: `Rule crashed: ${e.message}`
       });
@@ -1887,14 +1971,102 @@ Bundle size: ${sizeMB} MB`);
           "\u26A0 Bundle exceeds 5MB limit \u2014 optimize before submitting to marketplace"
         );
       }
+      const serverBundle = path6.join(distDir, "theme.server.js");
+      if (fs7.existsSync(serverBundle)) {
+        const kb = (fs7.statSync(serverBundle).size / 1024).toFixed(1);
+        console.log(`SSR bundle: theme.server.js (${kb} KB) \u2014 hosts will server-render this theme`);
+      } else {
+        console.log(
+          "SSR bundle: not emitted \u2014 theme ships client-only. Export `createApp` via defineThemeEntry (SDK \u2265 0.3) and build with federate:true to enable server rendering."
+        );
+      }
     }
     console.log("\n\u2713 Build complete");
   }
 );
 
-// src/commands/push.ts
+// src/commands/verify.ts
 var import_commander6 = require("commander");
+var import_child_process5 = require("child_process");
+var import_fs = require("fs");
+var import_module = require("module");
 var path7 = __toESM(require("path"));
+var import_url = require("url");
+var dynamicImport = new Function("u", "return import(u)");
+var verifyCommand = new import_commander6.Command("verify").description(
+  "Server-render every template against fixtures to catch runtime crashes"
+).option("-d, --dir <directory>", "Theme directory", ".").option("--locale <code>", "Render under a locale (e.g. `ar` for RTL)").option("--no-build", "Verify the existing dist/ without rebuilding").action(
+  async (options) => {
+    const dir = path7.resolve(process.cwd(), options.dir);
+    if (options.build !== false) {
+      console.log("Building theme (SSR bundle)\u2026");
+      try {
+        (0, import_child_process5.execSync)("npx vite build", { cwd: dir, stdio: "inherit" });
+      } catch {
+        console.error("Build failed");
+        process.exit(1);
+      }
+    }
+    const serverBundle = path7.join(dir, "dist", "theme.server.js");
+    if (!(0, import_fs.existsSync)(serverBundle)) {
+      console.error(
+        "No dist/theme.server.js \u2014 this theme is client-only and can't be render-verified. Export `createApp` via defineThemeEntry() and build with federate:true (SDK >= 0.3)."
+      );
+      process.exit(1);
+    }
+    const requireFromTheme = (0, import_module.createRequire)(path7.join(dir, "package.json"));
+    let harness;
+    try {
+      const verifyEntry = requireFromTheme.resolve("@numueg/theme-sdk/verify");
+      harness = await dynamicImport(
+        (0, import_url.pathToFileURL)(verifyEntry).href
+      );
+    } catch {
+      console.error(
+        "This theme's @numueg/theme-sdk has no `/verify` entry \u2014 upgrade @numueg/theme-sdk to a version that ships the render harness."
+      );
+      process.exit(1);
+    }
+    let serverModule;
+    try {
+      serverModule = await dynamicImport((0, import_url.pathToFileURL)(serverBundle).href);
+    } catch (e) {
+      console.error(
+        "Failed to load dist/theme.server.js:",
+        e instanceof Error ? e.message : String(e)
+      );
+      process.exit(1);
+    }
+    const def = serverModule.default;
+    const mod = {
+      createApp: serverModule.createApp ?? def?.createApp
+    };
+    const result = await harness.verifyThemeRender(mod, {
+      locale: options.locale
+    });
+    console.log("\nRender verification:");
+    for (const r of result.results) {
+      const mark = r.ok ? "\u2713" : "\u2718";
+      console.log(
+        `  ${mark} ${r.template}${r.ok ? ` (${r.htmlLength} chars)` : ""}`
+      );
+      if (!r.ok && r.error) {
+        console.log(`      ${String(r.error).split("\n")[0]}`);
+      }
+    }
+    if (!result.ok) {
+      console.error(
+        "\n\u2718 Render verification failed \u2014 fix the crashing templates above."
+      );
+      process.exit(1);
+    }
+    console.log("\n\u2713 All templates render against fixture data.");
+  }
+);
+
+// src/commands/push.ts
+var import_commander7 = require("commander");
+var path8 = __toESM(require("path"));
 var os2 = __toESM(require("os"));
 
 // src/utils/zipper.ts
@@ -1902,10 +2074,10 @@ var fs8 = __toESM(require("fs"));
 var import_archiver = __toESM(require("archiver"));
 async function zipDirectory(sourceDir, outputPath, optsOrLegacyExcludes = {}) {
   const opts = Array.isArray(optsOrLegacyExcludes) ? { excludePatterns: optsOrLegacyExcludes } : optsOrLegacyExcludes;
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const output = fs8.createWriteStream(outputPath);
     const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
-    output.on("close", () => resolve9(outputPath));
+    output.on("close", () => resolve10(outputPath));
     archive.on("error", reject);
     archive.pipe(output);
     const defaultExcludes = [
@@ -1927,7 +2099,7 @@ async function zipDirectory(sourceDir, outputPath, optsOrLegacyExcludes = {}) {
 }
 
 // src/commands/push.ts
-var pushCommand = new import_commander6.Command("push").description("Upload built theme to your developer account for testing").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
+var pushCommand = new import_commander7.Command("push").description("Upload built theme to your developer account for testing").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
   const config = loadConfig();
   if (!config.token) {
     console.error("Not logged in. Run: numu-theme login");
@@ -1940,7 +2112,7 @@ var pushCommand = new import_commander6.Command("push").description("Upload buil
     process.exit(1);
   }
   console.log("Packaging theme...");
-  const zipPath = path7.join(os2.tmpdir(), `numu-theme-${Date.now()}.zip`);
+  const zipPath = path8.join(os2.tmpdir(), `numu-theme-${Date.now()}.zip`);
   await zipDirectory(options.dir, zipPath);
   console.log("Uploading...");
   const res = await uploadFile("/themes/upload", zipPath);
@@ -1961,11 +2133,11 @@ Push failed (${res.status}): ${JSON.stringify(res.data)}`);
 });
 
 // src/commands/submit.ts
-var import_commander7 = require("commander");
-var path8 = __toESM(require("path"));
+var import_commander8 = require("commander");
+var path9 = __toESM(require("path"));
 var os3 = __toESM(require("os"));
 var fs9 = __toESM(require("fs"));
-var submitCommand = new import_commander7.Command("submit").description("Submit theme to the NUMU Marketplace for review").option("-d, --dir <directory>", "Theme directory", ".").requiredOption(
+var submitCommand = new import_commander8.Command("submit").description("Submit theme to the NUMU Marketplace for review").option("-d, --dir <directory>", "Theme directory", ".").requiredOption(
   "-t, --theme-id <theme_id>",
   "Marketplace theme listing UUID (create via dashboard first)"
 ).option("-n, --notes <notes>", "Release notes for this version").action(
@@ -1988,7 +2160,7 @@ var submitCommand = new import_commander7.Command("submit").description("Submit
       console.log("\nWarnings:");
       result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
     }
-    const themeJsonPath = path8.join(options.dir, "theme.json");
+    const themeJsonPath = path9.join(options.dir, "theme.json");
     let version;
     try {
       const tj = JSON.parse(fs9.readFileSync(themeJsonPath, "utf-8"));
@@ -2002,7 +2174,7 @@ var submitCommand = new import_commander7.Command("submit").description("Submit
       process.exit(1);
     }
     console.log("\nPackaging theme source...");
-    const zipPath = path8.join(
+    const zipPath = path9.join(
       os3.tmpdir(),
       `numu-theme-submit-${Date.now()}.zip`
     );
@@ -2055,12 +2227,12 @@ Submission failed (${submitRes.status}): ${JSON.stringify(submitRes.data)}`
 );
 
 // src/commands/install.ts
-var import_commander8 = require("commander");
-var import_child_process5 = require("child_process");
-var path9 = __toESM(require("path"));
+var import_commander9 = require("commander");
+var import_child_process6 = require("child_process");
+var path10 = __toESM(require("path"));
 var os4 = __toESM(require("os"));
 var fs10 = __toESM(require("fs"));
-var installCommand = new import_commander8.Command("install").description(
+var installCommand = new import_commander9.Command("install").description(
   "Build + upload + install a theme directly on a store you own (bypasses marketplace review)"
 ).option("-d, --dir <directory>", "Theme directory", ".").requiredOption(
   "-t, --theme-id <theme_id>",
@@ -2098,7 +2270,7 @@ var installCommand = new import_commander8.Command("install").description(
       process.exit(1);
     }
     result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
-    const themeJsonPath = path9.join(options.dir, "theme.json");
+    const themeJsonPath = path10.join(options.dir, "theme.json");
     let baseVersion;
     try {
       const tj = JSON.parse(fs10.readFileSync(themeJsonPath, "utf-8"));
@@ -2117,7 +2289,7 @@ var installCommand = new import_commander8.Command("install").description(
     console.log(`  install tag:  ${version}`);
     console.log("Building locally (so worker can skip npm install)...");
     try {
-      (0, import_child_process5.execSync)("npm run build", {
+      (0, import_child_process6.execSync)("npm run build", {
         cwd: options.dir,
         stdio: "inherit",
         env: { ...process.env, NODE_ENV: "production" }
@@ -2128,7 +2300,7 @@ var installCommand = new import_commander8.Command("install").description(
       );
       process.exit(1);
     }
-    const distEntry = path9.join(options.dir, "dist", "theme.js");
+    const distEntry = path10.join(options.dir, "dist", "theme.js");
     if (!fs10.existsSync(distEntry)) {
       console.error(
         "\nBuild completed but dist/theme.js is missing. Check vite.config.ts entry / output filename."
@@ -2136,7 +2308,7 @@ var installCommand = new import_commander8.Command("install").description(
       process.exit(1);
     }
     console.log("Packaging source + dist...");
-    const zipPath = path9.join(
+    const zipPath = path10.join(
       os4.tmpdir(),
       `numu-theme-install-${Date.now()}.zip`
     );
@@ -2250,9 +2422,9 @@ Timed out waiting for build (${options.pollTimeout}s). Run \`numu-theme status -
 );
 
 // src/commands/login.ts
-var import_commander9 = require("commander");
+var import_commander10 = require("commander");
 var import_inquirer = __toESM(require("inquirer"));
-var loginCommand = new import_commander9.Command("login").description("Authenticate with the NUMU API").option("--token <token>", "API token (skip interactive login)").option("--api-url <url>", "Custom API URL").action(async (options) => {
+var loginCommand = new import_commander10.Command("login").description("Authenticate with the NUMU API").option("--token <token>", "API token (skip interactive login)").option("--api-url <url>", "Custom API URL").action(async (options) => {
   if (options.apiUrl) {
     saveConfig({ api_url: options.apiUrl });
     console.log(`API URL set to: ${options.apiUrl}`);
@@ -2299,8 +2471,8 @@ Login failed: ${err.message}`);
 });
 
 // src/commands/status.ts
-var import_commander10 = require("commander");
-var statusCommand = new import_commander10.Command("status").description("Poll the status of a theme build or marketplace version").option("--build <build_id>", "Build ID returned by `numu-theme push`").option(
+var import_commander11 = require("commander");
+var statusCommand = new import_commander11.Command("status").description("Poll the status of a theme build or marketplace version").option("--build <build_id>", "Build ID returned by `numu-theme push`").option(
   "--version <version_id>",
   "Marketplace version ID returned by `numu-theme submit`"
 ).option("-w, --watch", "Poll until the build reaches a terminal state").option(
@@ -2427,13 +2599,13 @@ function formatBytes(n) {
 }
 
 // src/commands/doctor.ts
-var import_commander11 = require("commander");
+var import_commander12 = require("commander");
 var fs11 = __toESM(require("fs"));
-var path10 = __toESM(require("path"));
-var doctorCommand = new import_commander11.Command("doctor").description("Diagnose common dev-loop problems (run inside a theme directory)").option("-d, --dir <directory>", "Theme directory", ".").option("-p, --port <port>", "Expected dev server port", "5173").action(async (options) => {
+var path11 = __toESM(require("path"));
+var doctorCommand = new import_commander12.Command("doctor").description("Diagnose common dev-loop problems (run inside a theme directory)").option("-d, --dir <directory>", "Theme directory", ".").option("-p, --port <port>", "Expected dev server port", "5173").action(async (options) => {
   let issues = 0;
   let warnings = 0;
-  const themeDir = path10.resolve(options.dir);
+  const themeDir = path11.resolve(options.dir);
   function ok(line) {
     console.log(`  \x1B[32m\u2713\x1B[0m ${line}`);
   }
@@ -2446,8 +2618,8 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
     console.log(`  \x1B[31m\u2717\x1B[0m ${line}`);
   }
   console.log("\nProject");
-  const themeJsonPath = path10.join(themeDir, "theme.json");
-  const settingsPath = path10.join(themeDir, "settings_schema.json");
+  const themeJsonPath = path11.join(themeDir, "theme.json");
+  const settingsPath = path11.join(themeDir, "settings_schema.json");
   if (!fs11.existsSync(themeJsonPath)) {
     fail(`No theme.json found in ${themeDir}`);
     console.log(
@@ -2473,21 +2645,53 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
     "src/index.ts"
   ];
   const entry = entryCandidates.find(
-    (p) => fs11.existsSync(path10.join(themeDir, p))
+    (p) => fs11.existsSync(path11.join(themeDir, p))
   );
   if (!entry) {
     fail(`No entry point found (expected one of: ${entryCandidates.join(", ")})`);
   } else {
-    const src = fs11.readFileSync(path10.join(themeDir, entry), "utf-8");
-    const exportsMount = /\bexport\s+(?:async\s+)?function\s+mount\b/.test(src) || /\bexport\s+(?:const|let|var)\s+mount\b/.test(src) || /\bexport\s*\{[^}]*\bmount\b[^}]*\}/.test(src);
+    const src = fs11.readFileSync(path11.join(themeDir, entry), "utf-8");
+    const exportsMount = /\bexport\s+(?:async\s+)?function\s+mount\b/.test(src) || /\bexport\s+(?:const|let|var)\s+mount\b/.test(src) || /\bexport\s+(?:const|let|var)\s*\{[^}]*\bmount\b[^}]*\}/.test(src) || /\bexport\s*\{[^}]*\bmount\b[^}]*\}/.test(src);
     if (exportsMount) ok(`${entry} exports mount(el, props)`);
     else
       fail(
         `${entry} does NOT export mount(el, props) \u2014 BYOT host can't render this theme. See THEME_AUTHORING.md for the contract, or scaffold a fresh theme with \`numu-theme init\`.`
       );
+    const exportsCreateApp = /\bexport\s+(?:async\s+)?function\s+createApp\b/.test(src) || /\bexport\s+(?:const|let|var)\s+createApp\b/.test(src) || /\bexport\s+(?:const|let|var)\s*\{[^}]*\bcreateApp\b[^}]*\}/.test(src) || /\bexport\s*\{[^}]*\bcreateApp\b[^}]*\}/.test(src);
+    if (exportsCreateApp) ok(`${entry} exports createApp(ctx) \u2014 SSR-capable`);
+    else
+      warn(
+        `${entry} does not export createApp \u2014 theme renders client-only (no server-rendered first paint). Use defineThemeEntry from @numueg/theme-sdk \u2265 0.3 to export mount + createApp from one component.`
+      );
+  }
+  console.log("\nSSR toolchain");
+  try {
+    const pkg = JSON.parse(
+      fs11.readFileSync(path11.join(themeDir, "package.json"), "utf-8")
+    );
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const checkMinor = (name, minMinor) => {
+      const range = allDeps[name];
+      if (!range) {
+        warn(`${name} not in package.json \u2014 npm install it`);
+        return;
+      }
+      const m = /(\d+)\.(\d+)\./.exec(range);
+      if (m && Number(m[1]) === 0 && Number(m[2]) < minMinor) {
+        warn(
+          `${name}@${range} predates the SSR contract \u2014 bump to ^0.${minMinor}.0 for server rendering`
+        );
+      } else {
+        ok(`${name}@${range}`);
+      }
+    };
+    checkMinor("@numueg/theme-sdk", 3);
+    checkMinor("@numueg/theme-plugin", 3);
+  } catch {
+    warn("Could not read package.json to verify SDK/plugin versions");
   }
   console.log("\nLocales");
-  const localesDir = path10.join(themeDir, "locales");
+  const localesDir = path11.join(themeDir, "locales");
   if (!fs11.existsSync(localesDir)) {
     warn(
       "locales/ directory not found \u2014 `useTranslation` will fall through to keys. Add locales/en.default.json (required) and locales/ar.json (recommended for MENA stores)."
@@ -2504,14 +2708,14 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
     }
     for (const f of localeFiles) {
       try {
-        JSON.parse(fs11.readFileSync(path10.join(localesDir, f), "utf-8"));
+        JSON.parse(fs11.readFileSync(path11.join(localesDir, f), "utf-8"));
       } catch (err) {
         fail(`locales/${f} is not valid JSON: ${err.message}`);
       }
     }
   }
   console.log("\nAssets");
-  const assetsDir = path10.join(themeDir, "assets");
+  const assetsDir = path11.join(themeDir, "assets");
   if (!fs11.existsSync(assetsDir)) {
     warn(
       "assets/ directory not found \u2014 assetUrl() helpers will fall back to bare paths under /assets/. Create assets/ and put images, fonts, and JSON fixtures there for the plugin to copy with content-hashed filenames."
@@ -2532,13 +2736,13 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
       fs11.readFileSync(themeJsonPath, "utf-8")
     );
     const presets = themeJson.presets ?? {};
-    const sectionsDir = path10.join(themeDir, "src", "sections");
-    const schemaDir = path10.join(themeDir, "schemas", "sections");
+    const sectionsDir = path11.join(themeDir, "src", "sections");
+    const schemaDir = path11.join(themeDir, "schemas", "sections");
     const componentNames = fs11.existsSync(sectionsDir) ? new Set(
-      fs11.readdirSync(sectionsDir).filter((f) => /\.(tsx|ts|jsx|js)$/.test(f)).map((f) => path10.basename(f, path10.extname(f)).toLowerCase())
+      fs11.readdirSync(sectionsDir).filter((f) => /\.(tsx|ts|jsx|js)$/.test(f)).map((f) => path11.basename(f, path11.extname(f)).toLowerCase())
     ) : /* @__PURE__ */ new Set();
     const schemaNames = fs11.existsSync(schemaDir) ? new Set(
-      fs11.readdirSync(schemaDir).filter((f) => f.endsWith(".json")).map((f) => path10.basename(f, ".json").toLowerCase())
+      fs11.readdirSync(schemaDir).filter((f) => f.endsWith(".json")).map((f) => path11.basename(f, ".json").toLowerCase())
     ) : /* @__PURE__ */ new Set();
     let missingRefs = 0;
     for (const [presetName, presetVal] of Object.entries(presets)) {
@@ -2569,8 +2773,8 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
     warn(`Could not parse theme.json presets: ${err.message}`);
   }
   console.log("\nBuild");
-  const distJs = path10.join(themeDir, "dist", "theme.js");
-  const distCss = path10.join(themeDir, "dist", "theme.css");
+  const distJs = path11.join(themeDir, "dist", "theme.js");
+  const distCss = path11.join(themeDir, "dist", "theme.css");
   if (!fs11.existsSync(distJs)) {
     warn("dist/theme.js not found \u2014 run `numu-theme build` first");
   } else {
@@ -2586,6 +2790,16 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
   } else {
     ok("dist/theme.css present");
   }
+  const distServer = path11.join(themeDir, "dist", "theme.server.js");
+  if (fs11.existsSync(distServer)) {
+    ok(
+      `dist/theme.server.js (${(fs11.statSync(distServer).size / 1024).toFixed(1)} KB) \u2014 SSR artifact present`
+    );
+  } else if (fs11.existsSync(distJs)) {
+    warn(
+      "dist/theme.server.js not found \u2014 last build produced a client-only theme (plugin < 0.3, federate:false, or SSR pass failed)"
+    );
+  }
   console.log("\nAuth");
   const config = loadConfig();
   if (!config.token) {
@@ -2653,9 +2867,9 @@ var doctorCommand = new import_commander11.Command("doctor").description("Diagno
 });
 
 // src/commands/add-section.ts
-var import_commander12 = require("commander");
+var import_commander13 = require("commander");
 var fs12 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
+var path12 = __toESM(require("path"));
 
 // src/section-library/entries/hero-with-cta.ts
 var heroWithCta = {
@@ -3700,7 +3914,7 @@ function findEntry(slug) {
 }
 
 // src/commands/add-section.ts
-var addSectionCommand = new import_commander12.Command("add-section").description("Scaffold a new section (optionally from the built-in library)").argument("[name]", "Section slug (kebab-case, e.g. 'hero-banner')").option(
+var addSectionCommand = new import_commander13.Command("add-section").description("Scaffold a new section (optionally from the built-in library)").argument("[name]", "Section slug (kebab-case, e.g. 'hero-banner')").option(
   "--from-library <slug>",
   "Copy from the built-in section library (run with --list to see options)"
 ).option("--list", "List the built-in section library and exit").option("-d, --dir <directory>", "Theme directory", ".").action(
@@ -3721,8 +3935,8 @@ var addSectionCommand = new import_commander12.Command("add-section").descriptio
       );
       process.exit(1);
     }
-    const themeDir = path11.resolve(process.cwd(), options.dir);
-    if (!fs12.existsSync(path11.join(themeDir, "theme.json"))) {
+    const themeDir = path12.resolve(process.cwd(), options.dir);
+    if (!fs12.existsSync(path12.join(themeDir, "theme.json"))) {
       console.error(
         "No theme.json in this directory. Run from a theme project root."
       );
@@ -3758,14 +3972,14 @@ var addSectionCommand = new import_commander12.Command("add-section").descriptio
         ]
       };
     }
-    const componentPath = path11.join(themeDir, "src/sections", `${pascal}.tsx`);
+    const componentPath = path12.join(themeDir, "src/sections", `${pascal}.tsx`);
     ensureDirOf(componentPath);
     if (fs12.existsSync(componentPath)) {
       console.error(`Already exists: ${componentPath}`);
       process.exit(1);
     }
     fs12.writeFileSync(componentPath, componentSource);
-    const schemaPath = path11.join(themeDir, "schemas/sections", `${slug}.json`);
+    const schemaPath = path12.join(themeDir, "schemas/sections", `${slug}.json`);
     ensureDirOf(schemaPath);
     fs12.writeFileSync(schemaPath, JSON.stringify(schemaJson, null, 2));
     tryWireMain(themeDir, slug, pascal);
@@ -3789,7 +4003,7 @@ function humanize(slug) {
   return slug.split("-").filter(Boolean).map((p) => p[0].toUpperCase() + p.slice(1)).join(" ");
 }
 function ensureDirOf(p) {
-  fs12.mkdirSync(path11.dirname(p), { recursive: true });
+  fs12.mkdirSync(path12.dirname(p), { recursive: true });
 }
 function emptySectionStub(pascal) {
   return `import type { SectionProps } from "@numueg/theme-sdk";
@@ -3807,7 +4021,7 @@ export default function ${pascal}({ settings }: SectionProps) {
 `;
 }
 function tryWireMain(themeDir, slug, pascal) {
-  const mainPath = path11.join(themeDir, "src/main.tsx");
+  const mainPath = path12.join(themeDir, "src/main.tsx");
   if (!fs12.existsSync(mainPath)) return;
   const src = fs12.readFileSync(mainPath, "utf-8");
   if (src.includes(`./sections/${pascal}`)) return;
@@ -3848,7 +4062,7 @@ function tryWireMain(themeDir, slug, pascal) {
   fs12.writeFileSync(mainPath, lines.join("\n"));
 }
 function tryAddToHomePreset(themeDir, slug) {
-  const themeJsonPath = path11.join(themeDir, "theme.json");
+  const themeJsonPath = path12.join(themeDir, "theme.json");
   if (!fs12.existsSync(themeJsonPath)) return;
   let parsed;
   try {
@@ -3875,19 +4089,19 @@ function tryAddToHomePreset(themeDir, slug) {
 }
 
 // src/commands/add-block.ts
-var import_commander13 = require("commander");
+var import_commander14 = require("commander");
 var fs13 = __toESM(require("fs"));
-var path12 = __toESM(require("path"));
-var addBlockCommand = new import_commander13.Command("add-block").description("Scaffold a new block inside an existing section schema").argument("<section>", "Section type, e.g. 'product_grid'").argument("<name>", "Block type, e.g. 'feature'").option("-d, --dir <directory>", "Theme directory", ".").action((section, name, options) => {
-  const themeDir = path12.resolve(options.dir);
-  if (!fs13.existsSync(path12.join(themeDir, "theme.json"))) {
+var path13 = __toESM(require("path"));
+var addBlockCommand = new import_commander14.Command("add-block").description("Scaffold a new block inside an existing section schema").argument("<section>", "Section type, e.g. 'product_grid'").argument("<name>", "Block type, e.g. 'feature'").option("-d, --dir <directory>", "Theme directory", ".").action((section, name, options) => {
+  const themeDir = path13.resolve(options.dir);
+  if (!fs13.existsSync(path13.join(themeDir, "theme.json"))) {
     console.error(`No theme.json in ${themeDir}.`);
     process.exit(1);
   }
   const sectionSnake = toSnakeCase(section);
   const blockSnake = toSnakeCase(name);
   const blockHuman = humanize2(toPascalCase(name));
-  const schemaPath = path12.join(
+  const schemaPath = path13.join(
     themeDir,
     "schemas",
     "sections",
@@ -3930,7 +4144,7 @@ var addBlockCommand = new import_commander13.Command("add-block").description("S
     `
 \x1B[32m\u2713\x1B[0m Added block "${blockSnake}" to section "${sectionSnake}":`,
     `
-  - ${path12.relative(themeDir, schemaPath)}`,
+  - ${path13.relative(themeDir, schemaPath)}`,
     `
 
 \x1B[33m\u26A0\x1B[0m The section component should iterate \`blockOrder\` and render each block by type.`,
@@ -3962,17 +4176,17 @@ function humanize2(name) {
 }
 
 // src/commands/pull.ts
-var import_commander14 = require("commander");
+var import_commander15 = require("commander");
 var fs14 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
+var path14 = __toESM(require("path"));
 var https2 = __toESM(require("https"));
 var http2 = __toESM(require("http"));
 async function downloadToFile(url, dest) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const client = url.startsWith("https:") ? https2 : http2;
     const req = client.get(url, (res) => {
       if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        downloadToFile(res.headers.location, dest).then(resolve9, reject);
+        downloadToFile(res.headers.location, dest).then(resolve10, reject);
         return;
       }
       if (res.statusCode !== 200) {
@@ -3981,7 +4195,7 @@ async function downloadToFile(url, dest) {
       }
       const out = fs14.createWriteStream(dest);
       res.pipe(out);
-      out.on("finish", () => out.close(() => resolve9()));
+      out.on("finish", () => out.close(() => resolve10()));
       out.on("error", reject);
     });
     req.on("error", reject);
@@ -4000,7 +4214,7 @@ async function unzip(zipPath, targetDir) {
     });
   }
 }
-var pullCommand = new import_commander14.Command("pull").description("Download a published theme's source to a local directory").argument("<theme-id>", "Theme slug or UUID").option(
+var pullCommand = new import_commander15.Command("pull").description("Download a published theme's source to a local directory").argument("<theme-id>", "Theme slug or UUID").option(
   "-d, --dir <directory>",
   "Target directory (default: ./<theme-id>)"
 ).option(
@@ -4008,7 +4222,7 @@ var pullCommand = new import_commander14.Command("pull").description("Download a
   "Specific version_string (default: latest)"
 ).option("--force", "Overwrite the target directory if it exists").action(
   async (themeId, options) => {
-    const targetDir = path13.resolve(options.dir || themeId);
+    const targetDir = path14.resolve(options.dir || themeId);
     if (fs14.existsSync(targetDir) && !options.force) {
       const isEmpty = fs14.readdirSync(targetDir).length === 0;
       if (!isEmpty) {
@@ -4055,7 +4269,7 @@ var pullCommand = new import_commander14.Command("pull").description("Download a
       process.exit(1);
     }
     console.log(`Downloading ${theme.name || themeId} ${target.version_string}\u2026`);
-    const tmpZip = path13.join(
+    const tmpZip = path14.join(
       require("os").tmpdir(),
       `numu-pull-${process.pid}-${Date.now()}.zip`
     );
@@ -4072,28 +4286,28 @@ var pullCommand = new import_commander14.Command("pull").description("Download a
     console.log(`\u2714 Pulled ${theme.slug || themeId}@${target.version_string} into ${targetDir}`);
     console.log("");
     console.log("Next steps:");
-    console.log(`  cd ${path13.relative(process.cwd(), targetDir) || "."}`);
+    console.log(`  cd ${path14.relative(process.cwd(), targetDir) || "."}`);
     console.log("  npm install");
     console.log("  numu-theme dev");
   }
 );
 
 // src/commands/delete.ts
-var import_commander15 = require("commander");
+var import_commander16 = require("commander");
 var readline = __toESM(require("readline"));
 async function confirm(prompt) {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     rl.question(`${prompt} [y/N] `, (answer) => {
       rl.close();
-      resolve9(/^y(es)?$/i.test(answer.trim()));
+      resolve10(/^y(es)?$/i.test(answer.trim()));
     });
   });
 }
-var deleteCommand = new import_commander15.Command("delete").description("Delete a theme or a specific version from the marketplace").argument("<theme-id>", "Theme slug or UUID").option("-v, --version <version>", "Delete this version only (default: whole theme)").option("-y, --yes", "Skip the confirmation prompt").action(
+var deleteCommand = new import_commander16.Command("delete").description("Delete a theme or a specific version from the marketplace").argument("<theme-id>", "Theme slug or UUID").option("-v, --version <version>", "Delete this version only (default: whole theme)").option("-y, --yes", "Skip the confirmation prompt").action(
   async (themeId, options) => {
     const isVersion = Boolean(options.version);
     const scope = isVersion ? `version ${options.version} of ${themeId}` : `the entire theme ${themeId}`;
@@ -4106,8 +4320,8 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
         return;
       }
     }
-    const path15 = isVersion ? `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions/${encodeURIComponent(options.version)}` : `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`;
-    const res = await apiRequest("DELETE", path15);
+    const path16 = isVersion ? `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions/${encodeURIComponent(options.version)}` : `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`;
+    const res = await apiRequest("DELETE", path16);
     if (res.status === 200 || res.status === 204) {
       console.log(`\u2714 Deleted ${scope}.`);
       return;
@@ -4126,9 +4340,9 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
 );
 
 // src/commands/migrate.ts
-var import_commander16 = require("commander");
+var import_commander17 = require("commander");
 var fs15 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
+var path15 = __toESM(require("path"));
 var import_chalk = __toESM(require("chalk"));
 var V2_HOOK_PATTERNS = [
   {
@@ -4226,14 +4440,14 @@ function findSectionFiles(dir) {
   if (!fs15.existsSync(dir)) return [];
   const out = [];
   for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
-    const full = path14.join(dir, entry.name);
+    const full = path15.join(dir, entry.name);
     if (entry.isDirectory()) out.push(...findSectionFiles(full));
     else if (entry.isFile() && /\.(tsx|ts)$/.test(entry.name)) out.push(full);
   }
   return out;
 }
 function sectionTypeFromFilename(filename) {
-  const base = path14.basename(filename).replace(/\.(tsx|ts)$/, "");
+  const base = path15.basename(filename).replace(/\.(tsx|ts)$/, "");
   return base.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9-]+/g, "-").toLowerCase();
 }
 function makeV2Bridge() {
@@ -4733,7 +4947,7 @@ function makeTemplates() {
 `
   };
 }
-var migrateCommand = new import_commander16.Command("migrate").description("Scaffold a V3 theme project from a V2 theme directory").argument(
+var migrateCommand = new import_commander17.Command("migrate").description("Scaffold a V3 theme project from a V2 theme directory").argument(
   "<v2-path>",
   "Path to the V2 theme directory (e.g. ../numu-egyptian-bazaar/src/themes/empire)"
 ).option(
@@ -4744,15 +4958,15 @@ var migrateCommand = new import_commander16.Command("migrate").description("Scaf
   "Override the display name (default: title-cased v2 id)"
 ).action(
   async (v2Path, options) => {
-    const absV2Path = path14.resolve(process.cwd(), v2Path);
+    const absV2Path = path15.resolve(process.cwd(), v2Path);
     if (!fs15.existsSync(absV2Path) || !fs15.statSync(absV2Path).isDirectory()) {
       console.error(import_chalk.default.red(`V2 path does not exist or is not a directory: ${absV2Path}`));
       process.exit(1);
     }
-    const v2Id = path14.basename(absV2Path).toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    const v2Id = path15.basename(absV2Path).toLowerCase().replace(/[^a-z0-9-]/g, "-");
     const themeId = `${v2Id}-v3`;
     const displayName = options.name ?? v2Id.charAt(0).toUpperCase() + v2Id.slice(1).replace(/-/g, " ") + " (V3)";
-    const outDir = path14.resolve(
+    const outDir = path15.resolve(
       process.cwd(),
       options.out ?? `${v2Id}-engine-V3`
     );
@@ -4773,25 +4987,25 @@ Migrating V2 \u2192 V3:`));
       "schemas/blocks",
       "templates"
     ]) {
-      fs15.mkdirSync(path14.join(outDir, d), { recursive: true });
+      fs15.mkdirSync(path15.join(outDir, d), { recursive: true });
     }
     fs15.writeFileSync(
-      path14.join(outDir, "src/v2-bridge", "index.tsx"),
+      path15.join(outDir, "src/v2-bridge", "index.tsx"),
       makeV2Bridge()
     );
-    const v2Styles = path14.join(absV2Path, "styles.css");
+    const v2Styles = path15.join(absV2Path, "styles.css");
     if (fs15.existsSync(v2Styles)) {
-      fs15.copyFileSync(v2Styles, path14.join(outDir, "styles.css"));
+      fs15.copyFileSync(v2Styles, path15.join(outDir, "styles.css"));
       console.log(import_chalk.default.green("  \u2713 Copied styles.css"));
     } else {
       fs15.writeFileSync(
-        path14.join(outDir, "styles.css"),
+        path15.join(outDir, "styles.css"),
         `/* ${displayName} styles */
 `
       );
       console.log(import_chalk.default.yellow("  \u26A0 No styles.css found \u2014 created an empty one"));
     }
-    const v2SectionsDir = path14.join(absV2Path, "sections");
+    const v2SectionsDir = path15.join(absV2Path, "sections");
     const sectionFiles = fs15.existsSync(v2SectionsDir) ? findSectionFiles(v2SectionsDir) : [];
     const sectionTypes = [];
     const allNotes = [];
@@ -4802,18 +5016,18 @@ Migrating V2 \u2192 V3:`));
       const v2Source = fs15.readFileSync(file, "utf-8");
       const notes = migrationNotesFor(v2Source);
       allNotes.push({ file, type, notes });
-      const relativeV2 = path14.relative(process.cwd(), file);
+      const relativeV2 = path15.relative(process.cwd(), file);
       const header = adapterCommentBlock(notes, relativeV2);
       const rewritten = rewriteV2Imports(v2Source);
       const ported = `${header}
 
 ${rewritten}`;
       fs15.writeFileSync(
-        path14.join(outDir, "src/sections", `${type}.tsx`),
+        path15.join(outDir, "src/sections", `${type}.tsx`),
         ported
       );
       fs15.writeFileSync(
-        path14.join(outDir, "schemas/sections", `${type}.json`),
+        path15.join(outDir, "schemas/sections", `${type}.json`),
         JSON.stringify(
           {
             type,
@@ -4827,38 +5041,38 @@ ${rewritten}`;
     }
     console.log(import_chalk.default.green(`  \u2713 Ported ${sectionTypes.length} section file(s)`));
     fs15.writeFileSync(
-      path14.join(outDir, "theme.json"),
+      path15.join(outDir, "theme.json"),
       JSON.stringify(makeThemeJson(themeId, displayName, sectionTypes), null, 2)
     );
     fs15.writeFileSync(
-      path14.join(outDir, "settings_schema.json"),
+      path15.join(outDir, "settings_schema.json"),
       JSON.stringify(makeSettingsSchema(), null, 2)
     );
     fs15.writeFileSync(
-      path14.join(outDir, "src/main.tsx"),
+      path15.join(outDir, "src/main.tsx"),
       makeMainTsx(themeId, displayName, sectionTypes)
     );
     fs15.writeFileSync(
-      path14.join(outDir, "vite.config.ts"),
+      path15.join(outDir, "vite.config.ts"),
       makeViteConfig()
     );
     fs15.writeFileSync(
-      path14.join(outDir, "package.json"),
+      path15.join(outDir, "package.json"),
       JSON.stringify(makePackageJson(themeId, displayName), null, 2)
     );
     fs15.writeFileSync(
-      path14.join(outDir, "tsconfig.json"),
+      path15.join(outDir, "tsconfig.json"),
       JSON.stringify(makeTsConfig(), null, 2)
     );
     fs15.writeFileSync(
-      path14.join(outDir, "index.html"),
+      path15.join(outDir, "index.html"),
       makeIndexHtml(displayName)
     );
     const tpl = makeTemplates();
-    fs15.writeFileSync(path14.join(outDir, "templates/error.html"), tpl.error);
-    fs15.writeFileSync(path14.join(outDir, "templates/loading.html"), tpl.loading);
+    fs15.writeFileSync(path15.join(outDir, "templates/error.html"), tpl.error);
+    fs15.writeFileSync(path15.join(outDir, "templates/loading.html"), tpl.loading);
     fs15.writeFileSync(
-      path14.join(outDir, ".gitignore"),
+      path15.join(outDir, ".gitignore"),
       "node_modules/\ndist/\n.DS_Store\n"
     );
     console.log(import_chalk.default.green("  \u2713 Wrote scaffold files\n"));
@@ -4879,7 +5093,7 @@ ${rewritten}`;
       console.log();
     }
     console.log(import_chalk.default.bold("\nNext steps:"));
-    console.log(`  ${import_chalk.default.cyan("cd")} ${path14.relative(process.cwd(), outDir)}`);
+    console.log(`  ${import_chalk.default.cyan("cd")} ${path15.relative(process.cwd(), outDir)}`);
     console.log(`  ${import_chalk.default.cyan("npm install")}`);
     console.log(`  ${import_chalk.default.cyan("npm run dev")}                ${import_chalk.default.dim("# dev preview on :5173")}`);
     console.log(`  ${import_chalk.default.cyan("npx numu-theme build")}       ${import_chalk.default.dim("# validate + build")}`);
@@ -4891,13 +5105,14 @@ ${import_chalk.default.dim("Open each src/sections/*.tsx and follow the ADAPTER
 );
 
 // src/index.ts
-var program = new import_commander17.Command();
+var program = new import_commander18.Command();
 program.name("numu-theme").description("CLI for developing, validating, building, and publishing NUMU themes").version("0.1.0");
 program.addCommand(initCommand);
 program.addCommand(devCommand);
 program.addCommand(checkCommand);
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
+program.addCommand(verifyCommand);
 program.addCommand(pushCommand);
 program.addCommand(submitCommand);
 program.addCommand(installCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numueg/theme-cli",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "CLI for developing, validating, building, linting, and publishing NUMU storefront themes",
   "keywords": [
     "numu",