@numueg/theme-cli 0.1.0 → 0.4.0

package/dist/index.js

@@ -591,13 +591,293 @@ var init_manifest_required_fields = __esm({
   }
 });
 
+// src/lint/rules/contrast-hint.ts
+var contrast_hint_exports = {};
+__export(contrast_hint_exports, {
+  default: () => contrast_hint_default
+});
+function hexToRgb(hex) {
+  let h = hex.replace("#", "").trim();
+  if (h.length === 3) {
+    h = h.split("").map((c) => c + c).join("");
+  }
+  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return null;
+  const n = parseInt(h, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function relativeLuminance([r, g, b]) {
+  const a = [r, g, b].map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * a[0] + 0.7152 * a[1] + 0.0722 * a[2];
+}
+function contrastRatio(c1, c2) {
+  const l1 = relativeLuminance(c1);
+  const l2 = relativeLuminance(c2);
+  const hi = Math.max(l1, l2);
+  const lo = Math.min(l1, l2);
+  return (hi + 0.05) / (lo + 0.05);
+}
+var rule11, contrast_hint_default;
+var init_contrast_hint = __esm({
+  "src/lint/rules/contrast-hint.ts"() {
+    "use strict";
+    rule11 = {
+      id: "contrast-hint",
+      description: "Co-located color/background hex pairs should meet WCAG 4.5:1 contrast",
+      check(ctx) {
+        const issues = [];
+        const css = ctx.styles;
+        if (!css) return issues;
+        const blockRe = /([^{}]*)\{([^{}]*)\}/g;
+        let m;
+        while ((m = blockRe.exec(css)) !== null) {
+          const rawSelector = m[1].trim().split("\n").pop()?.trim() || m[1].trim();
+          const body = m[2];
+          const colorM = body.match(/(?:^|[;{\s])color:\s*(#[0-9a-fA-F]{3,6})\b/);
+          const bgM = body.match(
+            /background(?:-color)?:\s*(#[0-9a-fA-F]{3,6})\b/
+          );
+          if (!colorM || !bgM) continue;
+          const fg = hexToRgb(colorM[1]);
+          const bg = hexToRgb(bgM[1]);
+          if (!fg || !bg) continue;
+          const ratio = contrastRatio(fg, bg);
+          if (ratio < 4.5) {
+            const line = css.slice(0, m.index).split("\n").length;
+            issues.push({
+              rule: rule11.id,
+              severity: "warning",
+              file: "styles.css",
+              line,
+              message: `Low contrast ${ratio.toFixed(2)}:1 for "${rawSelector}" (${colorM[1]} on ${bgM[1]}).`,
+              suggestion: ratio >= 3 ? `Meets 3:1 (OK for large text \u226524px/19px-bold) but not the 4.5:1 body-text minimum.` : `Below WCAG 4.5:1 \u2014 darken/lighten one color, or drive both from a color_scheme so merchants control contrast.`
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    contrast_hint_default = rule11;
+  }
+});
+
+// src/lint/rules/touch-target.ts
+var touch_target_exports = {};
+__export(touch_target_exports, {
+  default: () => touch_target_default
+});
+var INTERACTIVE, DIM_PROPS, rule12, touch_target_default;
+var init_touch_target = __esm({
+  "src/lint/rules/touch-target.ts"() {
+    "use strict";
+    INTERACTIVE = /(^|[\s,>+~])(button|a|\.btn\b|\[role=["']?button["']?\]|input\[type=["']?(?:button|submit|reset)["']?\])/i;
+    DIM_PROPS = ["width", "height", "min-width", "min-height"];
+    rule12 = {
+      id: "touch-target",
+      description: "Interactive targets should be \u2265 24\xD724px (WCAG 2.5.8)",
+      check(ctx) {
+        const issues = [];
+        const css = ctx.styles;
+        if (!css) return issues;
+        const blockRe = /([^{}]*)\{([^{}]*)\}/g;
+        let m;
+        while ((m = blockRe.exec(css)) !== null) {
+          const rawSelector = m[1].trim().split("\n").pop()?.trim() || m[1].trim();
+          if (rawSelector.includes("::")) continue;
+          if (!INTERACTIVE.test(rawSelector)) continue;
+          const body = m[2];
+          for (const prop of DIM_PROPS) {
+            const pm = body.match(
+              new RegExp(`(?:^|[;{\\s])${prop}:\\s*([0-9.]+)px\\b`)
+            );
+            if (!pm) continue;
+            const px = parseFloat(pm[1]);
+            if (px > 0 && px < 24) {
+              const line = css.slice(0, m.index).split("\n").length;
+              issues.push({
+                rule: rule12.id,
+                severity: "warning",
+                file: "styles.css",
+                line,
+                message: `Interactive "${rawSelector}" sets ${prop}: ${px}px (< 24px touch target).`,
+                suggestion: `Give clickable elements a \u226524\xD724px hit area (min-width/min-height: 24px or adequate padding).`
+              });
+              break;
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    touch_target_default = rule12;
+  }
+});
+
+// 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_commander16 = require("commander");
+var import_commander18 = require("commander");
 
 // src/commands/init.ts
 var import_commander = require("commander");
+var import_child_process = require("child_process");
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
+function detectAuthor() {
+  const git = (args) => {
+    try {
+      return (0, import_child_process.execSync)(`git config ${args}`, {
+        stdio: ["ignore", "pipe", "ignore"]
+      }).toString().trim();
+    } catch {
+      return "";
+    }
+  };
+  const name = git("user.name");
+  const email = git("user.email");
+  if (name && email) return `${name} <${email}>`;
+  if (name) return name;
+  return "Theme Author";
+}
 var initCommand = new import_commander.Command("init").description("Scaffold a new NUMU theme project").argument("<name>", "Theme name").option("--template <template>", "Starter template", "basic").action(async (name, _options) => {
   const dir = path.resolve(process.cwd(), name);
   if (fs.existsSync(dir)) {
@@ -620,7 +900,7 @@ var initCommand = new import_commander.Command("init").description("Scaffold a n
       {
         id: name.toLowerCase().replace(/[^a-z0-9-]/g, "-"),
         name,
-        author: "",
+        author: detectAuthor(),
         version: "0.1.0",
         layout: "single-column",
         description: `${name} NUMU theme`,
@@ -771,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>
@@ -822,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(
@@ -961,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(
@@ -1020,10 +1199,10 @@ export default defineConfig({
           build: "numu-theme build",
           check: "numu-theme check"
         },
-        dependencies: { "@numueg/theme-sdk": "^0.1.0" },
+        dependencies: { "@numueg/theme-sdk": "^0.3.0" },
         devDependencies: {
-          "@numueg/theme-cli": "^0.1.0",
-          "@numueg/theme-plugin": "^0.1.0",
+          "@numueg/theme-cli": "^0.3.0",
+          "@numueg/theme-plugin": "^0.3.0",
           "@vitejs/plugin-react": "^4.3.0",
           vite: "^6.0.0",
           typescript: "^5.8.0",
@@ -1056,20 +1235,27 @@ Next steps:
 
 // src/commands/dev.ts
 var import_commander2 = require("commander");
-var import_child_process = require("child_process");
+var import_child_process2 = require("child_process");
 
 // src/utils/config.ts
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 var os = __toESM(require("os"));
-var RC_FILE = path2.join(os.homedir(), ".numurc");
+function configHome() {
+  const override = process.env.NUMU_HOME;
+  if (override && override.length > 0) return override;
+  return os.homedir();
+}
+function rcFile() {
+  return path2.join(configHome(), ".numurc");
+}
 function loadConfig() {
   const config = {
     api_url: process.env.NUMU_API_URL || "https://api.numu.io/api/v1"
   };
-  if (fs2.existsSync(RC_FILE)) {
+  if (fs2.existsSync(rcFile())) {
     try {
-      const rc = JSON.parse(fs2.readFileSync(RC_FILE, "utf-8"));
+      const rc = JSON.parse(fs2.readFileSync(rcFile(), "utf-8"));
       if (rc.token) config.token = rc.token;
       if (rc.api_url) config.api_url = rc.api_url;
       if (rc.store_id) config.store_id = rc.store_id;
@@ -1082,16 +1268,16 @@ function loadConfig() {
 }
 function saveConfig(updates) {
   let existing = {};
-  if (fs2.existsSync(RC_FILE)) {
+  if (fs2.existsSync(rcFile())) {
     try {
-      existing = JSON.parse(fs2.readFileSync(RC_FILE, "utf-8"));
+      existing = JSON.parse(fs2.readFileSync(rcFile(), "utf-8"));
     } catch {
     }
   }
   const merged = { ...existing, ...updates };
-  fs2.writeFileSync(RC_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+  fs2.writeFileSync(rcFile(), JSON.stringify(merged, null, 2), { mode: 384 });
   try {
-    fs2.chmodSync(RC_FILE, 384);
+    fs2.chmodSync(rcFile(), 384);
   } catch {
   }
 }
@@ -1126,12 +1312,12 @@ function assertHttpsOrLocalhost(urlStr) {
   }
   throw new Error(`Unsupported protocol: ${url.protocol}`);
 }
-async function apiRequest(method, path14, body) {
+async function apiRequest(method, path16, body) {
   const config = loadConfig();
-  const url = assertHttpsOrLocalhost(`${config.api_url}${path14}`);
+  const url = assertHttpsOrLocalhost(`${config.api_url}${path16}`);
   const isHttps = url.protocol === "https:";
   const transport = isHttps ? https : http;
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve10, reject) => {
     const headers = {};
     if (config.token) headers["Authorization"] = `Bearer ${config.token}`;
     let postData;
@@ -1153,7 +1339,7 @@ async function apiRequest(method, path14, body) {
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve7({
+          resolve10({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1186,7 +1372,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((resolve7, reject) => {
+  return new Promise((resolve10, reject) => {
     const headers = {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
       "Content-Length": String(fullBody.byteLength)
@@ -1209,7 +1395,7 @@ Content-Type: application/zip\r
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve7({
+          resolve10({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1265,11 +1451,11 @@ var devCommand = new import_commander2.Command("dev").description("Start local d
     console.log(
       `Starting Vite on ${options.expose ? "0.0.0.0" : "localhost"}:${options.port}...`
     );
-    const child = (0, import_child_process.spawn)("npx", args, { stdio: "inherit", shell: true });
+    const child = (0, import_child_process2.spawn)("npx", args, { stdio: "inherit", shell: true });
     let watcher = null;
     if (options.watch) {
       console.log("Starting bundle watcher (vite build --watch)...");
-      watcher = (0, import_child_process.spawn)(
+      watcher = (0, import_child_process2.spawn)(
         "npx",
         ["vite", "build", "--watch", "--mode", "development"],
         { stdio: "inherit", shell: true }
@@ -1295,6 +1481,7 @@ var devCommand = new import_commander2.Command("dev").description("Start local d
 
 // src/commands/check.ts
 var import_commander3 = require("commander");
+var import_child_process3 = require("child_process");
 
 // src/utils/validator.ts
 var fs4 = __toESM(require("fs"));
@@ -1383,27 +1570,134 @@ 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 };
 }
 
 // src/commands/check.ts
-var checkCommand = new import_commander3.Command("check").description("Validate theme schemas and structure").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
-  console.log("Validating theme...");
-  const result = validateTheme(options.dir);
-  if (result.warnings.length > 0) {
-    console.log("\nWarnings:");
-    result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
-  }
-  if (result.errors.length > 0) {
-    console.log("\nErrors:");
-    result.errors.forEach((e) => console.log(`  \u2717 ${e}`));
-    console.log(`
+var checkCommand = new import_commander3.Command("check").description("Validate theme schemas and structure").option("-d, --dir <directory>", "Theme directory", ".").option(
+  "--lighthouse",
+  "Run a Lighthouse audit (performance + accessibility) \u2014 needs --url"
+).option(
+  "--url <url>",
+  "URL of the built theme on a seeded store to audit (e.g. http://localhost:3100/<store>)"
+).option("--perf <score>", "Minimum Lighthouse performance score (0-100)", "60").option(
+  "--a11y <score>",
+  "Minimum Lighthouse accessibility score (0-100)",
+  "90"
+).option(
+  "--strict",
+  "Exit non-zero when below thresholds (default: soft gate \u2014 report only)"
+).action(
+  async (options) => {
+    console.log("Validating theme...");
+    const result = validateTheme(options.dir);
+    if (result.warnings.length > 0) {
+      console.log("\nWarnings:");
+      result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
+    }
+    if (result.errors.length > 0) {
+      console.log("\nErrors:");
+      result.errors.forEach((e) => console.log(`  \u2717 ${e}`));
+      console.log(`
 Validation failed with ${result.errors.length} error(s)`);
+      process.exit(1);
+    }
+    console.log(`
+\u2713 Theme is valid (${result.warnings.length} warning(s))`);
+    if (options.lighthouse) {
+      runLighthouse(options);
+    }
+  }
+);
+function runLighthouse(options) {
+  if (!options.url) {
+    console.error(
+      "\n\u2718 --lighthouse requires --url <url> (a built theme on a seeded store)."
+    );
     process.exit(1);
   }
+  const perfMin = parseFloat(options.perf);
+  const a11yMin = parseFloat(options.a11y);
   console.log(`
-\u2713 Theme is valid (${result.warnings.length} warning(s))`);
-});
+Running Lighthouse against ${options.url} ...`);
+  let raw;
+  try {
+    raw = (0, import_child_process3.execSync)(
+      `npx --yes lighthouse "${options.url}" --output=json --output-path=stdout --only-categories=performance,accessibility --chrome-flags="--headless=new --no-sandbox --disable-gpu" --quiet --no-enable-error-reporting`,
+      { encoding: "utf-8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }
+    );
+  } catch (e) {
+    console.warn(
+      "\n\u26A0 Could not run Lighthouse (install it: `npm i -g lighthouse`, and ensure Chrome is available). Soft-skipping."
+    );
+    console.warn(`   ${String(e.message).split("\n")[0]}`);
+    return;
+  }
+  let report;
+  try {
+    report = JSON.parse(raw);
+  } catch {
+    console.warn("\n\u26A0 Lighthouse output was not parseable JSON; skipping gate.");
+    return;
+  }
+  const perf = Math.round((report.categories?.performance?.score ?? 0) * 100);
+  const a11y = Math.round((report.categories?.accessibility?.score ?? 0) * 100);
+  console.log(`  Performance:   ${perf}  (min ${perfMin})`);
+  console.log(`  Accessibility: ${a11y}  (min ${a11yMin})`);
+  const failed = perf < perfMin || a11y < a11yMin;
+  if (!failed) {
+    console.log("\u2713 Lighthouse thresholds met.");
+    return;
+  }
+  const msg = `Lighthouse below threshold (Perf ${perf}/${perfMin}, A11y ${a11y}/${a11yMin}).`;
+  if (options.strict) {
+    console.error(`\u2718 ${msg}`);
+    process.exit(1);
+  }
+  console.warn(`\u26A0 ${msg}  (soft gate \u2014 pass --strict to enforce.)`);
+}
 
 // src/commands/lint.ts
 var import_commander4 = require("commander");
@@ -1425,7 +1719,11 @@ async function runAllRules(themeDir, options) {
     () => Promise.resolve().then(() => (init_inline_color_literal(), inline_color_literal_exports)),
     () => Promise.resolve().then(() => (init_forbidden_script_tag(), forbidden_script_tag_exports)),
     () => 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_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_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) {
@@ -1440,14 +1738,14 @@ async function runAllRules(themeDir, options) {
       });
       continue;
     }
-    const rule11 = mod.default;
-    if (options.enabledRules && !options.enabledRules.has(rule11.id)) continue;
+    const rule15 = mod.default;
+    if (options.enabledRules && !options.enabledRules.has(rule15.id)) continue;
     try {
-      const ruleIssues = await rule11.check(ctx);
+      const ruleIssues = await rule15.check(ctx);
       for (const issue of ruleIssues) issues.push(issue);
     } catch (e) {
       issues.push({
-        rule: rule11.id,
+        rule: rule15.id,
         severity: "warning",
         message: `Rule crashed: ${e.message}`
       });
@@ -1467,6 +1765,7 @@ function buildContext(themeDir) {
   const blockSchemas = readSchemaDir(path4.join(themeDir, "schemas", "blocks"));
   const locales = readLocales(path4.join(themeDir, "locales"));
   const sources = readSources(themeDir);
+  const styles = readText(path4.join(themeDir, "styles.css"));
   return {
     themeDir,
     manifest,
@@ -1474,7 +1773,8 @@ function buildContext(themeDir) {
     sectionSchemas,
     blockSchemas,
     locales,
-    sources
+    sources,
+    styles
   };
 }
 function readJson(filePath, fallback) {
@@ -1485,6 +1785,14 @@ function readJson(filePath, fallback) {
     return fallback;
   }
 }
+function readText(filePath) {
+  if (!fs5.existsSync(filePath)) return "";
+  try {
+    return fs5.readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+}
 function readSchemaDir(dir) {
   const out = {};
   if (!fs5.existsSync(dir)) return out;
@@ -1592,45 +1900,171 @@ function groupByFile(issues) {
 
 // src/commands/build.ts
 var import_commander5 = require("commander");
-var import_child_process2 = require("child_process");
+var import_child_process4 = require("child_process");
 var fs7 = __toESM(require("fs"));
 var path6 = __toESM(require("path"));
-var buildCommand = new import_commander5.Command("build").description("Build the theme for production").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
-  console.log("Validating before build...");
-  const result = validateTheme(options.dir);
-  if (!result.valid) {
-    console.error("Validation failed. Fix errors before building.");
-    result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
-    process.exit(1);
-  }
-  console.log("Building theme...");
-  try {
-    (0, import_child_process2.execSync)("npx vite build", { cwd: options.dir, stdio: "inherit" });
-  } catch {
-    console.error("Build failed");
-    process.exit(1);
-  }
-  const distDir = path6.join(options.dir, "dist");
-  if (fs7.existsSync(distDir)) {
-    let totalSize = 0;
-    const files = fs7.readdirSync(distDir, { recursive: true });
-    for (const file of files) {
-      const filePath = path6.join(distDir, file);
-      if (fs7.statSync(filePath).isFile()) totalSize += fs7.statSync(filePath).size;
+var buildCommand = new import_commander5.Command("build").description("Build the theme for production").option("-d, --dir <directory>", "Theme directory", ".").option(
+  "--strict",
+  "Treat lint warnings as errors (Shopify-style a11y/quality gate)"
+).option("--no-lint", "Skip the lint gate (not recommended)").action(
+  async (options) => {
+    console.log("Validating before build...");
+    const result = validateTheme(options.dir);
+    if (!result.valid) {
+      console.error("Validation failed. Fix errors before building.");
+      result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
+      process.exit(1);
     }
-    const sizeMB = (totalSize / 1024 / 1024).toFixed(2);
-    console.log(`
+    if (options.lint !== false) {
+      const issues = await runAllRules(
+        path6.resolve(process.cwd(), options.dir),
+        { enabledRules: null }
+      );
+      const errors = issues.filter((i) => i.severity === "error");
+      const warnings = issues.filter((i) => i.severity === "warning");
+      if (issues.length > 0) {
+        console.log("\nLint:");
+        for (const i of issues) {
+          const marker = i.severity === "error" ? "\u2718" : "\u26A0";
+          const loc = i.file ? ` ${i.file}${i.line ? ":" + i.line : ""}` : "";
+          console.log(`  ${marker} ${i.rule}${loc} \u2014 ${i.message}`);
+        }
+      }
+      const blocked = errors.length > 0 || options.strict && warnings.length > 0;
+      if (blocked) {
+        console.error(
+          `
+Lint gate failed: ${errors.length} error(s), ${warnings.length} warning(s)${options.strict ? " (--strict treats warnings as errors)" : ""}.`
+        );
+        process.exit(1);
+      }
+      if (warnings.length > 0) {
+        console.log(
+          `
+\u26A0 ${warnings.length} lint warning(s) \u2014 run \`numu-theme lint\` for detail, or \`--strict\` to enforce.`
+        );
+      }
+    }
+    console.log("Building theme...");
+    try {
+      (0, import_child_process4.execSync)("npx vite build", { cwd: options.dir, stdio: "inherit" });
+    } catch {
+      console.error("Build failed");
+      process.exit(1);
+    }
+    const distDir = path6.join(options.dir, "dist");
+    if (fs7.existsSync(distDir)) {
+      let totalSize = 0;
+      const files = fs7.readdirSync(distDir, { recursive: true });
+      for (const file of files) {
+        const filePath = path6.join(distDir, file);
+        if (fs7.statSync(filePath).isFile())
+          totalSize += fs7.statSync(filePath).size;
+      }
+      const sizeMB = (totalSize / 1024 / 1024).toFixed(2);
+      console.log(`
 Bundle size: ${sizeMB} MB`);
-    if (totalSize > 5 * 1024 * 1024) {
-      console.warn("\u26A0 Bundle exceeds 5MB limit \u2014 optimize before submitting to marketplace");
+      if (totalSize > 5 * 1024 * 1024) {
+        console.warn(
+          "\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");
   }
-  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
@@ -1638,10 +2072,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((resolve7, reject) => {
+  return new Promise((resolve10, reject) => {
     const output = fs8.createWriteStream(outputPath);
     const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
-    output.on("close", () => resolve7(outputPath));
+    output.on("close", () => resolve10(outputPath));
     archive.on("error", reject);
     archive.pipe(output);
     const defaultExcludes = [
@@ -1663,7 +2097,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");
@@ -1676,7 +2110,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);
@@ -1697,11 +2131,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(
@@ -1724,7 +2158,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"));
@@ -1738,7 +2172,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`
     );
@@ -1791,12 +2225,12 @@ Submission failed (${submitRes.status}): ${JSON.stringify(submitRes.data)}`
 );
 
 // src/commands/install.ts
-var import_commander8 = require("commander");
-var import_child_process3 = 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>",
@@ -1834,7 +2268,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"));
@@ -1853,7 +2287,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_process3.execSync)("npm run build", {
+      (0, import_child_process6.execSync)("npm run build", {
         cwd: options.dir,
         stdio: "inherit",
         env: { ...process.env, NODE_ENV: "production" }
@@ -1864,7 +2298,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."
@@ -1872,7 +2306,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`
     );
@@ -1986,9 +2420,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}`);
@@ -2035,8 +2469,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(
@@ -2163,13 +2597,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}`);
   }
@@ -2182,8 +2616,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(
@@ -2209,21 +2643,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)."
@@ -2240,14 +2706,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."
@@ -2268,13 +2734,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)) {
@@ -2305,8 +2771,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 {
@@ -2322,6 +2788,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) {
@@ -2389,9 +2865,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 = {
@@ -3436,7 +3912,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(
@@ -3457,8 +3933,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."
       );
@@ -3494,14 +3970,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);
@@ -3525,7 +4001,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";
@@ -3543,7 +4019,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;
@@ -3584,7 +4060,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 {
@@ -3611,19 +4087,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",
@@ -3666,7 +4142,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.`,
@@ -3698,17 +4174,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((resolve7, 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(resolve7, reject);
+        downloadToFile(res.headers.location, dest).then(resolve10, reject);
         return;
       }
       if (res.statusCode !== 200) {
@@ -3717,7 +4193,7 @@ async function downloadToFile(url, dest) {
       }
       const out = fs14.createWriteStream(dest);
       res.pipe(out);
-      out.on("finish", () => out.close(() => resolve7()));
+      out.on("finish", () => out.close(() => resolve10()));
       out.on("error", reject);
     });
     req.on("error", reject);
@@ -3736,7 +4212,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(
@@ -3744,7 +4220,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) {
@@ -3791,7 +4267,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`
     );
@@ -3808,28 +4284,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((resolve7) => {
+  return new Promise((resolve10) => {
     rl.question(`${prompt} [y/N] `, (answer) => {
       rl.close();
-      resolve7(/^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}`;
@@ -3842,8 +4318,8 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
         return;
       }
     }
-    const path14 = isVersion ? `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions/${encodeURIComponent(options.version)}` : `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`;
-    const res = await apiRequest("DELETE", path14);
+    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;
@@ -3861,14 +4337,780 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
   }
 );
 
+// src/commands/migrate.ts
+var import_commander17 = require("commander");
+var fs15 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
+var import_chalk = __toESM(require("chalk"));
+var V2_HOOK_PATTERNS = [
+  {
+    pattern: /from\s+["']@\/contexts\/StoreContext["']/,
+    v2: "useStore (bazaar)",
+    v3: "useShop() from @numueg/theme-sdk",
+    note: "Returns Store directly; bazaar's useStore returns { store, themeSettings, ... } \u2014 destructure differently."
+  },
+  {
+    pattern: /useProductsContext|from\s+["']@\/contexts\/ProductsContext["']/,
+    v2: "useProductsContext (bazaar)",
+    v3: "useProducts() from @numueg/theme-sdk",
+    note: "V3 hook is paginated + has loading state. Shape: { items, loading, error, hasMore, loadMore }. V2 returned flat array."
+  },
+  {
+    pattern: /useCart\s*\(\s*\)/,
+    v2: "useCart (bazaar)",
+    v3: "useCart() from @numueg/theme-sdk",
+    note: "Same name but different shape \u2014 SDK returns { cart, addItem, removeItem, ... } with async actions. Bazaar's was sync."
+  },
+  {
+    pattern: /useAuth\s*\(\s*\)/,
+    v2: "useAuth (bazaar)",
+    v3: "useCustomer() + useCustomerActions() from @numueg/theme-sdk",
+    note: "Customer state is split from action handlers in V3 to avoid render-on-every-action."
+  },
+  {
+    pattern: /useTheme\s*\(\s*\)|from\s+["']@\/contexts\/ThemeContext["']/,
+    v2: "useTheme (bazaar)",
+    v3: "useThemeSettings() from @numueg/theme-sdk",
+    note: "Returns ThemeSettingsV3; access settings via .global_settings or .templates[<page>].sections[<id>].settings."
+  },
+  {
+    pattern: /useLanguage\s*\(/,
+    v2: "useLanguage (bazaar)",
+    v3: "useLocalization() / useDirection() from @numueg/theme-sdk",
+    note: "Returns { locale, direction, translations, ... }. Use useTranslation() for resolving message keys."
+  },
+  {
+    pattern: /editable\.section\s*\(/,
+    v2: "editable.section() helper",
+    v3: "<EditableText> / <EditableImage> from @numueg/theme-sdk",
+    note: "V3 marks editable nodes via dedicated components instead of spread props."
+  }
+];
+function migrationNotesFor(source) {
+  const notes = [];
+  const lines = source.split("\n");
+  for (const { pattern, v2, v3, note } of V2_HOOK_PATTERNS) {
+    for (let i = 0; i < lines.length; i++) {
+      if (pattern.test(lines[i])) {
+        notes.push({ v2, v3, note, lineHint: i + 1 });
+        break;
+      }
+    }
+  }
+  return notes;
+}
+function adapterCommentBlock(notes, v2RelativePath) {
+  const lines = [
+    "/**",
+    " * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    " *  V3 PORT \u2014 ADAPTER NOTES",
+    " * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    " *",
+    ` *  Source: ${v2RelativePath}`,
+    " *",
+    " *  Generated by `numu-theme migrate`. Review and rewrite using V3",
+    " *  SDK hooks before publishing. The list below was inferred from",
+    " *  static analysis \u2014 there may be other V2 idioms not detected.",
+    " *"
+  ];
+  if (notes.length === 0) {
+    lines.push(" *  No V2-specific hooks detected. You may only need to:");
+    lines.push(" *    1. Replace any bazaar-specific imports with @numueg/theme-sdk equivalents.");
+    lines.push(" *    2. Wrap your section's root element with <Section id={...} type={...}> from the SDK.");
+    lines.push(" *    3. Read settings from `props.instance.settings` (V3 SectionInstance shape).");
+  } else {
+    lines.push(" *  Required swaps:");
+    lines.push(" *");
+    for (const n of notes) {
+      const where = n.lineHint ? ` (line ${n.lineHint})` : "";
+      lines.push(` *    \u2022 ${n.v2}${where}`);
+      lines.push(` *      \u2192 ${n.v3}`);
+      lines.push(` *      ${n.note}`);
+      lines.push(" *");
+    }
+  }
+  lines.push(" *  When done, remove this block.");
+  lines.push(" * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push(" */");
+  return lines.join("\n");
+}
+function findSectionFiles(dir) {
+  if (!fs15.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
+    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 = 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() {
+  return `/**
+ * v2-bridge \u2014 per-theme compat shim for V2 sections ported via
+ * \`numu-theme migrate\`. DELETE this file once each section has been
+ * rewritten to use idiomatic V3 SDK hooks + components.
+ */
+
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import {
+  useV2Products,
+  useV2Categories,
+  useV2Auth,
+  useV2Language,
+  useV2Theme,
+} from "@numueg/theme-sdk/v2-compat";
+import { ProductCard, useThemeSettings } from "@numueg/theme-sdk";
+import type { SectionInstance } from "@numueg/theme-sdk";
+
+// \u2500\u2500 Re-shaped V3 hooks under V2 names \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
+
+/** V2's \`useProducts\` returned \`{ products, loading }\`. Same shape. */
+export function useProducts() {
+  return useV2Products();
+}
+
+/** V2's \`useCategories\` returned \`{ categories, loading }\`. Same shape. */
+export function useCategories() {
+  return useV2Categories();
+}
+
+/** V2's \`useAuth\` returned \`{ user, isAuthenticated }\`. */
+export function useAuth() {
+  return useV2Auth();
+}
+
+/** V2's \`useLanguage\` returned \`{ language, direction, setLanguage, t }\`. */
+export function useLanguage() {
+  return useV2Language();
+}
+
+/** V2's \`useStore\` returned the full store config; here we expose
+ *  only the parts ported sections use (themeSettings nested). */
+export function useStore() {
+  return useV2Theme();
+}
+
+// \u2500\u2500 V2 type re-shaping \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
+
+/**
+ * V2 sections expected this prop shape:
+ *
+ *   interface SectionComponentProps {
+ *     section: { id: string; type: string; settings: Record<string, any>; ... };
+ *     ...
+ *   }
+ *
+ * V3 mount passes \`{ instance: SectionInstance }\`. We re-export a
+ * compatible interface so existing destructure patterns like
+ * \`const { section } = props\` keep compiling \u2014 the wrapper below
+ * coerces \`instance\` \u2192 \`section\` at render time.
+ */
+export interface SectionComponentProps {
+  section: SectionInstance & { id?: string };
+}
+
+/**
+ * Section adapter. Migrate-generated sections still expect to be
+ * called with \`{ section }\`; the V3 \`SECTION_REGISTRY\` calls them
+ * with \`{ instance }\`. Wrap each export:
+ *
+ *   export default v2Section(YourComponent);
+ */
+export function v2Section<P extends SectionComponentProps>(
+  Component: (props: P) => ReactNode,
+): (props: { instance: SectionInstance }) => ReactNode {
+  return function V2SectionAdapter({ instance }) {
+    const props = { section: instance } as unknown as P;
+    return Component(props);
+  };
+}
+
+// \u2500\u2500 editable.section() compat \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
+
+/**
+ * V2's editable helper spread DOM props on individual nodes so the
+ * old V2 customizer could click-select them. V3 uses \`<EditableText>\`
+ * / \`<EditableImage>\` for the same job. Returning an empty object
+ * here means the spread is a no-op \u2014 the section still renders, just
+ * without the inline click-to-edit affordance. Replace with the V3
+ * components when polishing the port.
+ */
+export const editable = {
+  section: (_sectionId: string, _key: string) => ({}),
+  block: (_blockId: string, _key: string) => ({}),
+};
+
+// \u2500\u2500 Misc re-exports the V2 sections often imported \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export { ProductCard, useThemeSettings };
+
+/**
+ * V2's \`<Link to="/...">\` came from react-router-dom. The V3 storefront
+ * is Next.js, where \`<a href="/...">\` works (Next intercepts internal
+ * navigation). We expose a polyfill so existing JSX renders without
+ * react-router-dom installed. Pass-through any extra props.
+ */
+export function Link({
+  to,
+  children,
+  ...rest
+}: { to: string; children: ReactNode } & Omit<
+  ComponentPropsWithoutRef<"a">,
+  "href"
+>) {
+  return (
+    <a href={to} {...rest}>
+      {children}
+    </a>
+  );
+}
+
+/** V2's image placeholder constant. */
+export const PLACEHOLDER_HERO =
+  "https://images.unsplash.com/photo-1483985988355-763728e1935b?auto=format&fit=crop&w=1200&q=60";
+`;
+}
+function rewriteV2Imports(source) {
+  const PATH_REWRITES = [
+    // The most-common bazaar context imports.
+    [/@\/contexts\/ProductsContext/g, "../v2-bridge"],
+    [/@\/contexts\/AuthContext/g, "../v2-bridge"],
+    [/@\/contexts\/LanguageContext/g, "../v2-bridge"],
+    [/@\/contexts\/StoreContext/g, "../v2-bridge"],
+    [/@\/contexts\/ThemeContext/g, "../v2-bridge"],
+    // V2 engine types + editable helper.
+    [/@\/themes\/engine\/types/g, "../v2-bridge"],
+    [/@\/themes\/engine\/editable/g, "../v2-bridge"],
+    // bazaar's shared ProductCard component.
+    [/@\/components\/store\/ProductCard/g, "../v2-bridge"],
+    // The image placeholder constant.
+    [/@\/lib\/imagePlaceholders/g, "../v2-bridge"],
+    // react-router-dom → bridge (Link polyfill). Only the named
+    // imports we know about; the bridge exports `Link`. Sections that
+    // need other react-router-dom APIs will fail at build time, which
+    // is the right outcome — they need manual conversion.
+    [/(['"])react-router-dom\1/g, '"../v2-bridge"']
+  ];
+  let out = source;
+  for (const [pattern, replacement] of PATH_REWRITES) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+function makeThemeJson(themeId, displayName, sectionTypes) {
+  return {
+    id: themeId,
+    name: displayName,
+    author: "",
+    version: "0.1.0",
+    layout: "single-column",
+    description: `${displayName} \u2014 migrated from V2.`,
+    error_template: "templates/error.html",
+    loading_template: "templates/loading.html",
+    presets: {
+      templates: {
+        home: {
+          name: "Home",
+          sections: sectionTypes.map((type) => ({
+            type,
+            settings: {}
+          }))
+        }
+      }
+    }
+  };
+}
+function makeSettingsSchema() {
+  return [
+    {
+      name: "Brand",
+      settings: [
+        {
+          type: "color",
+          id: "primary_color",
+          label: "Primary color",
+          default: "#111111"
+        },
+        {
+          type: "color",
+          id: "accent_color",
+          label: "Accent color",
+          default: "#d4af37"
+        }
+      ]
+    }
+  ];
+}
+function makeMainTsx(themeId, displayName, sectionTypes) {
+  const registryEntries = sectionTypes.map((type) => `  "${type}": lazy(() => import("./sections/${type}")),`).join("\n");
+  return `/**
+ * ${displayName} (V3) \u2014 entry point.
+ *
+ * Generated by \`numu-theme migrate\`. Section components live in
+ * src/sections/<type>.tsx and are lazy-loaded so only sections the
+ * merchant actually uses pay the bundle cost.
+ */
+
+import {
+  StrictMode,
+  lazy,
+  Suspense,
+  useImperativeHandle,
+  useRef,
+  useState,
+  forwardRef,
+} from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+  NuMuProvider,
+  Section,
+  useThemeSettings,
+  type ThemeSettingsV3,
+  type Store,
+  type Cart,
+  type Customer,
+  type SectionInstance,
+  type MountResult,
+} from "@numueg/theme-sdk";
+import themeManifest from "../theme.json";
+
+const SECTION_REGISTRY: Record<string, ReturnType<typeof lazy>> = {
+${registryEntries}
+};
+
+function UnknownSection({ type }: { type: string }) {
+  return (
+    <section style={{ padding: "1rem", border: "1px dashed #fb923c" }}>
+      Unknown section: <strong>{type}</strong>
+    </section>
+  );
+}
+
+interface ResolvedSection {
+  id: string;
+  instance: SectionInstance;
+}
+
+interface MaybeOrdered {
+  sections?: Record<string, SectionInstance> | SectionInstance[];
+  order?: string[];
+}
+
+function resolveSections(group: MaybeOrdered | undefined): ResolvedSection[] {
+  if (!group) return [];
+  if (Array.isArray(group.sections)) {
+    return group.sections.map((instance, idx) => ({
+      id: \`\${instance.type}-\${idx}\`,
+      instance,
+    }));
+  }
+  const map = (group.sections ?? {}) as Record<string, SectionInstance>;
+  const order = group.order ?? Object.keys(map);
+  return order
+    .map((id): ResolvedSection | null => {
+      const instance = map[id];
+      if (!instance) return null;
+      return { id, instance };
+    })
+    .filter((x): x is ResolvedSection => Boolean(x));
+}
+
+const BUILTIN_HOME = (themeManifest as unknown as { presets?: { templates?: { home?: MaybeOrdered } } })
+  .presets?.templates?.home;
+
+function RenderSection({
+  instance,
+  sectionId,
+  groupId,
+}: {
+  instance: SectionInstance;
+  sectionId: string;
+  groupId?: string;
+}) {
+  const Component = SECTION_REGISTRY[instance.type];
+  if (!Component) {
+    return (
+      <Section id={sectionId} type={instance.type} groupId={groupId}>
+        <UnknownSection type={instance.type} />
+      </Section>
+    );
+  }
+  return (
+    <Section id={sectionId} type={instance.type} groupId={groupId}>
+      <Suspense fallback={<div style={{ minHeight: "20vh" }} />}>
+        <Component instance={instance} />
+      </Suspense>
+    </Section>
+  );
+}
+
+function ThemeApp() {
+  const settings = useThemeSettings();
+  const hostHome = settings.templates?.home as MaybeOrdered | undefined;
+  const sections = resolveSections(hostHome ?? BUILTIN_HOME);
+  return (
+    <div data-${themeId}-app>
+      {sections.map(({ id, instance }) => (
+        <RenderSection key={id} sectionId={id} instance={instance} />
+      ))}
+    </div>
+  );
+}
+
+// \u2500\u2500 Host contract: mount(el, ctx) returns a MountResult \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export interface MountContext {
+  store: Store;
+  themeSettings: ThemeSettingsV3;
+  initialCart?: Cart;
+  customer?: Customer | null;
+  locale?: string;
+  translations?: Record<string, string>;
+  [extra: string]: unknown;
+}
+
+interface DraftHandle {
+  applyDraft: (next: ThemeSettingsV3) => void;
+}
+
+const ThemeSettingsBridge = forwardRef<DraftHandle, { ctx: MountContext }>(
+  function ThemeSettingsBridge({ ctx }, ref) {
+    const [themeSettings, setThemeSettings] = useState<ThemeSettingsV3>(
+      ctx.themeSettings,
+    );
+    useImperativeHandle(
+      ref,
+      () => ({
+        applyDraft: (next) => setThemeSettings((prev) => (prev === next ? prev : next)),
+      }),
+      [],
+    );
+    return (
+      <NuMuProvider
+        store={ctx.store}
+        themeSettings={themeSettings}
+        initialCart={ctx.initialCart}
+        customer={ctx.customer}
+        locale={ctx.locale}
+        translations={ctx.translations}
+      >
+        <ThemeApp />
+      </NuMuProvider>
+    );
+  },
+);
+
+let currentRoot: Root | null = null;
+
+export function mount(el: HTMLElement, ctx: MountContext): MountResult {
+  if (currentRoot) {
+    currentRoot.unmount();
+    currentRoot = null;
+  }
+  const root = createRoot(el);
+  currentRoot = root;
+  const handleRef = { current: null as DraftHandle | null };
+  root.render(
+    <StrictMode>
+      <ThemeSettingsBridge
+        ctx={ctx}
+        ref={(h) => {
+          handleRef.current = h;
+        }}
+      />
+    </StrictMode>,
+  );
+  return {
+    applyDraft: (next) => handleRef.current?.applyDraft(next),
+    cleanup: () => {
+      root.unmount();
+      if (currentRoot === root) currentRoot = null;
+      handleRef.current = null;
+    },
+  };
+}
+
+const v3Handle = {
+  kind: "v3-mount" as const,
+  numu_theme_version: 3 as const,
+  mount_returns: "MountResult" as const,
+  manifest: { id: "${themeId}", name: "${displayName}", version: "0.1.0" },
+  mount,
+};
+export default v3Handle;
+`;
+}
+function makeViteConfig() {
+  return `import { defineConfig, type PluginOption } from "vite";
+import react from "@vitejs/plugin-react";
+import { numuTheme } from "@numueg/theme-plugin";
+
+export default defineConfig({
+  plugins: [react(), numuTheme({ federate: false }) as unknown as PluginOption],
+  server: { port: 5173 },
+});
+`;
+}
+function makePackageJson(themeId, displayName) {
+  return {
+    name: themeId,
+    version: "0.1.0",
+    private: true,
+    description: `${displayName} (V3 port)`,
+    type: "module",
+    scripts: {
+      dev: "vite",
+      build: "vite build",
+      preview: "vite preview --port 5173"
+    },
+    dependencies: {
+      react: "^18.3.1",
+      "react-dom": "^18.3.1",
+      "@numueg/theme-sdk": "^0.1.0",
+      // V2 sections commonly import these — including them in deps so
+      // `npm install` works without manual edits. The bundle externalises
+      // react/react-dom/@numueg/theme-sdk via federation; framer-motion
+      // and lucide-react ship as part of the theme bundle (~30-40 KB
+      // gzip combined). Themes that prove they don't need them can
+      // remove these after polishing.
+      "framer-motion": "^11.11.0",
+      "lucide-react": "^0.454.0"
+    },
+    devDependencies: {
+      "@numueg/theme-plugin": "^0.1.0",
+      "@types/react": "^18.3.0",
+      "@types/react-dom": "^18.3.0",
+      "@vitejs/plugin-react": "^4.3.0",
+      typescript: "^5.5.0",
+      vite: "^6.0.0"
+    }
+  };
+}
+function makeTsConfig() {
+  return {
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      jsx: "react-jsx",
+      strict: true,
+      noImplicitAny: true,
+      strictNullChecks: true,
+      esModuleInterop: true,
+      resolveJsonModule: true,
+      skipLibCheck: true,
+      isolatedModules: true,
+      allowSyntheticDefaultImports: true,
+      forceConsistentCasingInFileNames: true
+    },
+    include: ["src", "theme.json"]
+  };
+}
+function makeIndexHtml(displayName) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${displayName} \u2014 dev preview</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+}
+function makeTemplates() {
+  return {
+    error: `<!-- Static BYOT error template -->
+<main role="alert" style="min-height:100vh;display:flex;align-items:center;justify-content:center;padding:1rem;font-family:system-ui">
+  <div style="text-align:center;max-width:28rem">
+    <h1 style="font-size:1.5rem;font-weight:700;color:#b91c1c">Something went wrong</h1>
+    <p style="color:#374151;margin-top:.5rem">Please try again in a moment.</p>
+    <button data-numu-reset type="button" style="margin-top:1.5rem;padding:.5rem 1rem;background:#1d4ed8;color:white;border-radius:.375rem;border:0;cursor:pointer">Try again</button>
+  </div>
+</main>
+`,
+    loading: `<!-- Static BYOT loading skeleton -->
+<div role="status" aria-live="polite" aria-label="Loading" style="min-height:100vh;display:flex;align-items:center;justify-content:center;padding:1rem;font-family:system-ui">
+  <span style="font-size:.875rem;font-weight:500;color:#4b5563">Loading\u2026</span>
+</div>
+`
+  };
+}
+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(
+  "--out <dir>",
+  "Output directory (default: ./<v2-id>-engine-V3)"
+).option(
+  "--name <displayName>",
+  "Override the display name (default: title-cased v2 id)"
+).action(
+  async (v2Path, options) => {
+    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 = 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 = path15.resolve(
+      process.cwd(),
+      options.out ?? `${v2Id}-engine-V3`
+    );
+    if (fs15.existsSync(outDir)) {
+      console.error(import_chalk.default.red(`Output directory already exists: ${outDir}`));
+      console.error(import_chalk.default.dim("Remove it first, or pass --out to a fresh location."));
+      process.exit(1);
+    }
+    console.log(import_chalk.default.bold(`
+Migrating V2 \u2192 V3:`));
+    console.log(`  ${import_chalk.default.dim("from")} ${absV2Path}`);
+    console.log(`  ${import_chalk.default.dim("  to")} ${outDir}
+`);
+    for (const d of [
+      "src/sections",
+      "src/v2-bridge",
+      "schemas/sections",
+      "schemas/blocks",
+      "templates"
+    ]) {
+      fs15.mkdirSync(path15.join(outDir, d), { recursive: true });
+    }
+    fs15.writeFileSync(
+      path15.join(outDir, "src/v2-bridge", "index.tsx"),
+      makeV2Bridge()
+    );
+    const v2Styles = path15.join(absV2Path, "styles.css");
+    if (fs15.existsSync(v2Styles)) {
+      fs15.copyFileSync(v2Styles, path15.join(outDir, "styles.css"));
+      console.log(import_chalk.default.green("  \u2713 Copied styles.css"));
+    } else {
+      fs15.writeFileSync(
+        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 = path15.join(absV2Path, "sections");
+    const sectionFiles = fs15.existsSync(v2SectionsDir) ? findSectionFiles(v2SectionsDir) : [];
+    const sectionTypes = [];
+    const allNotes = [];
+    for (const file of sectionFiles) {
+      if (!file.endsWith(".tsx")) continue;
+      const type = sectionTypeFromFilename(file);
+      sectionTypes.push(type);
+      const v2Source = fs15.readFileSync(file, "utf-8");
+      const notes = migrationNotesFor(v2Source);
+      allNotes.push({ file, type, notes });
+      const relativeV2 = path15.relative(process.cwd(), file);
+      const header = adapterCommentBlock(notes, relativeV2);
+      const rewritten = rewriteV2Imports(v2Source);
+      const ported = `${header}
+
+${rewritten}`;
+      fs15.writeFileSync(
+        path15.join(outDir, "src/sections", `${type}.tsx`),
+        ported
+      );
+      fs15.writeFileSync(
+        path15.join(outDir, "schemas/sections", `${type}.json`),
+        JSON.stringify(
+          {
+            type,
+            name: type.split("-").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(" "),
+            settings: []
+          },
+          null,
+          2
+        )
+      );
+    }
+    console.log(import_chalk.default.green(`  \u2713 Ported ${sectionTypes.length} section file(s)`));
+    fs15.writeFileSync(
+      path15.join(outDir, "theme.json"),
+      JSON.stringify(makeThemeJson(themeId, displayName, sectionTypes), null, 2)
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "settings_schema.json"),
+      JSON.stringify(makeSettingsSchema(), null, 2)
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "src/main.tsx"),
+      makeMainTsx(themeId, displayName, sectionTypes)
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "vite.config.ts"),
+      makeViteConfig()
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "package.json"),
+      JSON.stringify(makePackageJson(themeId, displayName), null, 2)
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "tsconfig.json"),
+      JSON.stringify(makeTsConfig(), null, 2)
+    );
+    fs15.writeFileSync(
+      path15.join(outDir, "index.html"),
+      makeIndexHtml(displayName)
+    );
+    const tpl = makeTemplates();
+    fs15.writeFileSync(path15.join(outDir, "templates/error.html"), tpl.error);
+    fs15.writeFileSync(path15.join(outDir, "templates/loading.html"), tpl.loading);
+    fs15.writeFileSync(
+      path15.join(outDir, ".gitignore"),
+      "node_modules/\ndist/\n.DS_Store\n"
+    );
+    console.log(import_chalk.default.green("  \u2713 Wrote scaffold files\n"));
+    const filesWithNotes = allNotes.filter((n) => n.notes.length > 0);
+    if (filesWithNotes.length > 0) {
+      console.log(import_chalk.default.bold.yellow("Sections that need manual review:"));
+      for (const { type, notes } of filesWithNotes) {
+        console.log(
+          `
+  ${import_chalk.default.cyan(type)} ${import_chalk.default.dim(`(${notes.length} V2 hooks to swap)`)}`
+        );
+        for (const n of notes) {
+          console.log(
+            `    \u2022 ${import_chalk.default.dim(`L${n.lineHint ?? "?"}`)} ${n.v2} \u2192 ${import_chalk.default.green(n.v3)}`
+          );
+        }
+      }
+      console.log();
+    }
+    console.log(import_chalk.default.bold("\nNext steps:"));
+    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")}`);
+    console.log(
+      `
+${import_chalk.default.dim("Open each src/sections/*.tsx and follow the ADAPTER NOTES at the top.")}`
+    );
+  }
+);
+
 // src/index.ts
-var program = new import_commander16.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);
@@ -3879,4 +5121,5 @@ program.addCommand(addSectionCommand);
 program.addCommand(addBlockCommand);
 program.addCommand(pullCommand);
 program.addCommand(deleteCommand);
+program.addCommand(migrateCommand);
 program.parse();