@numueg/theme-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,3882 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/lint/rules/schema-registry-sync.ts
+var schema_registry_sync_exports = {};
+__export(schema_registry_sync_exports, {
+  default: () => schema_registry_sync_default
+});
+var rule, schema_registry_sync_default;
+var init_schema_registry_sync = __esm({
+  "src/lint/rules/schema-registry-sync.ts"() {
+    "use strict";
+    rule = {
+      id: "schema-registry-sync",
+      description: "Every section/block referenced in presets has a matching schema file",
+      check(ctx) {
+        const issues = [];
+        const presets = ctx.manifest.presets || {};
+        const templates = presets.templates || {};
+        const referencedSectionTypes = /* @__PURE__ */ new Set();
+        for (const template of Object.values(templates)) {
+          const sections = template?.sections || {};
+          for (const section of Object.values(sections)) {
+            if (section?.type) referencedSectionTypes.add(section.type);
+          }
+        }
+        for (const type of referencedSectionTypes) {
+          if (!ctx.sectionSchemas[type]) {
+            issues.push({
+              rule: rule.id,
+              severity: "error",
+              file: "theme.json",
+              message: `Preset references section type '${type}' but no schemas/sections/${type}.json exists.`,
+              suggestion: `Create schemas/sections/${type}.json or remove the section from the preset.`
+            });
+          }
+        }
+        for (const type of Object.keys(ctx.sectionSchemas)) {
+          if (!referencedSectionTypes.has(type)) {
+            if (Object.keys(referencedSectionTypes).length === 0) continue;
+            issues.push({
+              rule: rule.id,
+              severity: "warning",
+              file: `schemas/sections/${type}.json`,
+              message: `Section type '${type}' has a schema but isn't used in any preset.`,
+              suggestion: `Add it to a preset or delete the unused schema.`
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    schema_registry_sync_default = rule;
+  }
+});
+
+// src/lint/rules/locale-parity.ts
+var locale_parity_exports = {};
+__export(locale_parity_exports, {
+  default: () => locale_parity_default
+});
+function collectKeys(dict, prefix = "") {
+  const out = /* @__PURE__ */ new Set();
+  for (const [k, v] of Object.entries(dict)) {
+    const full = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      for (const nested of collectKeys(v, full)) {
+        out.add(nested);
+      }
+    } else {
+      out.add(full);
+    }
+  }
+  return out;
+}
+var rule2, locale_parity_default;
+var init_locale_parity = __esm({
+  "src/lint/rules/locale-parity.ts"() {
+    "use strict";
+    rule2 = {
+      id: "locale-parity",
+      description: "Non-default locale files have the same key set as the default",
+      check(ctx) {
+        const issues = [];
+        const locales = ctx.locales;
+        if (Object.keys(locales).length < 2) return issues;
+        const defaultCode = "en";
+        const defaultKeys = collectKeys(locales[defaultCode] || {});
+        if (defaultKeys.size === 0) return issues;
+        for (const [code, dict] of Object.entries(locales)) {
+          if (code === defaultCode) continue;
+          const keys = collectKeys(dict);
+          const missing = [];
+          const extra = [];
+          for (const k of defaultKeys) if (!keys.has(k)) missing.push(k);
+          for (const k of keys) if (!defaultKeys.has(k)) extra.push(k);
+          if (missing.length) {
+            issues.push({
+              rule: rule2.id,
+              severity: "error",
+              file: `locales/${code}.json`,
+              message: `Missing ${missing.length} key${missing.length === 1 ? "" : "s"} present in the default locale.`,
+              suggestion: `First missing keys: ` + missing.slice(0, 5).join(", ") + (missing.length > 5 ? ` (+${missing.length - 5} more)` : "")
+            });
+          }
+          if (extra.length) {
+            issues.push({
+              rule: rule2.id,
+              severity: "warning",
+              file: `locales/${code}.json`,
+              message: `Has ${extra.length} extra key${extra.length === 1 ? "" : "s"} not in the default locale (will fall back when the default is rendered).`,
+              suggestion: `Extra keys: ` + extra.slice(0, 5).join(", ") + (extra.length > 5 ? ` (+${extra.length - 5} more)` : "")
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    locale_parity_default = rule2;
+  }
+});
+
+// src/lint/rules/preset-schema-conformance.ts
+var preset_schema_conformance_exports = {};
+__export(preset_schema_conformance_exports, {
+  default: () => preset_schema_conformance_default
+});
+function collectSettingDefs(defs) {
+  const out = /* @__PURE__ */ new Map();
+  for (const d of defs) {
+    if (d && typeof d === "object" && d.id) {
+      out.set(
+        d.id,
+        d
+      );
+    }
+  }
+  return out;
+}
+function validateSettingValue(def, value) {
+  const type = def.type;
+  if (type === "select" || type === "radio") {
+    const options = def.options || [];
+    const validValues = options.map((o) => o.value);
+    if (validValues.length > 0 && !validValues.includes(value)) {
+      return `value '${String(value)}' is not one of [${validValues.join(", ")}]`;
+    }
+  }
+  if (type === "range" || type === "number") {
+    if (typeof value === "number") {
+      const min = def.min;
+      const max = def.max;
+      if (min !== void 0 && value < min)
+        return `value ${value} is below min (${min})`;
+      if (max !== void 0 && value > max)
+        return `value ${value} is above max (${max})`;
+    }
+  }
+  if (type === "checkbox" && typeof value !== "boolean") {
+    return `expected boolean, got ${typeof value}`;
+  }
+  return null;
+}
+var rule3, preset_schema_conformance_default;
+var init_preset_schema_conformance = __esm({
+  "src/lint/rules/preset-schema-conformance.ts"() {
+    "use strict";
+    rule3 = {
+      id: "preset-schema-conformance",
+      description: "Preset settings only use schema-declared ids + valid values",
+      check(ctx) {
+        const issues = [];
+        const presets = ctx.manifest.presets || {};
+        const templates = presets.templates || {};
+        for (const [templateKey, template] of Object.entries(templates)) {
+          const sections = template?.sections || {};
+          for (const [sectionKey, section] of Object.entries(sections)) {
+            if (!section?.type) continue;
+            const schema = ctx.sectionSchemas[section.type];
+            if (!schema) continue;
+            const allowed = collectSettingDefs(
+              schema.settings || []
+            );
+            const setSettings = section.settings || {};
+            for (const [settingId, value] of Object.entries(setSettings)) {
+              const def = allowed.get(settingId);
+              if (!def) {
+                issues.push({
+                  rule: rule3.id,
+                  severity: "error",
+                  file: "theme.json",
+                  message: `Template '${templateKey}' section '${sectionKey}' sets '${settingId}' but section schema '${section.type}' doesn't declare it.`,
+                  suggestion: `Add the setting to schemas/sections/${section.type}.json or remove it from the preset.`
+                });
+                continue;
+              }
+              const optionError = validateSettingValue(def, value);
+              if (optionError) {
+                issues.push({
+                  rule: rule3.id,
+                  severity: "error",
+                  file: "theme.json",
+                  message: `Template '${templateKey}' section '${sectionKey}' setting '${settingId}': ${optionError}`
+                });
+              }
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    preset_schema_conformance_default = rule3;
+  }
+});
+
+// src/lint/rules/unused-settings.ts
+var unused_settings_exports = {};
+__export(unused_settings_exports, {
+  default: () => unused_settings_default
+});
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var rule4, unused_settings_default;
+var init_unused_settings = __esm({
+  "src/lint/rules/unused-settings.ts"() {
+    "use strict";
+    rule4 = {
+      id: "unused-settings",
+      description: "Every settings_schema entry is read by some component",
+      check(ctx) {
+        const issues = [];
+        const schema = ctx.settingsSchema || [];
+        const declared = [];
+        for (const def of schema) {
+          if (def && typeof def === "object") {
+            const id = def.id;
+            if (typeof id === "string") declared.push(id);
+          }
+        }
+        if (declared.length === 0) return issues;
+        const haystack = [
+          ...Object.values(ctx.sources),
+          ...Object.values(ctx.sectionSchemas).map((s) => JSON.stringify(s)),
+          ...Object.values(ctx.blockSchemas).map((s) => JSON.stringify(s))
+        ].join("\n");
+        for (const id of declared) {
+          const patterns = [
+            new RegExp(`["']${escapeRe(id)}["']`),
+            new RegExp(`\\.${escapeRe(id)}\\b`)
+          ];
+          const used = patterns.some((p) => p.test(haystack));
+          if (!used) {
+            issues.push({
+              rule: rule4.id,
+              severity: "warning",
+              file: "settings_schema.json",
+              message: `Setting '${id}' is declared but never read.`,
+              suggestion: `Remove from settings_schema.json or wire it up in a section.`
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    unused_settings_default = rule4;
+  }
+});
+
+// src/lint/rules/img-missing-alt.ts
+var img_missing_alt_exports = {};
+__export(img_missing_alt_exports, {
+  default: () => img_missing_alt_default
+});
+var rule5, img_missing_alt_default;
+var init_img_missing_alt = __esm({
+  "src/lint/rules/img-missing-alt.ts"() {
+    "use strict";
+    rule5 = {
+      id: "img-missing-alt",
+      description: "Every <img> tag has an alt attribute",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          const lines = source.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const imgMatches = line.match(/<img\b[^>]*>/g);
+            if (!imgMatches) continue;
+            for (const match of imgMatches) {
+              if (!/\balt\s*=/.test(match)) {
+                issues.push({
+                  rule: rule5.id,
+                  severity: "warning",
+                  file,
+                  line: i + 1,
+                  message: `<img> tag missing alt attribute.`,
+                  suggestion: `Add alt="..." (or alt="" for purely decorative images), or use <Image> from @numueg/theme-sdk.`
+                });
+              }
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    img_missing_alt_default = rule5;
+  }
+});
+
+// src/lint/rules/hardcoded-text.ts
+var hardcoded_text_exports = {};
+__export(hardcoded_text_exports, {
+  default: () => hardcoded_text_default
+});
+function isUiCopy(text) {
+  if (!/[a-zA-Z]/.test(text)) return false;
+  const words = text.split(/\s+/).filter((w) => /[a-zA-Z]/.test(w));
+  if (words.length < 3) return false;
+  if (/^https?:\/\//.test(text)) return false;
+  if (/^[a-z][\w-]*$/.test(text)) return false;
+  return true;
+}
+function truncate(s, n) {
+  return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
+}
+var rule6, hardcoded_text_default;
+var init_hardcoded_text = __esm({
+  "src/lint/rules/hardcoded-text.ts"() {
+    "use strict";
+    rule6 = {
+      id: "hardcoded-text",
+      description: "JSX text content with 3+ words should use t() for translatability",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          if (file.includes("/dev-entry") || file.endsWith(".test.tsx")) continue;
+          const lines = source.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const m = line.match(/>([^<>{}\n]{8,})</g);
+            if (!m) continue;
+            for (const block of m) {
+              const text = block.slice(1, -1).trim();
+              if (!isUiCopy(text)) continue;
+              issues.push({
+                rule: rule6.id,
+                severity: "warning",
+                file,
+                line: i + 1,
+                message: `Hardcoded text "${truncate(text, 40)}" \u2014 won't translate.`,
+                suggestion: `Replace with {t("section.key")} and add the key to locales/*.json.`
+              });
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    hardcoded_text_default = rule6;
+  }
+});
+
+// src/lint/rules/inline-color-literal.ts
+var inline_color_literal_exports = {};
+__export(inline_color_literal_exports, {
+  default: () => inline_color_literal_default
+});
+var rule7, inline_color_literal_default;
+var init_inline_color_literal = __esm({
+  "src/lint/rules/inline-color-literal.ts"() {
+    "use strict";
+    rule7 = {
+      id: "inline-color-literal",
+      description: "Don't hardcode hex colors in style props \u2014 use theme settings",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          const lines = source.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!/style\s*=\s*\{/.test(line) && !/style=\{\{/.test(line)) continue;
+            const hexMatch = line.match(/#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})\b/g);
+            if (hexMatch) {
+              issues.push({
+                rule: rule7.id,
+                severity: "warning",
+                file,
+                line: i + 1,
+                message: `Hardcoded color (${hexMatch.join(", ")}) in style prop.`,
+                suggestion: `Read from useThemeSettings() or a color_scheme setting so merchants can rebrand.`
+              });
+            }
+            const rgbMatch = line.match(/rgba?\s*\(/g);
+            if (rgbMatch) {
+              issues.push({
+                rule: rule7.id,
+                severity: "warning",
+                file,
+                line: i + 1,
+                message: `Hardcoded rgb()/rgba() in style prop.`,
+                suggestion: `Read from useThemeSettings() or a color_scheme setting.`
+              });
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    inline_color_literal_default = rule7;
+  }
+});
+
+// src/lint/rules/forbidden-script-tag.ts
+var forbidden_script_tag_exports = {};
+__export(forbidden_script_tag_exports, {
+  default: () => forbidden_script_tag_default
+});
+var rule8, forbidden_script_tag_default;
+var init_forbidden_script_tag = __esm({
+  "src/lint/rules/forbidden-script-tag.ts"() {
+    "use strict";
+    rule8 = {
+      id: "forbidden-script-tag",
+      description: "Section components can't contain <script> tags (CSP + AST scanner forbid)",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          const lines = source.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (/<script[\s>]/i.test(line)) {
+              issues.push({
+                rule: rule8.id,
+                severity: "error",
+                file,
+                line: i + 1,
+                message: `<script> tag in theme source \u2014 marketplace AST scanner will reject.`,
+                suggestion: `Use a useEffect hook to load behavior, or move analytics to useAnalytics().`
+              });
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    forbidden_script_tag_default = rule8;
+  }
+});
+
+// src/lint/rules/use-app-no-availability-check.ts
+var use_app_no_availability_check_exports = {};
+__export(use_app_no_availability_check_exports, {
+  default: () => use_app_no_availability_check_default
+});
+var rule9, use_app_no_availability_check_default;
+var init_use_app_no_availability_check = __esm({
+  "src/lint/rules/use-app-no-availability-check.ts"() {
+    "use strict";
+    rule9 = {
+      id: "use-app-no-availability-check",
+      description: "useApp() calls should branch on .available for graceful fallback",
+      check(ctx) {
+        const issues = [];
+        for (const [file, source] of Object.entries(ctx.sources)) {
+          if (!/\buseApp\s*\(/.test(source)) continue;
+          const hasAvailableCheck = /\.available\b/.test(source) || /\{\s*[^}]*\bavailable\b/.test(source);
+          if (!hasAvailableCheck) {
+            const lines = source.split("\n");
+            let lineNum = 0;
+            for (let i = 0; i < lines.length; i++) {
+              if (/\buseApp\s*\(/.test(lines[i])) {
+                lineNum = i + 1;
+                break;
+              }
+            }
+            issues.push({
+              rule: rule9.id,
+              severity: "warning",
+              file,
+              line: lineNum,
+              message: `useApp() result is used without checking .available \u2014 UI breaks on stores without the app installed.`,
+              suggestion: `if (!app.available) return <Fallback />; before rendering app.data.`
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    use_app_no_availability_check_default = rule9;
+  }
+});
+
+// src/lint/rules/manifest-required-fields.ts
+var manifest_required_fields_exports = {};
+__export(manifest_required_fields_exports, {
+  default: () => manifest_required_fields_default
+});
+var SEMVER, ID_RE, rule10, manifest_required_fields_default;
+var init_manifest_required_fields = __esm({
+  "src/lint/rules/manifest-required-fields.ts"() {
+    "use strict";
+    SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.]+)?$/;
+    ID_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/i;
+    rule10 = {
+      id: "manifest-required-fields",
+      description: "theme.json has id / name / version / author with valid shapes",
+      check(ctx) {
+        const issues = [];
+        const m = ctx.manifest;
+        if (!m.id || typeof m.id !== "string") {
+          issues.push({
+            rule: rule10.id,
+            severity: "error",
+            file: "theme.json",
+            message: "Missing required field 'id'."
+          });
+        } else if (!ID_RE.test(m.id)) {
+          issues.push({
+            rule: rule10.id,
+            severity: "error",
+            file: "theme.json",
+            message: `Field 'id' = '${m.id}' must be alphanumerics, dashes, or underscores.`
+          });
+        }
+        if (!m.name || typeof m.name !== "string" || !m.name.trim()) {
+          issues.push({
+            rule: rule10.id,
+            severity: "error",
+            file: "theme.json",
+            message: "Missing or empty 'name'."
+          });
+        }
+        if (!m.version || typeof m.version !== "string") {
+          issues.push({
+            rule: rule10.id,
+            severity: "error",
+            file: "theme.json",
+            message: "Missing required field 'version'."
+          });
+        } else if (!SEMVER.test(m.version)) {
+          issues.push({
+            rule: rule10.id,
+            severity: "error",
+            file: "theme.json",
+            message: `Field 'version' = '${m.version}' is not valid semver (x.y.z).`
+          });
+        }
+        if (!m.author || typeof m.author !== "string" || !m.author.trim()) {
+          issues.push({
+            rule: rule10.id,
+            severity: "warning",
+            file: "theme.json",
+            message: "Field 'author' is empty \u2014 marketplace submission requires a non-empty author.",
+            suggestion: `Set "author": "Your Name" in theme.json.`
+          });
+        }
+        return issues;
+      }
+    };
+    manifest_required_fields_default = rule10;
+  }
+});
+
+// src/index.ts
+var import_commander16 = require("commander");
+
+// src/commands/init.ts
+var import_commander = require("commander");
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+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)) {
+    console.error(`Directory "${name}" already exists`);
+    process.exit(1);
+  }
+  console.log(`Creating NUMU theme: ${name}...`);
+  for (const d of [
+    "src/sections",
+    "src/blocks",
+    "schemas/sections",
+    "schemas/blocks",
+    "assets"
+  ]) {
+    fs.mkdirSync(path.join(dir, d), { recursive: true });
+  }
+  fs.writeFileSync(
+    path.join(dir, "theme.json"),
+    JSON.stringify(
+      {
+        id: name.toLowerCase().replace(/[^a-z0-9-]/g, "-"),
+        name,
+        author: "",
+        version: "0.1.0",
+        layout: "single-column",
+        description: `${name} NUMU theme`,
+        // Phase 7.3 — static BYOT templates for chrome that renders
+        // outside the React tree (the streaming loading skeleton +
+        // the client error boundary). Themes that want to fully
+        // own those moments edit these HTML files; absent or 404
+        // → the platform's hardcoded fallback renders.
+        error_template: "templates/error.html",
+        loading_template: "templates/loading.html",
+        presets: {
+          templates: {
+            home: {
+              name: "Home",
+              sections: [
+                {
+                  type: "hero",
+                  settings: { headline: "Welcome to our store" }
+                }
+              ]
+            }
+          }
+        }
+      },
+      null,
+      2
+    )
+  );
+  fs.mkdirSync(path.join(dir, "templates"), { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, "templates/error.html"),
+    `<!--
+  Static BYOT error template \u2014 rendered by the storefront when a
+  page throws. No JS available (the bundle might be the thing that
+  failed). Use <button data-numu-reset> to expose a retry button \u2014
+  the storefront wires the click for you.
+-->
+<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>
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "templates/loading.html"),
+    `<!-- 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">
+  <div style="display:flex;align-items:center;gap:.75rem;color:#4b5563">
+    <svg style="width:1.25rem;height:1.25rem;animation:spin 1s linear infinite" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" stroke="currentColor" stroke-opacity=".25" stroke-width="3"></circle>
+      <path d="M22 12a10 10 0 0 1-10 10" stroke="currentColor" stroke-width="3" stroke-linecap="round"></path>
+    </svg>
+    <span style="font-size:.875rem;font-weight:500">Loading\u2026</span>
+  </div>
+  <style>@keyframes spin { to { transform: rotate(360deg) } }</style>
+</div>
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "settings_schema.json"),
+    JSON.stringify(
+      [
+        {
+          type: "color",
+          id: "primary_color",
+          label: "Primary Color",
+          default: "#3B82F6"
+        },
+        {
+          type: "color",
+          id: "secondary_color",
+          label: "Secondary Color",
+          default: "#1E40AF"
+        },
+        {
+          type: "select",
+          id: "font_family",
+          label: "Font Family",
+          default: "Inter",
+          options: [
+            { value: "Inter", label: "Inter" },
+            { value: "Roboto", label: "Roboto" },
+            { value: "Cairo", label: "Cairo" }
+          ]
+        }
+      ],
+      null,
+      2
+    )
+  );
+  fs.writeFileSync(
+    path.join(dir, "styles.css"),
+    ":root { --numu-primary: #3B82F6; }\n"
+  );
+  fs.writeFileSync(
+    path.join(dir, "src/sections/Hero.tsx"),
+    `import type { SectionProps } from "@numueg/theme-sdk";
+
+export default function Hero({ settings }: SectionProps) {
+  return (
+    <section className="min-h-[50vh] flex items-center justify-center bg-gray-900 text-white">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold">{settings.headline as string || "Welcome"}</h1>
+        {settings.subtitle ? (
+          <p className="mt-4 text-xl">{settings.subtitle as string}</p>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "schemas/sections/hero.json"),
+    JSON.stringify(
+      {
+        type: "hero",
+        name: "Hero Banner",
+        locales: { ar: { name: "\u0628\u0627\u0646\u0631 \u0631\u0626\u064A\u0633\u064A" } },
+        settings: [
+          {
+            type: "text",
+            id: "headline",
+            label: "Headline",
+            locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646" } },
+            default: "Welcome"
+          },
+          {
+            type: "text",
+            id: "subtitle",
+            label: "Subtitle",
+            locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0641\u0631\u0639\u064A" } }
+          },
+          {
+            type: "image_picker",
+            id: "background_image",
+            label: "Background Image",
+            locales: { ar: { label: "\u0635\u0648\u0631\u0629 \u0627\u0644\u062E\u0644\u0641\u064A\u0629" } }
+          }
+        ]
+      },
+      null,
+      2
+    )
+  );
+  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 Hero from "./sections/Hero";
+
+interface ThemeProps {
+  themeSettings: ThemeSettingsV3;
+}
+
+const SECTION_REGISTRY: Record<string, React.ComponentType<any>> = {
+  hero: Hero,
+};
+
+export default function Theme({ themeSettings }: ThemeProps) {
+  const page = usePage();
+  const pageType = page?.type || "home";
+  const template =
+    themeSettings.templates?.[pageType] || themeSettings.templates?.home;
+
+  return (
+    <main>
+      {template?.order.map((sectionId) => {
+        const section = template.sections[sectionId];
+        if (!section || section.disabled) return null;
+        const Component = SECTION_REGISTRY[section.type];
+        if (!Component) return null;
+        return (
+          <Component
+            key={sectionId}
+            settings={section.settings}
+            blocks={section.blocks}
+            blockOrder={section.block_order}
+          />
+        );
+      })}
+    </main>
+  );
+}
+
+// \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);
+
+  return {
+    unmount: () => {
+      window.removeEventListener("numu:theme-update", handleUpdate);
+      root.unmount();
+    },
+    update: (next: MountProps) => {
+      current = next;
+      root.render(<ThemeWithContext {...current} />);
+    },
+  };
+}
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "index.html"),
+    `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name} \u2014 NUMU Theme Dev</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/dev-entry.tsx"></script>
+  </body>
+</html>
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "src/dev-entry.tsx"),
+    `import { createRoot } from "react-dom/client";
+import Theme from "./main";
+
+const placeholder = {
+  schema_version: 3 as const,
+  theme_id: "${name}",
+  global_settings: {},
+  templates: {
+    home: {
+      name: "Home",
+      sections: { hero_1: { type: "hero", settings: { headline: "Hello, theme!" } } },
+      order: ["hero_1"],
+    },
+  },
+  section_groups: {},
+};
+
+const root = document.getElementById("root");
+if (root) createRoot(root).render(<Theme themeSettings={placeholder as any} />);
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "vite.config.ts"),
+    `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { numuTheme } from "@numueg/theme-plugin";
+
+// The @numueg/theme-plugin handles all the NUMU-specific glue:
+//   - validates theme.json + settings_schema.json + entry point
+//   - externalizes React + @numueg/theme-sdk (host-provided)
+//   - emits dist/manifest.json + dist/import-map.json after build
+//
+// You don't need to repeat \`build.lib\` / \`build.rollupOptions.external\`
+// \u2014 the plugin sets sensible defaults when they're omitted.
+
+export default defineConfig({
+  plugins: [react(), numuTheme()],
+  server: { port: 5173 },
+});
+`
+  );
+  fs.writeFileSync(
+    path.join(dir, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          lib: ["ES2022", "DOM", "DOM.Iterable"],
+          module: "ESNext",
+          moduleResolution: "bundler",
+          jsx: "react-jsx",
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          isolatedModules: true,
+          esModuleInterop: true,
+          resolveJsonModule: true
+        },
+        include: ["src"]
+      },
+      null,
+      2
+    )
+  );
+  fs.writeFileSync(
+    path.join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name: `numu-theme-${name}`,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+          dev: "numu-theme dev",
+          build: "numu-theme build",
+          check: "numu-theme check"
+        },
+        dependencies: { "@numueg/theme-sdk": "^0.1.0" },
+        devDependencies: {
+          "@numueg/theme-cli": "^0.1.0",
+          "@numueg/theme-plugin": "^0.1.0",
+          "@vitejs/plugin-react": "^4.3.0",
+          vite: "^6.0.0",
+          typescript: "^5.8.0",
+          "@types/react": "^19.0.0",
+          "@types/react-dom": "^19.0.0",
+          react: "^19.0.0",
+          "react-dom": "^19.0.0"
+        }
+      },
+      null,
+      2
+    )
+  );
+  fs.writeFileSync(
+    path.join(dir, ".gitignore"),
+    "node_modules\ndist\n.env\n.env.*\n.next\n"
+  );
+  console.log(
+    `
+Theme "${name}" created.
+
+Next steps:
+  cd ${name}
+  npm install
+  npx numu-theme dev   # local preview
+  npx numu-theme build # production build
+`
+  );
+});
+
+// src/commands/dev.ts
+var import_commander2 = require("commander");
+var import_child_process = 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 loadConfig() {
+  const config = {
+    api_url: process.env.NUMU_API_URL || "https://api.numu.io/api/v1"
+  };
+  if (fs2.existsSync(RC_FILE)) {
+    try {
+      const rc = JSON.parse(fs2.readFileSync(RC_FILE, "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;
+    } catch {
+    }
+  }
+  if (process.env.NUMU_TOKEN) config.token = process.env.NUMU_TOKEN;
+  if (process.env.NUMU_STORE_ID) config.store_id = process.env.NUMU_STORE_ID;
+  return config;
+}
+function saveConfig(updates) {
+  let existing = {};
+  if (fs2.existsSync(RC_FILE)) {
+    try {
+      existing = JSON.parse(fs2.readFileSync(RC_FILE, "utf-8"));
+    } catch {
+    }
+  }
+  const merged = { ...existing, ...updates };
+  fs2.writeFileSync(RC_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+  try {
+    fs2.chmodSync(RC_FILE, 384);
+  } catch {
+  }
+}
+
+// src/utils/api.ts
+var https = __toESM(require("https"));
+var http = __toESM(require("http"));
+var fs3 = __toESM(require("fs"));
+function parseBody(body) {
+  let raw;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { unwrapped: body, raw: body };
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && Object.prototype.hasOwnProperty.call(raw, "data")) {
+    return { unwrapped: raw.data, raw };
+  }
+  return { unwrapped: raw, raw };
+}
+function assertHttpsOrLocalhost(urlStr) {
+  const url = new URL(urlStr);
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:") {
+    const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (!isLocal) {
+      throw new Error(
+        `Refusing to send credentials over HTTP to ${url.hostname}. Set NUMU_API_URL to an https:// URL.`
+      );
+    }
+    return url;
+  }
+  throw new Error(`Unsupported protocol: ${url.protocol}`);
+}
+async function apiRequest(method, path14, body) {
+  const config = loadConfig();
+  const url = assertHttpsOrLocalhost(`${config.api_url}${path14}`);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  return new Promise((resolve7, reject) => {
+    const headers = {};
+    if (config.token) headers["Authorization"] = `Bearer ${config.token}`;
+    let postData;
+    if (body !== void 0) {
+      postData = Buffer.from(JSON.stringify(body), "utf8");
+      headers["Content-Type"] = "application/json";
+      headers["Content-Length"] = String(postData.byteLength);
+    }
+    const req = transport.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method,
+        headers
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => data += chunk);
+        res.on("end", () => {
+          const { unwrapped, raw } = parseBody(data);
+          resolve7({
+            status: res.statusCode ?? 0,
+            data: unwrapped,
+            raw
+          });
+        });
+      }
+    );
+    req.on("error", reject);
+    if (postData) req.write(postData);
+    req.end();
+  });
+}
+async function uploadFile(path_, filePath) {
+  const config = loadConfig();
+  const url = assertHttpsOrLocalhost(`${config.api_url}${path_}`);
+  const fileBuffer = fs3.readFileSync(filePath);
+  const boundary = "----NuMuCLI" + Date.now();
+  const fileName = filePath.split(/[\\/]/).pop() || "theme.zip";
+  const head = Buffer.from(
+    `--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${fileName}"\r
+Content-Type: application/zip\r
+\r
+`,
+    "utf8"
+  );
+  const tail = Buffer.from(`\r
+--${boundary}--\r
+`, "utf8");
+  const fullBody = Buffer.concat([head, fileBuffer, tail]);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  return new Promise((resolve7, reject) => {
+    const headers = {
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      "Content-Length": String(fullBody.byteLength)
+    };
+    if (config.token) headers["Authorization"] = `Bearer ${config.token}`;
+    const req = transport.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        // Preserve querystring so callers can pass `?queue_build=false`
+        // (used by install/submit to keep the uploaded ZIP from being
+        // consumed by the BYOT-from-zip Celery task before the
+        // marketplace builder picks it up).
+        path: url.pathname + (url.search || ""),
+        method: "POST",
+        headers
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => data += chunk);
+        res.on("end", () => {
+          const { unwrapped, raw } = parseBody(data);
+          resolve7({
+            status: res.statusCode ?? 0,
+            data: unwrapped,
+            raw
+          });
+        });
+      }
+    );
+    req.on("error", reject);
+    req.write(fullBody);
+    req.end();
+  });
+}
+
+// src/commands/dev.ts
+var devCommand = new import_commander2.Command("dev").description("Start local development server with HMR").option("-p, --port <port>", "Dev server port", "5173").option("-s, --store <store_id>", "Store ID to register dev URL with").option(
+  "--expose",
+  "Bind to 0.0.0.0 instead of localhost (use only on trusted networks)",
+  false
+).option(
+  "--watch",
+  "Also run `vite build --watch` so dist/theme.js auto-rebuilds on save",
+  false
+).action(
+  async (options) => {
+    const config = loadConfig();
+    const storeId = options.store || config.store_id;
+    if (storeId && config.token) {
+      console.log(`Registering dev server with store ${storeId}...`);
+      try {
+        const res = await apiRequest(
+          "POST",
+          `/stores/${encodeURIComponent(storeId)}/themes/external/dev-mode`,
+          {
+            dev_url: `http://localhost:${options.port}`,
+            mode: "development"
+          }
+        );
+        if (res.status >= 300) {
+          console.warn(
+            `  Registration returned ${res.status}: ${JSON.stringify(res.data)}`
+          );
+        } else {
+          console.log("  Registered. Edits will reflect in your storefront.");
+        }
+      } catch (err) {
+        console.warn(
+          `  Could not register dev server: ${err.message}`
+        );
+      }
+    }
+    const args = ["vite", "--port", options.port];
+    if (options.expose) args.push("--host");
+    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 });
+    let watcher = null;
+    if (options.watch) {
+      console.log("Starting bundle watcher (vite build --watch)...");
+      watcher = (0, import_child_process.spawn)(
+        "npx",
+        ["vite", "build", "--watch", "--mode", "development"],
+        { stdio: "inherit", shell: true }
+      );
+    }
+    function shutdown(code) {
+      if (watcher && !watcher.killed) {
+        watcher.kill();
+      }
+      process.exit(code);
+    }
+    child.on("exit", (code) => shutdown(code ?? 0));
+    if (watcher) {
+      watcher.on("exit", (code) => {
+        if (code !== 0 && code !== null) {
+          console.error(`Bundle watcher exited with code ${code}.`);
+        }
+        if (!child.killed) child.kill();
+      });
+    }
+  }
+);
+
+// src/commands/check.ts
+var import_commander3 = require("commander");
+
+// src/utils/validator.ts
+var fs4 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var semver = __toESM(require("semver"));
+function validateTheme(themeDir) {
+  const errors = [];
+  const warnings = [];
+  const themeJsonPath = path3.join(themeDir, "theme.json");
+  if (!fs4.existsSync(themeJsonPath)) {
+    errors.push("Missing theme.json in project root");
+    return { valid: false, errors, warnings };
+  }
+  let themeJson;
+  try {
+    themeJson = JSON.parse(fs4.readFileSync(themeJsonPath, "utf-8"));
+  } catch {
+    errors.push("theme.json is not valid JSON");
+    return { valid: false, errors, warnings };
+  }
+  for (const field of ["name", "version", "author"]) {
+    if (!themeJson[field]) errors.push(`theme.json missing required field: ${field}`);
+  }
+  if (themeJson.version && !semver.valid(themeJson.version)) {
+    errors.push(`theme.json version "${themeJson.version}" is not valid semver`);
+  }
+  const settingsPath = path3.join(themeDir, "settings_schema.json");
+  if (!fs4.existsSync(settingsPath)) {
+    warnings.push("Missing settings_schema.json \u2014 theme will have no global settings");
+  } else {
+    try {
+      JSON.parse(fs4.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      errors.push("settings_schema.json is not valid JSON");
+    }
+  }
+  const sectionsDir = path3.join(themeDir, "src", "sections");
+  if (!fs4.existsSync(sectionsDir) || fs4.readdirSync(sectionsDir).length === 0) {
+    errors.push("Theme must have at least one section in src/sections/");
+  }
+  const schemaDir = path3.join(themeDir, "schemas", "sections");
+  const componentNames = /* @__PURE__ */ new Set();
+  const schemaNames = /* @__PURE__ */ new Set();
+  if (fs4.existsSync(sectionsDir)) {
+    for (const file of fs4.readdirSync(sectionsDir)) {
+      if (!/\.(tsx|ts|jsx|js)$/.test(file)) continue;
+      componentNames.add(path3.basename(file, path3.extname(file)).toLowerCase());
+    }
+  }
+  if (fs4.existsSync(schemaDir)) {
+    for (const file of fs4.readdirSync(schemaDir)) {
+      if (!file.endsWith(".json")) continue;
+      schemaNames.add(path3.basename(file, ".json").toLowerCase());
+    }
+  }
+  for (const name of componentNames) {
+    if (!schemaNames.has(name)) {
+      warnings.push(
+        `Section "${name}" has no schema at schemas/sections/${name}.json \u2014 merchants won't be able to add this section via the customizer.`
+      );
+    }
+  }
+  for (const name of schemaNames) {
+    if (!componentNames.has(name)) {
+      errors.push(
+        `schemas/sections/${name}.json has no matching component at src/sections/<${name}>.tsx \u2014 the storefront will throw 'unknown section type' the moment a merchant adds it.`
+      );
+    }
+  }
+  const pkgPath = path3.join(themeDir, "package.json");
+  if (fs4.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+      const deps = { ...pkg.dependencies, ...pkg.peerDependencies };
+      if (!deps["@numueg/theme-sdk"]) {
+        warnings.push("@numueg/theme-sdk not found in dependencies \u2014 hooks will not be available");
+      }
+    } catch {
+    }
+  }
+  for (const envFile of [".env", ".env.local", ".env.production"]) {
+    if (fs4.existsSync(path3.join(themeDir, envFile))) {
+      errors.push(`${envFile} found \u2014 secrets must not be included in themes`);
+    }
+  }
+  if (!themeJson.presets || Object.keys(themeJson.presets).length === 0) {
+    warnings.push("theme.json has no presets \u2014 merchants will start with an empty page");
+  }
+  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(`
+Validation failed with ${result.errors.length} error(s)`);
+    process.exit(1);
+  }
+  console.log(`
+\u2713 Theme is valid (${result.warnings.length} warning(s))`);
+});
+
+// src/commands/lint.ts
+var import_commander4 = require("commander");
+var fs6 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+
+// src/lint/runner.ts
+var fs5 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+async function runAllRules(themeDir, options) {
+  const ctx = buildContext(themeDir);
+  const ruleLoaders = [
+    () => Promise.resolve().then(() => (init_schema_registry_sync(), schema_registry_sync_exports)),
+    () => Promise.resolve().then(() => (init_locale_parity(), locale_parity_exports)),
+    () => Promise.resolve().then(() => (init_preset_schema_conformance(), preset_schema_conformance_exports)),
+    () => Promise.resolve().then(() => (init_unused_settings(), unused_settings_exports)),
+    () => Promise.resolve().then(() => (init_img_missing_alt(), img_missing_alt_exports)),
+    () => Promise.resolve().then(() => (init_hardcoded_text(), hardcoded_text_exports)),
+    () => 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))
+  ];
+  const issues = [];
+  for (const load of ruleLoaders) {
+    let mod;
+    try {
+      mod = await load();
+    } catch (e) {
+      issues.push({
+        rule: "internal",
+        severity: "warning",
+        message: `Failed to load rule module: ${e.message}`
+      });
+      continue;
+    }
+    const rule11 = mod.default;
+    if (options.enabledRules && !options.enabledRules.has(rule11.id)) continue;
+    try {
+      const ruleIssues = await rule11.check(ctx);
+      for (const issue of ruleIssues) issues.push(issue);
+    } catch (e) {
+      issues.push({
+        rule: rule11.id,
+        severity: "warning",
+        message: `Rule crashed: ${e.message}`
+      });
+    }
+  }
+  return issues;
+}
+function buildContext(themeDir) {
+  const manifest = readJson(path4.join(themeDir, "theme.json"), {});
+  const settingsSchema = readJson(
+    path4.join(themeDir, "settings_schema.json"),
+    []
+  );
+  const sectionSchemas = readSchemaDir(
+    path4.join(themeDir, "schemas", "sections")
+  );
+  const blockSchemas = readSchemaDir(path4.join(themeDir, "schemas", "blocks"));
+  const locales = readLocales(path4.join(themeDir, "locales"));
+  const sources = readSources(themeDir);
+  return {
+    themeDir,
+    manifest,
+    settingsSchema,
+    sectionSchemas,
+    blockSchemas,
+    locales,
+    sources
+  };
+}
+function readJson(filePath, fallback) {
+  if (!fs5.existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(fs5.readFileSync(filePath, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function readSchemaDir(dir) {
+  const out = {};
+  if (!fs5.existsSync(dir)) return out;
+  for (const file of fs5.readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    const parsed = readJson(path4.join(dir, file), null);
+    if (parsed && typeof parsed === "object") {
+      const type = parsed.type || file.replace(/\.json$/, "");
+      out[type] = parsed;
+    }
+  }
+  return out;
+}
+function readLocales(dir) {
+  const out = {};
+  if (!fs5.existsSync(dir)) return out;
+  for (const file of fs5.readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    const locale = file.replace(/\.(default\.)?json$/, "");
+    const parsed = readJson(path4.join(dir, file), {});
+    out[locale] = parsed;
+  }
+  return out;
+}
+function readSources(themeDir) {
+  const out = {};
+  const srcDir = path4.join(themeDir, "src");
+  if (!fs5.existsSync(srcDir)) return out;
+  walk(srcDir, (file) => {
+    if (!/\.(tsx?|jsx?)$/.test(file)) return;
+    const rel = path4.relative(themeDir, file).replace(/\\/g, "/");
+    out[rel] = fs5.readFileSync(file, "utf-8");
+  });
+  return out;
+}
+function walk(dir, visit) {
+  for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+    const full = path4.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, visit);
+    else visit(full);
+  }
+}
+
+// src/commands/lint.ts
+var lintCommand = new import_commander4.Command("lint").description("Lint a NUMU theme against the platform's contract + best practices").option("-d, --dir <directory>", "Theme directory", ".").option("--strict", "Treat warnings as errors (exit 1)").option("--json", "Output JSON instead of human-readable").option(
+  "--rules <rules>",
+  "Comma-separated list of rule IDs to run (default: all)"
+).action(
+  async (options) => {
+    const themeDir = path5.resolve(process.cwd(), options.dir);
+    if (!fs6.existsSync(path5.join(themeDir, "theme.json"))) {
+      console.error(
+        `No theme.json found in ${themeDir}. Run 'numu-theme lint' from a theme project root.`
+      );
+      process.exit(1);
+    }
+    const enabledRules = options.rules ? new Set(options.rules.split(",").map((r) => r.trim())) : null;
+    const issues = await runAllRules(themeDir, {
+      enabledRules
+    });
+    if (options.json) {
+      console.log(JSON.stringify({ issues }, null, 2));
+      const hasErrors = issues.some((i) => i.severity === "error");
+      process.exit(hasErrors || options.strict && issues.length > 0 ? 1 : 0);
+      return;
+    }
+    if (issues.length === 0) {
+      console.log("\u2713 No issues found.");
+      process.exit(0);
+      return;
+    }
+    const grouped = groupByFile(issues);
+    for (const [file, fileIssues] of Object.entries(grouped)) {
+      console.log(`
+${file}`);
+      for (const issue of fileIssues) {
+        const marker = issue.severity === "error" ? "\u2718" : "\u26A0";
+        const loc = issue.line ? `:${issue.line}` : "";
+        console.log(`  ${marker} ${issue.rule}${loc} \u2014 ${issue.message}`);
+        if (issue.suggestion) {
+          console.log(`     \u21B3 ${issue.suggestion}`);
+        }
+      }
+    }
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warnCount = issues.filter((i) => i.severity === "warning").length;
+    console.log(
+      `
+${errorCount} error${errorCount === 1 ? "" : "s"}, ${warnCount} warning${warnCount === 1 ? "" : "s"}.`
+    );
+    const shouldFail = errorCount > 0 || options.strict && warnCount > 0;
+    process.exit(shouldFail ? 1 : 0);
+  }
+);
+function groupByFile(issues) {
+  const out = {};
+  for (const issue of issues) {
+    const key = issue.file || "(theme-wide)";
+    if (!out[key]) out[key] = [];
+    out[key].push(issue);
+  }
+  return out;
+}
+
+// src/commands/build.ts
+var import_commander5 = require("commander");
+var import_child_process2 = 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;
+    }
+    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");
+    }
+  }
+  console.log("\n\u2713 Build complete");
+});
+
+// src/commands/push.ts
+var import_commander6 = require("commander");
+var path7 = __toESM(require("path"));
+var os2 = __toESM(require("os"));
+
+// src/utils/zipper.ts
+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) => {
+    const output = fs8.createWriteStream(outputPath);
+    const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
+    output.on("close", () => resolve7(outputPath));
+    archive.on("error", reject);
+    archive.pipe(output);
+    const defaultExcludes = [
+      "node_modules/**",
+      ".git/**",
+      ".env",
+      ".env.*",
+      ".next/**"
+    ];
+    if (!opts.includeDist) defaultExcludes.push("dist/**");
+    const allExcludes = [...defaultExcludes, ...opts.excludePatterns ?? []];
+    archive.glob("**/*", {
+      cwd: sourceDir,
+      ignore: allExcludes,
+      dot: false
+    });
+    archive.finalize();
+  });
+}
+
+// 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) => {
+  const config = loadConfig();
+  if (!config.token) {
+    console.error("Not logged in. Run: numu-theme login");
+    process.exit(1);
+  }
+  console.log("Validating...");
+  const result = validateTheme(options.dir);
+  if (!result.valid) {
+    result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
+    process.exit(1);
+  }
+  console.log("Packaging theme...");
+  const zipPath = path7.join(os2.tmpdir(), `numu-theme-${Date.now()}.zip`);
+  await zipDirectory(options.dir, zipPath);
+  console.log("Uploading...");
+  const res = await uploadFile("/themes/upload", zipPath);
+  if (res.status === 200 || res.status === 201 || res.status === 202) {
+    console.log("\n\u2713 Theme uploaded. Build queued.");
+    if (res.data?.build_id) {
+      console.log(`  Build ID: ${res.data.build_id}`);
+      console.log("  Poll status with:");
+      console.log(
+        `    numu-theme status --build ${res.data.build_id}`
+      );
+    }
+  } else {
+    console.error(`
+Push failed (${res.status}): ${JSON.stringify(res.data)}`);
+    process.exit(1);
+  }
+});
+
+// src/commands/submit.ts
+var import_commander7 = require("commander");
+var path8 = __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(
+  "-t, --theme-id <theme_id>",
+  "Marketplace theme listing UUID (create via dashboard first)"
+).option("-n, --notes <notes>", "Release notes for this version").action(
+  async (options) => {
+    const config = loadConfig();
+    if (!config.token) {
+      console.error("Not logged in. Run: numu-theme login");
+      process.exit(1);
+    }
+    console.log("Running full validation...");
+    const result = validateTheme(options.dir);
+    if (!result.valid) {
+      console.error(
+        "Theme must pass all validations before marketplace submission."
+      );
+      result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
+      process.exit(1);
+    }
+    if (result.warnings.length > 0) {
+      console.log("\nWarnings:");
+      result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
+    }
+    const themeJsonPath = path8.join(options.dir, "theme.json");
+    let version;
+    try {
+      const tj = JSON.parse(fs9.readFileSync(themeJsonPath, "utf-8"));
+      version = tj.version;
+    } catch {
+      console.error("Cannot read theme.json from theme directory.");
+      process.exit(1);
+    }
+    if (!version) {
+      console.error("theme.json has no `version` field.");
+      process.exit(1);
+    }
+    console.log("\nPackaging theme source...");
+    const zipPath = path8.join(
+      os3.tmpdir(),
+      `numu-theme-submit-${Date.now()}.zip`
+    );
+    await zipDirectory(options.dir, zipPath);
+    console.log("Uploading source...");
+    const uploadRes = await uploadFile(
+      "/themes/upload?queue_build=false",
+      zipPath
+    );
+    if (uploadRes.status >= 300) {
+      console.error(
+        `
+Upload failed (${uploadRes.status}): ${JSON.stringify(uploadRes.data)}`
+      );
+      process.exit(1);
+    }
+    const sourceZipPath = uploadRes.data?.source_zip_path;
+    if (!sourceZipPath) {
+      console.error(
+        "\nUpload response missing `source_zip_path`. Backend may be out of date."
+      );
+      process.exit(1);
+    }
+    console.log(`Submitting version ${version} to marketplace...`);
+    const submitRes = await apiRequest(
+      "POST",
+      `/marketplace/developer/themes/${encodeURIComponent(options.themeId)}/versions`,
+      {
+        version_string: version,
+        source_zip_path: sourceZipPath,
+        release_notes: options.notes ?? null
+      }
+    );
+    if (submitRes.status === 200 || submitRes.status === 202) {
+      console.log("\n\u2713 Theme submitted for review!");
+      console.log(`  Version ID: ${submitRes.data.version_id}`);
+      console.log(`  Status:     ${submitRes.data.status}`);
+      console.log("\n  Poll status with:");
+      console.log(
+        `    numu-theme status --version ${submitRes.data.version_id}`
+      );
+    } else {
+      console.error(
+        `
+Submission failed (${submitRes.status}): ${JSON.stringify(submitRes.data)}`
+      );
+      process.exit(1);
+    }
+  }
+);
+
+// src/commands/install.ts
+var import_commander8 = require("commander");
+var import_child_process3 = require("child_process");
+var path9 = __toESM(require("path"));
+var os4 = __toESM(require("os"));
+var fs10 = __toESM(require("fs"));
+var installCommand = new import_commander8.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>",
+  "Marketplace theme listing UUID (create via dashboard first)"
+).requiredOption(
+  "-s, --store <store_id>",
+  "Store UUID to install on. Falls back to the configured store_id when omitted."
+).option(
+  "--poll-timeout <seconds>",
+  "How long to wait for the build to finish (default: 240)",
+  "240"
+).option(
+  "--poll-interval <seconds>",
+  "How often to poll build status (default: 4)",
+  "4"
+).option("-n, --notes <notes>", "Release notes for this version").action(
+  async (options) => {
+    const config = loadConfig();
+    if (!config.token) {
+      console.error("Not logged in. Run: numu-theme login");
+      process.exit(1);
+    }
+    const storeId = options.store || config.store_id;
+    if (!storeId) {
+      console.error(
+        "No store specified. Pass --store <id> or set store_id in your config."
+      );
+      process.exit(1);
+    }
+    console.log("Validating theme...");
+    const result = validateTheme(options.dir);
+    if (!result.valid) {
+      console.error("Theme has validation errors. Fix these first:");
+      result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
+      process.exit(1);
+    }
+    result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
+    const themeJsonPath = path9.join(options.dir, "theme.json");
+    let baseVersion;
+    try {
+      const tj = JSON.parse(fs10.readFileSync(themeJsonPath, "utf-8"));
+      baseVersion = tj.version;
+    } catch {
+      console.error("Cannot read theme.json from theme directory.");
+      process.exit(1);
+    }
+    if (!baseVersion) {
+      console.error("theme.json has no `version` field.");
+      process.exit(1);
+    }
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z") + "-" + Math.random().toString(36).slice(2, 6);
+    const version = `${baseVersion}-dev.${stamp}`;
+    console.log(`  base version: ${baseVersion}`);
+    console.log(`  install tag:  ${version}`);
+    console.log("Building locally (so worker can skip npm install)...");
+    try {
+      (0, import_child_process3.execSync)("npm run build", {
+        cwd: options.dir,
+        stdio: "inherit",
+        env: { ...process.env, NODE_ENV: "production" }
+      });
+    } catch {
+      console.error(
+        "\nLocal build failed. Fix the build errors above before running install again."
+      );
+      process.exit(1);
+    }
+    const distEntry = path9.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."
+      );
+      process.exit(1);
+    }
+    console.log("Packaging source + dist...");
+    const zipPath = path9.join(
+      os4.tmpdir(),
+      `numu-theme-install-${Date.now()}.zip`
+    );
+    await zipDirectory(options.dir, zipPath, { includeDist: true });
+    console.log("Uploading...");
+    const uploadRes = await uploadFile(
+      "/themes/upload?queue_build=false",
+      zipPath
+    );
+    if (uploadRes.status >= 300) {
+      console.error(
+        `Upload failed (${uploadRes.status}): ${JSON.stringify(uploadRes.data)}`
+      );
+      process.exit(1);
+    }
+    const sourceZipPath = uploadRes.data?.source_zip_path;
+    if (!sourceZipPath) {
+      console.error(
+        "Upload response missing `source_zip_path`. Backend out of date?"
+      );
+      process.exit(1);
+    }
+    console.log(`Submitting version ${version}...`);
+    const submitRes = await apiRequest(
+      "POST",
+      `/marketplace/developer/themes/${encodeURIComponent(options.themeId)}/versions`,
+      {
+        version_string: version,
+        source_zip_path: sourceZipPath,
+        release_notes: options.notes ?? null
+      }
+    );
+    if (submitRes.status !== 200 && submitRes.status !== 202) {
+      console.error(
+        `Submit failed (${submitRes.status}): ${JSON.stringify(submitRes.data)}`
+      );
+      process.exit(1);
+    }
+    const versionId = submitRes.data.version_id;
+    console.log(`  version_id: ${versionId}`);
+    const timeoutMs = Math.max(60, parseInt(options.pollTimeout, 10) || 240) * 1e3;
+    const intervalMs = Math.max(2, parseInt(options.pollInterval, 10) || 4) * 1e3;
+    const deadline = Date.now() + timeoutMs;
+    console.log("Waiting for build...");
+    let lastStatus = "";
+    while (Date.now() < deadline) {
+      const statusRes = await apiRequest(
+        "GET",
+        `/marketplace/developer/versions/${encodeURIComponent(versionId)}/status`
+      );
+      if (statusRes.status >= 300) {
+        console.error(
+          `  status check failed (${statusRes.status}): ${JSON.stringify(statusRes.data)}`
+        );
+        process.exit(1);
+      }
+      const s = statusRes.data;
+      if (s.status !== lastStatus) {
+        console.log(`  ${s.status}`);
+        lastStatus = s.status;
+      }
+      if (s.bundle_url) break;
+      if (s.status === "build_failed") {
+        console.error("\nBuild failed.");
+        if (s.build_log) {
+          console.error("--- build log (tail) ---");
+          const tail = s.build_log.split("\n").slice(-60).join("\n");
+          console.error(tail);
+          console.error("--- end log ---");
+        }
+        process.exit(1);
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    if (Date.now() >= deadline) {
+      console.error(
+        `
+Timed out waiting for build (${options.pollTimeout}s). Run \`numu-theme status --version ${versionId}\` to keep watching.`
+      );
+      process.exit(1);
+    }
+    console.log(`Installing on store ${storeId}...`);
+    const installRes = await apiRequest(
+      "POST",
+      `/stores/${encodeURIComponent(storeId)}/marketplace/developer-install/${encodeURIComponent(options.themeId)}`,
+      {}
+    );
+    if (installRes.status >= 300) {
+      console.error(
+        `Install failed (${installRes.status}): ${JSON.stringify(installRes.data)}`
+      );
+      process.exit(1);
+    }
+    const activateRes = await apiRequest(
+      "POST",
+      `/stores/${encodeURIComponent(storeId)}/marketplace/activate`,
+      { marketplace_theme_id: options.themeId }
+    );
+    if (activateRes.status >= 300) {
+      console.warn(
+        `  Installed but activation returned ${activateRes.status}. Visit the dashboard to activate.`
+      );
+    }
+    console.log("\n\u2713 Installed and activated on your store.");
+    console.log(
+      `  installation_id: ${installRes.data.installation_id}`
+    );
+    console.log(`  version: ${installRes.data.version_string}`);
+    console.log(`  version_status: ${installRes.data.version_status}`);
+  }
+);
+
+// src/commands/login.ts
+var import_commander9 = 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) => {
+  if (options.apiUrl) {
+    saveConfig({ api_url: options.apiUrl });
+    console.log(`API URL set to: ${options.apiUrl}`);
+  }
+  if (options.token) {
+    saveConfig({ token: options.token });
+    console.log("\u2713 Token saved");
+    return;
+  }
+  console.log("NUMU Theme Developer Login\n");
+  const answers = await import_inquirer.default.prompt([
+    {
+      type: "input",
+      name: "email",
+      message: "Email:",
+      validate: (v) => v.includes("@") || "Enter a valid email"
+    },
+    { type: "password", name: "password", message: "Password:", mask: "*" }
+  ]);
+  try {
+    const res = await apiRequest("POST", "/auth/login", {
+      email: answers.email,
+      password: answers.password
+    });
+    if (res.status === 200 && res.data?.requires_2fa) {
+      console.error(
+        "\nLogin failed: this account has 2FA enabled. The CLI cannot complete a 2FA challenge \u2014 generate an API token in the dashboard and run `numu-theme login --token <token>`."
+      );
+      process.exit(1);
+    } else if (res.status === 200 && res.data?.tokens?.access_token) {
+      saveConfig({ token: res.data.tokens.access_token });
+      console.log("\n\u2713 Logged in successfully");
+    } else {
+      const detail = res.data?.detail ?? `HTTP ${res.status}`;
+      console.error(`
+Login failed: ${detail}`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`
+Login failed: ${err.message}`);
+    process.exit(1);
+  }
+});
+
+// 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(
+  "--version <version_id>",
+  "Marketplace version ID returned by `numu-theme submit`"
+).option("-w, --watch", "Poll until the build reaches a terminal state").option(
+  "-i, --interval <seconds>",
+  "Polling interval in seconds (with --watch)",
+  "3"
+).action(async (options) => {
+  const config = loadConfig();
+  if (!config.token) {
+    console.error("Not logged in. Run: numu-theme login");
+    process.exit(1);
+  }
+  if (!options.build && !options.version) {
+    console.error("Provide --build <id> or --version <id>");
+    process.exit(1);
+  }
+  if (options.build && options.version) {
+    console.error("Use one of --build or --version, not both");
+    process.exit(1);
+  }
+  const intervalMs = Math.max(
+    1e3,
+    Math.floor(parseFloat(options.interval || "3") * 1e3)
+  );
+  const TERMINAL_BUILD = /* @__PURE__ */ new Set([
+    "complete",
+    "completed",
+    "failed",
+    "error"
+  ]);
+  const TERMINAL_VERSION = /* @__PURE__ */ new Set([
+    "pending_review",
+    "published",
+    "rejected",
+    "build_failed"
+  ]);
+  async function pollOnce() {
+    if (options.build) {
+      const res2 = await apiRequest(
+        "GET",
+        `/themes/builds/${encodeURIComponent(options.build)}`
+      );
+      if (res2.status === 404) {
+        console.error(`Build ${options.build} not found`);
+        return { done: true, failed: true };
+      }
+      if (res2.status >= 300) {
+        console.error(`HTTP ${res2.status}: ${JSON.stringify(res2.data)}`);
+        return { done: true, failed: true };
+      }
+      const s2 = res2.data;
+      printBuild(s2);
+      const terminal2 = TERMINAL_BUILD.has(s2.status);
+      const failed2 = s2.status === "failed" || s2.status === "error";
+      return { done: terminal2, failed: failed2 };
+    }
+    const res = await apiRequest(
+      "GET",
+      `/marketplace/developer/versions/${encodeURIComponent(options.version)}/status`
+    );
+    if (res.status === 404) {
+      console.error(`Version ${options.version} not found`);
+      return { done: true, failed: true };
+    }
+    if (res.status >= 300) {
+      console.error(`HTTP ${res.status}: ${JSON.stringify(res.data)}`);
+      return { done: true, failed: true };
+    }
+    const s = res.data;
+    printVersion(s);
+    const terminal = TERMINAL_VERSION.has(s.status);
+    const failed = s.status === "rejected" || s.status === "build_failed";
+    return { done: terminal, failed };
+  }
+  if (!options.watch) {
+    const { failed } = await pollOnce();
+    process.exit(failed ? 1 : 0);
+  }
+  while (true) {
+    const { done, failed } = await pollOnce();
+    if (done) {
+      process.exit(failed ? 1 : 0);
+    }
+    await sleep(intervalMs);
+  }
+});
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function printBuild(s) {
+  console.log(`Build:      ${s.build_id}`);
+  console.log(`Status:     ${s.status}`);
+  if (s.version) console.log(`Version:    ${s.version}`);
+  if (s.theme_slug) console.log(`Theme:      ${s.theme_slug}`);
+  if (s.bundle_url) console.log(`Bundle:     ${s.bundle_url}`);
+  if (s.css_url) console.log(`CSS:        ${s.css_url}`);
+  if (s.size_bytes != null)
+    console.log(`Size:       ${formatBytes(s.size_bytes)}`);
+  if (s.checksum) console.log(`Checksum:   ${s.checksum}`);
+  if (s.updated_at) console.log(`Updated:    ${s.updated_at}`);
+  if (s.error) console.log(`
+Error:
+${s.error}`);
+  console.log("");
+}
+function printVersion(s) {
+  console.log(`Version:    ${s.version_id}`);
+  if (s.version_string) console.log(`Number:     ${s.version_string}`);
+  console.log(`Status:     ${s.status}`);
+  if (s.bundle_url) console.log(`Bundle:     ${s.bundle_url}`);
+  if (s.css_url) console.log(`CSS:        ${s.css_url}`);
+  if (s.size_bytes != null)
+    console.log(`Size:       ${formatBytes(s.size_bytes)}`);
+  if (s.checksum) console.log(`Checksum:   ${s.checksum}`);
+  if (s.build_log) console.log(`
+Build log:
+${s.build_log}`);
+  console.log("");
+}
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+// src/commands/doctor.ts
+var import_commander11 = 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) => {
+  let issues = 0;
+  let warnings = 0;
+  const themeDir = path10.resolve(options.dir);
+  function ok(line) {
+    console.log(`  \x1B[32m\u2713\x1B[0m ${line}`);
+  }
+  function warn(line) {
+    warnings += 1;
+    console.log(`  \x1B[33m\u26A0\x1B[0m ${line}`);
+  }
+  function fail(line) {
+    issues += 1;
+    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");
+  if (!fs11.existsSync(themeJsonPath)) {
+    fail(`No theme.json found in ${themeDir}`);
+    console.log(
+      "    Run \x1B[36mnumu-theme init <name>\x1B[0m to scaffold a theme."
+    );
+    process.exit(1);
+  }
+  ok(`Theme directory: ${themeDir}`);
+  if (!fs11.existsSync(settingsPath))
+    warn("settings_schema.json missing \u2014 no global theme settings");
+  else ok("settings_schema.json present");
+  console.log("\nContract");
+  const result = validateTheme(themeDir);
+  for (const w of result.warnings) warn(w);
+  for (const e of result.errors) fail(e);
+  if (result.valid && result.errors.length === 0)
+    ok(`numu-theme check passes (${result.warnings.length} warning(s))`);
+  console.log("\nBundle contract");
+  const entryCandidates = [
+    "src/main.tsx",
+    "src/main.ts",
+    "src/index.tsx",
+    "src/index.ts"
+  ];
+  const entry = entryCandidates.find(
+    (p) => fs11.existsSync(path10.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);
+    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\`.`
+      );
+  }
+  console.log("\nLocales");
+  const localesDir = path10.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)."
+    );
+  } else {
+    const localeFiles = fs11.readdirSync(localesDir).filter((f) => f.endsWith(".json"));
+    const hasDefault = localeFiles.some((f) => f.endsWith(".default.json"));
+    if (!hasDefault) {
+      fail(
+        "No default locale file found in locales/ \u2014 useTranslation needs a *.default.json fallback. Rename your primary locale to e.g. locales/en.default.json."
+      );
+    } else {
+      ok(`locales/ has ${localeFiles.length} file(s) including default`);
+    }
+    for (const f of localeFiles) {
+      try {
+        JSON.parse(fs11.readFileSync(path10.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");
+  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."
+    );
+  } else {
+    const count = fs11.readdirSync(assetsDir).filter(
+      (f) => !f.startsWith(".")
+    ).length;
+    if (count === 0) {
+      warn("assets/ exists but is empty");
+    } else {
+      ok(`assets/ contains ${count} file(s)/folder(s)`);
+    }
+  }
+  console.log("\nPresets");
+  try {
+    const themeJson = JSON.parse(
+      fs11.readFileSync(themeJsonPath, "utf-8")
+    );
+    const presets = themeJson.presets ?? {};
+    const sectionsDir = path10.join(themeDir, "src", "sections");
+    const schemaDir = path10.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())
+    ) : /* @__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())
+    ) : /* @__PURE__ */ new Set();
+    let missingRefs = 0;
+    for (const [presetName, presetVal] of Object.entries(presets)) {
+      const sections = presetVal.sections ?? {};
+      for (const [, sec] of Object.entries(sections)) {
+        const t = (sec?.type || "").toLowerCase();
+        if (!t) continue;
+        if (!componentNames.has(t)) {
+          fail(
+            `Preset "${presetName}" references section type "${t}" but src/sections/${t}.tsx (or .jsx/.ts) is missing.`
+          );
+          missingRefs += 1;
+        } else if (!schemaNames.has(t)) {
+          warn(
+            `Preset "${presetName}" references section type "${t}" but schemas/sections/${t}.json is missing \u2014 customizer will warn on selection.`
+          );
+        }
+      }
+    }
+    if (Object.keys(presets).length === 0) {
+      warn("theme.json has no presets \u2014 merchants start with an empty page");
+    } else if (missingRefs === 0) {
+      ok(
+        `${Object.keys(presets).length} preset(s); all section refs resolve`
+      );
+    }
+  } catch (err) {
+    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");
+  if (!fs11.existsSync(distJs)) {
+    warn("dist/theme.js not found \u2014 run `numu-theme build` first");
+  } else {
+    const stat = fs11.statSync(distJs);
+    ok(`dist/theme.js (${(stat.size / 1024).toFixed(1)} KB)`);
+    if (stat.size > 2 * 1024 * 1024)
+      warn("Bundle exceeds 2 MB \u2014 marketplace will reject");
+  }
+  if (!fs11.existsSync(distCss)) {
+    warn(
+      "dist/theme.css not found \u2014 the plugin should copy styles.css; check that styles.css exists"
+    );
+  } else {
+    ok("dist/theme.css present");
+  }
+  console.log("\nAuth");
+  const config = loadConfig();
+  if (!config.token) {
+    warn("Not logged in \u2014 run `numu-theme login --api-url <url>` to enable push/submit");
+  } else {
+    ok(`Token loaded (${config.token.slice(0, 12)}\u2026)`);
+  }
+  if (!config.api_url) {
+    warn("No api_url configured \u2014 run `numu-theme login --api-url <url>`");
+  } else {
+    ok(`API URL: ${config.api_url}`);
+  }
+  if (config.token && config.api_url) {
+    console.log("\nBackend");
+    try {
+      const res = await apiRequest("GET", "/auth/me");
+      if (res.status === 200) {
+        ok("Backend reachable, token valid");
+      } else if (res.status === 401) {
+        fail("Token expired \u2014 run `numu-theme login` again");
+      } else if (res.status === 404) {
+        warn(
+          `API URL may be wrong (HTTP 404 on /auth/me). Confirm api_url in ~/.numurc points to the /api/v1 prefix.`
+        );
+      } else {
+        warn(`Backend returned HTTP ${res.status}`);
+      }
+    } catch (err) {
+      fail(`Cannot reach ${config.api_url}: ${err.message}`);
+    }
+  }
+  console.log("\nDev server");
+  const port = parseInt(options.port, 10);
+  try {
+    const probe = await fetch(`http://localhost:${port}/theme.json`, {
+      signal: AbortSignal.timeout(1500)
+    }).catch(() => null);
+    if (!probe) {
+      warn(
+        `Nothing serving on http://localhost:${port} \u2014 run \`numu-theme dev\` in another terminal to enable dev-mode connect`
+      );
+    } else if (probe.ok) {
+      ok(`Dev server is up on :${port} and serving theme.json`);
+    } else {
+      warn(
+        `Port ${port} responds but didn't return theme.json (HTTP ${probe.status})`
+      );
+    }
+  } catch (err) {
+    warn(`Dev port check failed: ${err.message}`);
+  }
+  console.log("");
+  if (issues === 0 && warnings === 0) {
+    console.log("\x1B[32m\u2713 All checks passed.\x1B[0m");
+  } else if (issues === 0) {
+    console.log(
+      `\x1B[33m\u26A0 ${warnings} warning(s) \u2014 theme should still work.\x1B[0m`
+    );
+  } else {
+    console.log(
+      `\x1B[31m\u2717 ${issues} error(s), ${warnings} warning(s).\x1B[0m`
+    );
+    process.exit(1);
+  }
+});
+
+// src/commands/add-section.ts
+var import_commander12 = require("commander");
+var fs12 = __toESM(require("fs"));
+var path11 = __toESM(require("path"));
+
+// src/section-library/entries/hero-with-cta.ts
+var heroWithCta = {
+  slug: "hero-with-cta",
+  name: "Hero with Call-to-Action",
+  description: "Full-bleed hero \u2014 headline, subtitle, primary + secondary buttons, optional background image",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useDirection, useTranslation } from "@numueg/theme-sdk";
+
+export default function HeroWithCta({ settings }: SectionProps) {
+  const dir = useDirection();
+  const { t } = useTranslation();
+  const align = (settings.alignment as string) || "center";
+  const headline = (settings.headline as string) || t("hero.title", "Welcome");
+  const subtitle = (settings.subtitle as string) || "";
+  const bg = settings.background_image as string | undefined;
+  const cta1 = settings.cta1_label as string | undefined;
+  const cta1Href = (settings.cta1_href as string) || "/";
+  const cta2 = settings.cta2_label as string | undefined;
+  const cta2Href = (settings.cta2_href as string) || "/";
+
+  const justify =
+    align === "left" ? "items-start text-left"
+    : align === "right" ? "items-end text-right"
+    : "items-center text-center";
+
+  return (
+    <section
+      dir={dir}
+      className="relative min-h-[60vh] flex flex-col justify-center px-6 py-20 bg-gray-900 text-white"
+      style={
+        bg
+          ? { backgroundImage: \`url(\${bg})\`, backgroundSize: "cover", backgroundPosition: "center" }
+          : undefined
+      }
+    >
+      {bg && <div className="absolute inset-0 bg-black/50" aria-hidden="true" />}
+      <div className={\`relative max-w-4xl mx-auto w-full flex flex-col \${justify}\`}>
+        <h1 className="text-4xl md:text-6xl font-bold tracking-tight">{headline}</h1>
+        {subtitle && <p className="mt-6 text-lg md:text-xl text-gray-100 max-w-2xl">{subtitle}</p>}
+        {(cta1 || cta2) && (
+          <div className="mt-10 flex flex-wrap gap-3">
+            {cta1 && (
+              <a href={cta1Href} className="bg-white text-gray-900 px-6 py-3 rounded-md font-medium hover:bg-gray-100 transition">
+                {cta1}
+              </a>
+            )}
+            {cta2 && (
+              <a href={cta2Href} className="border border-white text-white px-6 py-3 rounded-md font-medium hover:bg-white/10 transition">
+                {cta2}
+              </a>
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "hero-with-cta",
+    name: "Hero with CTA",
+    locales: { ar: { name: "\u0628\u0627\u0646\u0631 \u0631\u0626\u064A\u0633\u064A \u0645\u0639 \u0632\u0631 \u062F\u0639\u0648\u0629" } },
+    settings: [
+      {
+        type: "text",
+        id: "headline",
+        label: "Headline",
+        locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646" } },
+        default: "Welcome to our store"
+      },
+      {
+        type: "textarea",
+        id: "subtitle",
+        label: "Subtitle",
+        locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0641\u0631\u0639\u064A" } }
+      },
+      {
+        type: "image_picker",
+        id: "background_image",
+        label: "Background image",
+        locales: { ar: { label: "\u0635\u0648\u0631\u0629 \u0627\u0644\u062E\u0644\u0641\u064A\u0629" } }
+      },
+      {
+        type: "select",
+        id: "alignment",
+        label: "Content alignment",
+        locales: { ar: { label: "\u0645\u062D\u0627\u0630\u0627\u0629 \u0627\u0644\u0645\u062D\u062A\u0648\u0649" } },
+        default: "center",
+        options: [
+          { value: "left", label: "Left" },
+          { value: "center", label: "Center" },
+          { value: "right", label: "Right" }
+        ]
+      },
+      {
+        type: "text",
+        id: "cta1_label",
+        label: "Primary button label",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0632\u0631 \u0627\u0644\u0631\u0626\u064A\u0633\u064A" } }
+      },
+      {
+        type: "url",
+        id: "cta1_href",
+        label: "Primary button link",
+        locales: { ar: { label: "\u0631\u0627\u0628\u0637 \u0627\u0644\u0632\u0631 \u0627\u0644\u0631\u0626\u064A\u0633\u064A" } },
+        default: "/"
+      },
+      {
+        type: "text",
+        id: "cta2_label",
+        label: "Secondary button label",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0632\u0631 \u0627\u0644\u062B\u0627\u0646\u0648\u064A" } }
+      },
+      {
+        type: "url",
+        id: "cta2_href",
+        label: "Secondary button link",
+        locales: { ar: { label: "\u0631\u0627\u0628\u0637 \u0627\u0644\u0632\u0631 \u0627\u0644\u062B\u0627\u0646\u0648\u064A" } },
+        default: "/"
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/featured-products.ts
+var featuredProducts = {
+  slug: "featured-products",
+  name: "Featured Products",
+  description: "Grid of hand-picked products with title + price + CTA",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { ProductCard, useProducts } from "@numueg/theme-sdk";
+
+export default function FeaturedProducts({ settings }: SectionProps) {
+  const ids = (settings.product_ids as string[]) || [];
+  const limit = (settings.limit as number) || 8;
+  const title = (settings.title as string) || "Featured products";
+
+  // When specific products are picked, fetch them; otherwise fetch a
+  // top-N list from the store catalog.
+  const { products, loading } = useProducts({
+    ids: ids.length > 0 ? ids : undefined,
+    limit: ids.length > 0 ? undefined : limit,
+  });
+
+  if (loading) return <section className="py-16 text-center text-gray-500">Loading\u2026</section>;
+  if (!products.length) return null;
+
+  return (
+    <section className="py-16 px-6 max-w-7xl mx-auto">
+      <h2 className="text-2xl md:text-3xl font-semibold mb-8 text-center">{title}</h2>
+      <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
+        {products.slice(0, limit).map((p) => (
+          <ProductCard key={p.id} product={p} />
+        ))}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "featured-products",
+    name: "Featured Products",
+    locales: { ar: { name: "\u0645\u0646\u062A\u062C\u0627\u062A \u0645\u0645\u064A\u0632\u0629" } },
+    settings: [
+      {
+        type: "text",
+        id: "title",
+        label: "Section title",
+        locales: { ar: { label: "\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0642\u0633\u0645" } },
+        default: "Featured products"
+      },
+      {
+        type: "product_list",
+        id: "product_ids",
+        label: "Products to feature (leave empty for top-N)",
+        locales: { ar: { label: "\u0627\u0644\u0645\u0646\u062A\u062C\u0627\u062A \u0627\u0644\u0645\u0645\u064A\u0632\u0629 (\u0641\u0627\u0631\u063A = \u0627\u0644\u0623\u0639\u0644\u0649 \u0645\u0628\u064A\u0639\u064B\u0627)" } }
+      },
+      {
+        type: "range",
+        id: "limit",
+        label: "Max products",
+        locales: { ar: { label: "\u0627\u0644\u062D\u062F \u0627\u0644\u0623\u0642\u0635\u0649" } },
+        min: 2,
+        max: 24,
+        default: 8
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/image-with-text.ts
+var imageWithText = {
+  slug: "image-with-text",
+  name: "Image with Text",
+  description: "Two-column section: image on one side, headline + body + CTA on the other",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useDirection } from "@numueg/theme-sdk";
+
+export default function ImageWithText({ settings }: SectionProps) {
+  const dir = useDirection();
+  const image = settings.image as string | undefined;
+  const layout = (settings.image_position as string) || "left";
+  const heading = (settings.heading as string) || "";
+  const body = (settings.body as string) || "";
+  const ctaLabel = settings.cta_label as string | undefined;
+  const ctaHref = (settings.cta_href as string) || "/";
+
+  // In RTL, "left/right" semantics flip naturally with flex-row-reverse.
+  const order = layout === "right" ? "md:flex-row-reverse" : "md:flex-row";
+
+  return (
+    <section dir={dir} className="py-16 px-6 max-w-7xl mx-auto">
+      <div className={\`flex flex-col gap-10 \${order}\`}>
+        <div className="flex-1">
+          {image ? (
+            <img src={image} alt="" className="w-full h-auto rounded-lg" />
+          ) : (
+            <div className="aspect-square bg-gray-100 rounded-lg" aria-hidden="true" />
+          )}
+        </div>
+        <div className="flex-1 flex flex-col justify-center">
+          {heading && <h2 className="text-3xl font-semibold mb-4">{heading}</h2>}
+          {body && <p className="text-gray-700 leading-relaxed">{body}</p>}
+          {ctaLabel && (
+            <div className="mt-6">
+              <a href={ctaHref} className="inline-flex items-center px-6 py-3 bg-gray-900 text-white rounded-md hover:bg-gray-800 transition">
+                {ctaLabel}
+              </a>
+            </div>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "image-with-text",
+    name: "Image with Text",
+    locales: { ar: { name: "\u0635\u0648\u0631\u0629 \u0645\u0639 \u0646\u0635" } },
+    settings: [
+      {
+        type: "image_picker",
+        id: "image",
+        label: "Image",
+        locales: { ar: { label: "\u0627\u0644\u0635\u0648\u0631\u0629" } }
+      },
+      {
+        type: "select",
+        id: "image_position",
+        label: "Image position",
+        locales: { ar: { label: "\u0645\u0648\u0636\u0639 \u0627\u0644\u0635\u0648\u0631\u0629" } },
+        default: "left",
+        options: [
+          { value: "left", label: "Left" },
+          { value: "right", label: "Right" }
+        ]
+      },
+      {
+        type: "text",
+        id: "heading",
+        label: "Heading",
+        locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646" } }
+      },
+      {
+        type: "textarea",
+        id: "body",
+        label: "Body text",
+        locales: { ar: { label: "\u0627\u0644\u0646\u0635" } }
+      },
+      {
+        type: "text",
+        id: "cta_label",
+        label: "Button label (optional)",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0632\u0631 (\u0627\u062E\u062A\u064A\u0627\u0631\u064A)" } }
+      },
+      {
+        type: "url",
+        id: "cta_href",
+        label: "Button link",
+        locales: { ar: { label: "\u0631\u0627\u0628\u0637 \u0627\u0644\u0632\u0631" } },
+        default: "/"
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/newsletter-signup.ts
+var newsletterSignup = {
+  slug: "newsletter-signup",
+  name: "Newsletter Signup",
+  description: "Email capture form with merchant-supplied heading + consent copy",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { Form } from "@numueg/theme-sdk";
+
+export default function NewsletterSignup({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "Stay in touch";
+  const subheading = (settings.subheading as string) || "";
+  const placeholder = (settings.placeholder as string) || "Email address";
+  const buttonLabel = (settings.button_label as string) || "Subscribe";
+  const consent = (settings.consent_text as string) || "";
+
+  return (
+    <section className="py-16 px-6 bg-gray-50">
+      <div className="max-w-2xl mx-auto text-center">
+        <h2 className="text-2xl md:text-3xl font-semibold">{heading}</h2>
+        {subheading && <p className="mt-3 text-gray-600">{subheading}</p>}
+        <Form
+          action="/api/newsletter/subscribe"
+          method="POST"
+          className="mt-8 flex flex-col sm:flex-row gap-2 max-w-md mx-auto"
+        >
+          <input
+            type="email"
+            name="email"
+            required
+            placeholder={placeholder}
+            aria-label={placeholder}
+            className="flex-1 px-4 py-3 rounded-md border border-gray-300 focus:outline-none focus:ring-2 focus:ring-gray-900"
+          />
+          <button
+            type="submit"
+            className="px-6 py-3 bg-gray-900 text-white rounded-md hover:bg-gray-800 transition"
+          >
+            {buttonLabel}
+          </button>
+        </Form>
+        {consent && <p className="mt-3 text-xs text-gray-500">{consent}</p>}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "newsletter-signup",
+    name: "Newsletter Signup",
+    locales: { ar: { name: "\u0627\u0634\u062A\u0631\u0627\u0643 \u0641\u064A \u0627\u0644\u0646\u0634\u0631\u0629" } },
+    settings: [
+      {
+        type: "text",
+        id: "heading",
+        label: "Heading",
+        locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646" } },
+        default: "Stay in touch"
+      },
+      {
+        type: "text",
+        id: "subheading",
+        label: "Subheading",
+        locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0641\u0631\u0639\u064A" } }
+      },
+      {
+        type: "text",
+        id: "placeholder",
+        label: "Input placeholder",
+        locales: { ar: { label: "\u0646\u0635 \u062A\u0648\u0636\u064A\u062D\u064A" } },
+        default: "Email address"
+      },
+      {
+        type: "text",
+        id: "button_label",
+        label: "Button label",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0632\u0631" } },
+        default: "Subscribe"
+      },
+      {
+        type: "textarea",
+        id: "consent_text",
+        label: "Consent / GDPR copy (optional)",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0645\u0648\u0627\u0641\u0642\u0629 (\u0627\u062E\u062A\u064A\u0627\u0631\u064A)" } }
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/multi-column.ts
+var multiColumn = {
+  slug: "multi-column",
+  name: "Multi-column",
+  description: "2 / 3 / 4-column features grid with icon + heading + text per column",
+  component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+import { Block } from "@numueg/theme-sdk";
+
+export default function MultiColumn({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+  const heading = (settings.heading as string) || "";
+  const cols = (settings.columns as number) || 3;
+  const gridCols =
+    cols === 2 ? "md:grid-cols-2" :
+    cols === 4 ? "md:grid-cols-2 lg:grid-cols-4" :
+    "md:grid-cols-3";
+
+  return (
+    <section className="py-16 px-6 max-w-7xl mx-auto">
+      {heading && (
+        <h2 className="text-2xl md:text-3xl font-semibold text-center mb-12">{heading}</h2>
+      )}
+      <div className={\`grid grid-cols-1 \${gridCols} gap-10\`}>
+        {(blocks || []).map((block, i) => (
+          <Block key={i} block={block}>
+            {block.type === "column" && (
+              <div className="text-center">
+                {block.settings.icon ? (
+                  <img
+                    src={block.settings.icon as string}
+                    alt=""
+                    className="w-12 h-12 mx-auto mb-4"
+                  />
+                ) : null}
+                <h3 className="text-lg font-semibold mb-2">
+                  {(block.settings.title as string) || ""}
+                </h3>
+                <p className="text-gray-600">{(block.settings.text as string) || ""}</p>
+              </div>
+            )}
+          </Block>
+        ))}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "multi-column",
+    name: "Multi-column",
+    locales: { ar: { name: "\u0623\u0639\u0645\u062F\u0629 \u0645\u062A\u0639\u062F\u062F\u0629" } },
+    settings: [
+      {
+        type: "text",
+        id: "heading",
+        label: "Section heading",
+        locales: { ar: { label: "\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0642\u0633\u0645" } }
+      },
+      {
+        type: "range",
+        id: "columns",
+        label: "Number of columns",
+        locales: { ar: { label: "\u0639\u062F\u062F \u0627\u0644\u0623\u0639\u0645\u062F\u0629" } },
+        min: 2,
+        max: 4,
+        default: 3
+      }
+    ],
+    blocks: [
+      {
+        type: "column",
+        name: "Column",
+        locales: { ar: { name: "\u0639\u0645\u0648\u062F" } },
+        max_blocks: 8,
+        settings: [
+          {
+            type: "image_picker",
+            id: "icon",
+            label: "Icon",
+            locales: { ar: { label: "\u0623\u064A\u0642\u0648\u0646\u0629" } }
+          },
+          {
+            type: "text",
+            id: "title",
+            label: "Title",
+            locales: { ar: { label: "\u0627\u0644\u0639\u0646\u0648\u0627\u0646" } }
+          },
+          {
+            type: "textarea",
+            id: "text",
+            label: "Text",
+            locales: { ar: { label: "\u0627\u0644\u0646\u0635" } }
+          }
+        ]
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/testimonials.ts
+var testimonials = {
+  slug: "testimonials",
+  name: "Testimonials",
+  description: "Customer reviews carousel with quote, author, role, optional photo",
+  component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+
+export default function Testimonials({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+  const heading = (settings.heading as string) || "What our customers say";
+  return (
+    <section className="py-16 px-6 bg-gray-50">
+      <div className="max-w-5xl mx-auto">
+        <h2 className="text-2xl md:text-3xl font-semibold text-center mb-12">{heading}</h2>
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {(blocks || []).map((b, i) => (
+            <figure key={i} className="bg-white p-6 rounded-lg shadow-sm">
+              <blockquote className="text-gray-700 italic">"{(b.settings.quote as string) || ""}"</blockquote>
+              <figcaption className="mt-4 flex items-center gap-3">
+                {b.settings.photo ? <img src={b.settings.photo as string} alt="" className="w-10 h-10 rounded-full" /> : null}
+                <div>
+                  <div className="font-medium">{(b.settings.author as string) || ""}</div>
+                  {b.settings.role ? <div className="text-sm text-gray-500">{b.settings.role as string}</div> : null}
+                </div>
+              </figcaption>
+            </figure>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "testimonials",
+    name: "Testimonials",
+    locales: { ar: { name: "\u0622\u0631\u0627\u0621 \u0627\u0644\u0639\u0645\u0644\u0627\u0621" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "What our customers say" }
+    ],
+    blocks: [
+      {
+        type: "testimonial",
+        name: "Testimonial",
+        max_blocks: 12,
+        settings: [
+          { type: "textarea", id: "quote", label: "Quote" },
+          { type: "text", id: "author", label: "Author" },
+          { type: "text", id: "role", label: "Role / company" },
+          { type: "image_picker", id: "photo", label: "Photo" }
+        ]
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/faq-accordion.ts
+var faqAccordion = {
+  slug: "faq-accordion",
+  name: "FAQ Accordion",
+  description: "Collapsible question/answer pairs using native <details>/<summary>",
+  component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+
+export default function FaqAccordion({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+  const heading = (settings.heading as string) || "Frequently asked questions";
+  return (
+    <section className="py-16 px-6 max-w-3xl mx-auto">
+      <h2 className="text-2xl md:text-3xl font-semibold text-center mb-10">{heading}</h2>
+      <div className="space-y-3">
+        {(blocks || []).map((b, i) => (
+          <details key={i} className="bg-white border border-gray-200 rounded-lg group">
+            <summary className="cursor-pointer p-4 font-medium list-none flex justify-between items-center group-open:border-b">
+              <span>{(b.settings.question as string) || ""}</span>
+              <span className="text-gray-400 group-open:rotate-180 transition" aria-hidden="true">\u25BE</span>
+            </summary>
+            <div className="p-4 text-gray-700 whitespace-pre-wrap">{(b.settings.answer as string) || ""}</div>
+          </details>
+        ))}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "faq-accordion",
+    name: "FAQ Accordion",
+    locales: { ar: { name: "\u0627\u0644\u0623\u0633\u0626\u0644\u0629 \u0627\u0644\u0634\u0627\u0626\u0639\u0629" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "Frequently asked questions" }
+    ],
+    blocks: [
+      {
+        type: "qa",
+        name: "Q&A",
+        max_blocks: 30,
+        settings: [
+          { type: "text", id: "question", label: "Question" },
+          { type: "textarea", id: "answer", label: "Answer" }
+        ]
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/logo-cloud.ts
+var logoCloud = {
+  slug: "logo-cloud",
+  name: "Logo Cloud",
+  description: "Row of partner / press / payment logos in grayscale with hover restore",
+  component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+
+export default function LogoCloud({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+  const heading = (settings.heading as string) || "";
+  return (
+    <section className="py-12 px-6 bg-white">
+      <div className="max-w-7xl mx-auto">
+        {heading && <p className="text-center text-sm text-gray-500 uppercase tracking-widest mb-8">{heading}</p>}
+        <div className="flex flex-wrap items-center justify-center gap-x-12 gap-y-6">
+          {(blocks || []).map((b, i) => {
+            const src = b.settings.logo as string | undefined;
+            const alt = (b.settings.name as string) || "";
+            if (!src) return null;
+            const inner = <img src={src} alt={alt} className="h-8 md:h-10 w-auto opacity-60 hover:opacity-100 grayscale hover:grayscale-0 transition" />;
+            const href = b.settings.href as string | undefined;
+            return href ? <a key={i} href={href} target="_blank" rel="noopener noreferrer">{inner}</a> : <div key={i}>{inner}</div>;
+          })}
+        </div>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "logo-cloud",
+    name: "Logo Cloud",
+    locales: { ar: { name: "\u0634\u0639\u0627\u0631\u0627\u062A \u0627\u0644\u0634\u0631\u0643\u0627\u0621" } },
+    settings: [{ type: "text", id: "heading", label: "Heading" }],
+    blocks: [
+      {
+        type: "logo",
+        name: "Logo",
+        max_blocks: 24,
+        settings: [
+          { type: "image_picker", id: "logo", label: "Logo image" },
+          { type: "text", id: "name", label: "Brand name (alt)" },
+          { type: "url", id: "href", label: "Link (optional)" }
+        ]
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/collection-list.ts
+var collectionList = {
+  slug: "collection-list",
+  name: "Collection List",
+  description: "Grid of collection cards (image + name) linking to each collection's PLP",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { CollectionCard, useCollections } from "@numueg/theme-sdk";
+
+export default function CollectionListSection({ settings }: SectionProps) {
+  const ids = (settings.collection_ids as string[]) || [];
+  const limit = (settings.limit as number) || 6;
+  const heading = (settings.heading as string) || "Shop by collection";
+  const { collections, loading } = useCollections({
+    ids: ids.length > 0 ? ids : undefined,
+    limit: ids.length > 0 ? undefined : limit,
+  });
+  if (loading) return <section className="py-16 text-center text-gray-500">Loading\u2026</section>;
+  if (!collections.length) return null;
+  return (
+    <section className="py-16 px-6 max-w-7xl mx-auto">
+      <h2 className="text-2xl md:text-3xl font-semibold text-center mb-10">{heading}</h2>
+      <div className="grid grid-cols-2 md:grid-cols-3 gap-6">
+        {collections.slice(0, limit).map((c) => <CollectionCard key={c.id} collection={c} />)}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "collection-list",
+    name: "Collection List",
+    locales: { ar: { name: "\u0642\u0627\u0626\u0645\u0629 \u0627\u0644\u0645\u062C\u0645\u0648\u0639\u0627\u062A" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "Shop by collection" },
+      { type: "collection_list", id: "collection_ids", label: "Collections (empty = newest)" },
+      { type: "range", id: "limit", label: "Max collections", min: 2, max: 12, default: 6 }
+    ]
+  }
+};
+
+// src/section-library/entries/video-embed.ts
+var videoEmbed = {
+  slug: "video-embed",
+  name: "Video Embed",
+  description: "Responsive 16:9 video (YouTube / Vimeo / self-hosted MP4)",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+
+export default function VideoEmbed({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "";
+  const url = (settings.video_url as string) || "";
+  const poster = (settings.poster as string) || undefined;
+  const isMp4 = /\\.(mp4|webm|mov)$/i.test(url);
+
+  return (
+    <section className="py-16 px-6 max-w-5xl mx-auto">
+      {heading && <h2 className="text-2xl md:text-3xl font-semibold text-center mb-8">{heading}</h2>}
+      <div className="aspect-video bg-black rounded-lg overflow-hidden">
+        {url ? (
+          isMp4 ? (
+            <video src={url} poster={poster} controls className="w-full h-full" />
+          ) : (
+            <iframe
+              src={url}
+              title={heading || "Video"}
+              allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+              allowFullScreen
+              className="w-full h-full border-0"
+            />
+          )
+        ) : (
+          <div className="flex items-center justify-center h-full text-white/60">Set a video URL</div>
+        )}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "video-embed",
+    name: "Video Embed",
+    locales: { ar: { name: "\u0641\u064A\u062F\u064A\u0648 \u0645\u0636\u0645\u0646" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading" },
+      { type: "url", id: "video_url", label: "Video URL (YouTube / Vimeo / .mp4)" },
+      { type: "image_picker", id: "poster", label: "Poster image (mp4 only)" }
+    ]
+  }
+};
+
+// src/section-library/entries/rich-text.ts
+var richText = {
+  slug: "rich-text",
+  name: "Rich Text",
+  description: "Merchant-edited rich text block \u2014 title + paragraph(s) + optional CTA",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { RichText } from "@numueg/theme-sdk";
+
+export default function RichTextSection({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "";
+  const body = (settings.body as string) || "";
+  const align = (settings.alignment as string) || "left";
+  const cls =
+    align === "center" ? "text-center mx-auto"
+    : align === "right" ? "text-right ml-auto"
+    : "text-left";
+
+  return (
+    <section className="py-16 px-6">
+      <div className={\`max-w-3xl \${cls}\`}>
+        {heading && <h2 className="text-2xl md:text-3xl font-semibold mb-6">{heading}</h2>}
+        {body && <RichText html={body} className="prose max-w-none" />}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "rich-text",
+    name: "Rich Text",
+    locales: { ar: { name: "\u0646\u0635 \u0645\u0646\u0633\u0642" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading" },
+      { type: "richtext", id: "body", label: "Body" },
+      {
+        type: "select",
+        id: "alignment",
+        label: "Alignment",
+        default: "left",
+        options: [
+          { value: "left", label: "Left" },
+          { value: "center", label: "Center" },
+          { value: "right", label: "Right" }
+        ]
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/announcement-bar.ts
+var announcementBar = {
+  slug: "announcement-bar",
+  name: "Announcement Bar",
+  description: "Thin top-of-page bar for promos / shipping notices, optionally dismissible",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useEffect, useState } from "react";
+
+const DISMISS_KEY = "numu_announcement_dismissed";
+
+export default function AnnouncementBar({ settings }: SectionProps) {
+  const message = (settings.message as string) || "";
+  const linkLabel = settings.link_label as string | undefined;
+  const linkHref = (settings.link_href as string) || "/";
+  const dismissible = Boolean(settings.dismissible ?? true);
+  const [dismissed, setDismissed] = useState(false);
+
+  useEffect(() => {
+    if (!dismissible) return;
+    setDismissed(typeof window !== "undefined" && window.sessionStorage.getItem(DISMISS_KEY) === "1");
+  }, [dismissible]);
+
+  if (!message || dismissed) return null;
+
+  return (
+    <div role="region" aria-label="Announcement" className="bg-gray-900 text-white text-sm">
+      <div className="max-w-7xl mx-auto px-4 py-2 flex items-center justify-center gap-3 relative">
+        <p>
+          {message}
+          {linkLabel && (
+            <>
+              {" "}
+              <a href={linkHref} className="underline font-medium ml-1">{linkLabel}</a>
+            </>
+          )}
+        </p>
+        {dismissible && (
+          <button
+            type="button"
+            aria-label="Dismiss announcement"
+            onClick={() => {
+              setDismissed(true);
+              try { window.sessionStorage.setItem(DISMISS_KEY, "1"); } catch {}
+            }}
+            className="absolute end-3 text-white/70 hover:text-white"
+          >
+            \xD7
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+`,
+  schema: {
+    type: "announcement-bar",
+    name: "Announcement Bar",
+    locales: { ar: { name: "\u0634\u0631\u064A\u0637 \u0627\u0644\u0625\u0639\u0644\u0627\u0646\u0627\u062A" } },
+    settings: [
+      { type: "text", id: "message", label: "Message" },
+      { type: "text", id: "link_label", label: "Link label (optional)" },
+      { type: "url", id: "link_href", label: "Link target" },
+      { type: "checkbox", id: "dismissible", label: "Dismissible", default: true }
+    ]
+  }
+};
+
+// src/section-library/entries/countdown-timer.ts
+var countdownTimer = {
+  slug: "countdown-timer",
+  name: "Countdown Timer",
+  description: "Sale-end countdown \u2014 DD:HH:MM:SS ticking to a merchant-set target date",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useEffect, useState } from "react";
+
+function diff(target: number) {
+  const ms = Math.max(0, target - Date.now());
+  const d = Math.floor(ms / 86_400_000);
+  const h = Math.floor((ms / 3_600_000) % 24);
+  const m = Math.floor((ms / 60_000) % 60);
+  const s = Math.floor((ms / 1000) % 60);
+  return { d, h, m, s, done: ms === 0 };
+}
+
+export default function CountdownTimer({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "Sale ends in";
+  const targetIso = settings.end_at as string | undefined;
+  const target = targetIso ? Date.parse(targetIso) : 0;
+  const [t, setT] = useState(() => diff(target));
+
+  useEffect(() => {
+    if (!target) return;
+    const id = window.setInterval(() => setT(diff(target)), 1000);
+    return () => window.clearInterval(id);
+  }, [target]);
+
+  if (!targetIso) return null;
+
+  return (
+    <section className="py-12 px-6 bg-red-50 text-center">
+      <h2 className="text-xl md:text-2xl font-semibold mb-4">{heading}</h2>
+      {t.done ? (
+        <p className="text-lg text-red-700">The sale has ended.</p>
+      ) : (
+        <div className="flex justify-center gap-4 md:gap-6 font-mono">
+          {[
+            { label: "days", value: t.d },
+            { label: "hrs", value: t.h },
+            { label: "min", value: t.m },
+            { label: "sec", value: t.s },
+          ].map((u) => (
+            <div key={u.label} className="bg-white rounded-lg p-3 min-w-[64px] shadow-sm">
+              <div className="text-2xl md:text-3xl font-bold">{String(u.value).padStart(2, "0")}</div>
+              <div className="text-xs text-gray-500 uppercase">{u.label}</div>
+            </div>
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "countdown-timer",
+    name: "Countdown Timer",
+    locales: { ar: { name: "\u0639\u062F\u0627\u062F \u062A\u0646\u0627\u0632\u0644\u064A" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "Sale ends in" },
+      { type: "text", id: "end_at", label: "End date/time (ISO 8601)", default: "" }
+    ]
+  }
+};
+
+// src/section-library/entries/featured-blog-posts.ts
+var featuredBlogPosts = {
+  slug: "featured-blog-posts",
+  name: "Featured Blog Posts",
+  description: "3-up grid of recent blog articles with cover image + title + excerpt",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+
+interface Article {
+  handle: string;
+  title: string;
+  excerpt?: string | null;
+  published_at?: string | null;
+  cover_image?: string | null;
+}
+
+export default function FeaturedBlogPosts({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "From the blog";
+  // Themes can pass articles in via page.data (the blogs route ships
+  // them on /[domain]/blogs). On other pages, this section needs a
+  // merchant-supplied list of links in the schema.
+  const articles = (settings._injected_articles as Article[] | undefined) || [];
+  if (articles.length === 0) return null;
+
+  return (
+    <section className="py-16 px-6 max-w-7xl mx-auto">
+      <h2 className="text-2xl md:text-3xl font-semibold text-center mb-10">{heading}</h2>
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-8">
+        {articles.slice(0, 3).map((a) => (
+          <article key={a.handle} className="flex flex-col">
+            {a.cover_image && <img src={a.cover_image} alt="" className="aspect-[4/3] w-full object-cover rounded-md" />}
+            <h3 className="mt-4 text-lg font-semibold">
+              <a href={\`/blogs/articles/\${a.handle}\`} className="hover:underline">{a.title}</a>
+            </h3>
+            {a.published_at && (
+              <p className="text-xs text-gray-500 mt-1">{new Date(a.published_at).toLocaleDateString()}</p>
+            )}
+            {a.excerpt && <p className="mt-2 text-gray-700">{a.excerpt}</p>}
+          </article>
+        ))}
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "featured-blog-posts",
+    name: "Featured Blog Posts",
+    locales: { ar: { name: "\u0645\u0646 \u0627\u0644\u0645\u062F\u0648\u0646\u0629" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "From the blog" }
+    ]
+  }
+};
+
+// src/section-library/entries/contact-map.ts
+var contactMap = {
+  slug: "contact-map",
+  name: "Contact + Map",
+  description: "Two-column contact info (address / phone / hours) + embedded map iframe",
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+
+export default function ContactMap({ settings }: SectionProps) {
+  const heading = (settings.heading as string) || "Visit us";
+  const address = (settings.address as string) || "";
+  const phone = (settings.phone as string) || "";
+  const hours = (settings.hours as string) || "";
+  const mapUrl = (settings.map_url as string) || "";
+
+  return (
+    <section className="py-16 px-6 max-w-7xl mx-auto">
+      <h2 className="text-2xl md:text-3xl font-semibold mb-10 text-center">{heading}</h2>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-10">
+        <div className="space-y-6">
+          {address && (
+            <div>
+              <h3 className="font-semibold mb-1">Address</h3>
+              <p className="text-gray-700 whitespace-pre-line">{address}</p>
+            </div>
+          )}
+          {phone && (
+            <div>
+              <h3 className="font-semibold mb-1">Phone</h3>
+              <a href={\`tel:\${phone}\`} className="text-blue-700 hover:underline">{phone}</a>
+            </div>
+          )}
+          {hours && (
+            <div>
+              <h3 className="font-semibold mb-1">Hours</h3>
+              <p className="text-gray-700 whitespace-pre-line">{hours}</p>
+            </div>
+          )}
+        </div>
+        <div className="aspect-square md:aspect-auto bg-gray-100 rounded-lg overflow-hidden">
+          {mapUrl ? (
+            <iframe
+              src={mapUrl}
+              title="Map"
+              loading="lazy"
+              className="w-full h-full border-0"
+              referrerPolicy="no-referrer-when-downgrade"
+              allowFullScreen
+            />
+          ) : (
+            <div className="flex items-center justify-center h-full text-gray-400">Set a map embed URL</div>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "contact-map",
+    name: "Contact + Map",
+    locales: { ar: { name: "\u062A\u0648\u0627\u0635\u0644 \u0648\u062E\u0631\u064A\u0637\u0629" } },
+    settings: [
+      { type: "text", id: "heading", label: "Heading", default: "Visit us" },
+      { type: "textarea", id: "address", label: "Address" },
+      { type: "text", id: "phone", label: "Phone" },
+      { type: "textarea", id: "hours", label: "Hours" },
+      { type: "url", id: "map_url", label: "Map embed URL (Google Maps / OSM)" }
+    ]
+  }
+};
+
+// src/section-library/index.ts
+var LIBRARY = [
+  heroWithCta,
+  featuredProducts,
+  imageWithText,
+  newsletterSignup,
+  multiColumn,
+  testimonials,
+  faqAccordion,
+  logoCloud,
+  collectionList,
+  videoEmbed,
+  richText,
+  announcementBar,
+  countdownTimer,
+  featuredBlogPosts,
+  contactMap
+];
+function findEntry(slug) {
+  return LIBRARY.find((e) => e.slug === 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(
+  "--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(
+  async (name, options) => {
+    if (options.list) {
+      console.log("Built-in section library:\n");
+      for (const entry of LIBRARY) {
+        console.log(`  ${entry.slug.padEnd(24)} ${entry.description}`);
+      }
+      console.log(
+        "\nUsage: numu-theme add-section <new-name> --from-library <slug>"
+      );
+      return;
+    }
+    if (!name) {
+      console.error(
+        "Section name is required. Run with --list to see library options."
+      );
+      process.exit(1);
+    }
+    const themeDir = path11.resolve(process.cwd(), options.dir);
+    if (!fs12.existsSync(path11.join(themeDir, "theme.json"))) {
+      console.error(
+        "No theme.json in this directory. Run from a theme project root."
+      );
+      process.exit(1);
+    }
+    const slug = toKebab(name);
+    const pascal = toPascal(name);
+    let componentSource;
+    let schemaJson;
+    if (options.fromLibrary) {
+      const entry = findEntry(options.fromLibrary);
+      if (!entry) {
+        console.error(
+          `Unknown library slug: '${options.fromLibrary}'. Run --list to see options.`
+        );
+        process.exit(1);
+      }
+      componentSource = entry.component;
+      schemaJson = JSON.parse(JSON.stringify(entry.schema));
+      schemaJson.type = slug;
+    } else {
+      componentSource = emptySectionStub(pascal);
+      schemaJson = {
+        type: slug,
+        name: humanize(slug),
+        settings: [
+          {
+            type: "text",
+            id: "headline",
+            label: "Headline",
+            default: humanize(slug)
+          }
+        ]
+      };
+    }
+    const componentPath = path11.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`);
+    ensureDirOf(schemaPath);
+    fs12.writeFileSync(schemaPath, JSON.stringify(schemaJson, null, 2));
+    tryWireMain(themeDir, slug, pascal);
+    tryAddToHomePreset(themeDir, slug);
+    console.log(`\u2714 Created section '${slug}'.`);
+    console.log(`  \u2022 src/sections/${pascal}.tsx`);
+    console.log(`  \u2022 schemas/sections/${slug}.json`);
+    console.log(
+      options.fromLibrary ? `
+From library: '${options.fromLibrary}'. Edit the files to customize.` : "\nEdit the files to add your design + behavior."
+    );
+  }
+);
+function toKebab(s) {
+  return s.replace(/[_\s]+/g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9-]/g, "");
+}
+function toPascal(s) {
+  return toKebab(s).split("-").filter(Boolean).map((p) => p[0].toUpperCase() + p.slice(1)).join("");
+}
+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 });
+}
+function emptySectionStub(pascal) {
+  return `import type { SectionProps } from "@numueg/theme-sdk";
+
+export default function ${pascal}({ settings }: SectionProps) {
+  const headline = (settings.headline as string) || "${pascal}";
+  return (
+    <section className="py-16 px-6">
+      <div className="max-w-4xl mx-auto">
+        <h2 className="text-2xl font-semibold">{headline}</h2>
+      </div>
+    </section>
+  );
+}
+`;
+}
+function tryWireMain(themeDir, slug, pascal) {
+  const mainPath = path11.join(themeDir, "src/main.tsx");
+  if (!fs12.existsSync(mainPath)) return;
+  const src = fs12.readFileSync(mainPath, "utf-8");
+  if (src.includes(`./sections/${pascal}`)) return;
+  const importLine = `import ${pascal} from "./sections/${pascal}";
+`;
+  const lines = src.split("\n");
+  let lastImportIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith("import ")) lastImportIdx = i;
+  }
+  if (lastImportIdx >= 0) {
+    lines.splice(lastImportIdx + 1, 0, importLine.trimEnd());
+  } else {
+    lines.unshift(importLine.trimEnd());
+  }
+  let inserted = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/section\.type\s*===\s*['"]/.test(lines[i])) {
+      const indent = lines[i].match(/^\s*/)?.[0] ?? "        ";
+      lines.splice(
+        i,
+        0,
+        `${indent}if (section.type === "${slug}") {`,
+        `${indent}  return <${pascal} key={sectionId} settings={section.settings} />;`,
+        `${indent}}`
+      );
+      inserted = true;
+      break;
+    }
+  }
+  if (!inserted) {
+    lines.push(
+      "",
+      `// TODO: dispatch the new '${slug}' section type:`,
+      `// if (section.type === "${slug}") return <${pascal} settings={section.settings} />;`
+    );
+  }
+  fs12.writeFileSync(mainPath, lines.join("\n"));
+}
+function tryAddToHomePreset(themeDir, slug) {
+  const themeJsonPath = path11.join(themeDir, "theme.json");
+  if (!fs12.existsSync(themeJsonPath)) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs12.readFileSync(themeJsonPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const presets = parsed.presets || {};
+  const templates = presets.templates || {};
+  const home = templates.home;
+  if (!home) return;
+  const sections = home.sections || {};
+  const order = home.order || [];
+  const newKey = `${slug.replace(/-/g, "_")}_1`;
+  for (const existing of Object.values(sections)) {
+    if (existing && typeof existing === "object" && existing.type === slug)
+      return;
+  }
+  sections[newKey] = { type: slug, settings: {} };
+  order.push(newKey);
+  home.sections = sections;
+  home.order = order;
+  fs12.writeFileSync(themeJsonPath, JSON.stringify(parsed, null, 2));
+}
+
+// src/commands/add-block.ts
+var import_commander13 = 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"))) {
+    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(
+    themeDir,
+    "schemas",
+    "sections",
+    `${sectionSnake}.json`
+  );
+  if (!fs13.existsSync(schemaPath)) {
+    console.error(
+      `Section schema not found: schemas/sections/${sectionSnake}.json`
+    );
+    console.error(`Create the section first with \`numu-theme add-section ${sectionSnake}\`.`);
+    process.exit(1);
+  }
+  const schema = JSON.parse(fs13.readFileSync(schemaPath, "utf-8"));
+  schema.blocks = schema.blocks ?? [];
+  if (Array.isArray(schema.blocks) && schema.blocks.some(
+    (b) => typeof b === "object" && b !== null && b.type === blockSnake
+  )) {
+    console.error(`Block "${blockSnake}" already exists in this section.`);
+    process.exit(1);
+  }
+  schema.blocks.push({
+    type: blockSnake,
+    name: blockHuman,
+    locales: { ar: { name: blockHuman } },
+    settings: [
+      {
+        type: "text",
+        id: "label",
+        label: "Label",
+        default: blockHuman,
+        locales: { ar: { label: "\u0627\u0644\u0646\u0635" } }
+      }
+    ]
+  });
+  if (typeof schema.max_blocks !== "number") {
+    schema.max_blocks = 12;
+  }
+  fs13.writeFileSync(schemaPath, JSON.stringify(schema, null, 2) + "\n");
+  console.log(
+    `
+\x1B[32m\u2713\x1B[0m Added block "${blockSnake}" to section "${sectionSnake}":`,
+    `
+  - ${path12.relative(themeDir, schemaPath)}`,
+    `
+
+\x1B[33m\u26A0\x1B[0m The section component should iterate \`blockOrder\` and render each block by type.`,
+    `
+   Pattern:`,
+    `
+     {(blockOrder ?? []).map((id) => {`,
+    `
+       const b = blocks?.[id];`,
+    `
+       if (!b || b.disabled) return null;`,
+    `
+       if (b.type === "${blockSnake}") return <Block key={id} id={id} type="${blockSnake}">\u2026</Block>;`,
+    `
+       return null;`,
+    `
+     })}
+`
+  );
+});
+function toSnakeCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").toLowerCase();
+}
+function toPascalCase(name) {
+  return name.replace(/[_\s-]+(.)?/g, (_m, c) => c ? c.toUpperCase() : "").replace(/^(.)/, (m) => m.toUpperCase());
+}
+function humanize2(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (m) => m.toUpperCase());
+}
+
+// src/commands/pull.ts
+var import_commander14 = require("commander");
+var fs14 = __toESM(require("fs"));
+var path13 = __toESM(require("path"));
+var https2 = __toESM(require("https"));
+var http2 = __toESM(require("http"));
+async function downloadToFile(url, dest) {
+  return new Promise((resolve7, 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);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        return;
+      }
+      const out = fs14.createWriteStream(dest);
+      res.pipe(out);
+      out.on("finish", () => out.close(() => resolve7()));
+      out.on("error", reject);
+    });
+    req.on("error", reject);
+  });
+}
+async function unzip(zipPath, targetDir) {
+  const { execFileSync } = await import("child_process");
+  fs14.mkdirSync(targetDir, { recursive: true });
+  if (process.platform === "win32") {
+    execFileSync("tar", ["-xf", zipPath, "-C", targetDir], {
+      stdio: "inherit"
+    });
+  } else {
+    execFileSync("unzip", ["-q", zipPath, "-d", targetDir], {
+      stdio: "inherit"
+    });
+  }
+}
+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(
+  "-d, --dir <directory>",
+  "Target directory (default: ./<theme-id>)"
+).option(
+  "-v, --version <version>",
+  "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);
+    if (fs14.existsSync(targetDir) && !options.force) {
+      const isEmpty = fs14.readdirSync(targetDir).length === 0;
+      if (!isEmpty) {
+        console.error(
+          `Target directory ${targetDir} is not empty. Re-run with --force to overwrite.`
+        );
+        process.exit(1);
+      }
+    }
+    console.log(`Resolving theme ${themeId}\u2026`);
+    const themeRes = await apiRequest(
+      "GET",
+      `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`
+    );
+    if (themeRes.status !== 200) {
+      console.error(
+        `Theme not found (HTTP ${themeRes.status}). Double-check the slug or UUID.`
+      );
+      process.exit(1);
+    }
+    const theme = themeRes.data;
+    const versionsRes = await apiRequest(
+      "GET",
+      `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions`
+    );
+    if (versionsRes.status !== 200) {
+      console.error(
+        `Couldn't list versions (HTTP ${versionsRes.status}).`
+      );
+      process.exit(1);
+    }
+    const versions = versionsRes.data;
+    const target = options.version ? versions.find((v) => v.version_string === options.version) : versions[0];
+    if (!target) {
+      console.error(
+        options.version ? `No version "${options.version}" found for this theme.` : "No versions published for this theme yet."
+      );
+      process.exit(1);
+    }
+    if (!target.source_zip_path) {
+      console.error(
+        `Version ${target.version_string} has no source ZIP \u2014 pull is only available for versions submitted with a ZIP upload (post-Phase 7).`
+      );
+      process.exit(1);
+    }
+    console.log(`Downloading ${theme.name || themeId} ${target.version_string}\u2026`);
+    const tmpZip = path13.join(
+      require("os").tmpdir(),
+      `numu-pull-${process.pid}-${Date.now()}.zip`
+    );
+    try {
+      await downloadToFile(target.source_zip_path, tmpZip);
+      console.log(`Unpacking into ${targetDir}\u2026`);
+      fs14.rmSync(targetDir, { recursive: true, force: true });
+      await unzip(tmpZip, targetDir);
+    } finally {
+      if (fs14.existsSync(tmpZip)) {
+        fs14.unlinkSync(tmpZip);
+      }
+    }
+    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("  npm install");
+    console.log("  numu-theme dev");
+  }
+);
+
+// src/commands/delete.ts
+var import_commander15 = 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) => {
+    rl.question(`${prompt} [y/N] `, (answer) => {
+      rl.close();
+      resolve7(/^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(
+  async (themeId, options) => {
+    const isVersion = Boolean(options.version);
+    const scope = isVersion ? `version ${options.version} of ${themeId}` : `the entire theme ${themeId}`;
+    if (!options.yes) {
+      const ok = await confirm(
+        `This will permanently delete ${scope}. Existing installations may break. Continue?`
+      );
+      if (!ok) {
+        console.log("Cancelled.");
+        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);
+    if (res.status === 200 || res.status === 204) {
+      console.log(`\u2714 Deleted ${scope}.`);
+      return;
+    }
+    if (res.status === 404) {
+      console.error("Not found. Already deleted, or you don't have access.");
+      process.exit(1);
+    }
+    if (res.status === 403) {
+      console.error("Forbidden. You can only delete themes you own.");
+      process.exit(1);
+    }
+    console.error(`Delete failed (HTTP ${res.status}).`);
+    process.exit(1);
+  }
+);
+
+// src/index.ts
+var program = new import_commander16.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(pushCommand);
+program.addCommand(submitCommand);
+program.addCommand(installCommand);
+program.addCommand(loginCommand);
+program.addCommand(statusCommand);
+program.addCommand(doctorCommand);
+program.addCommand(addSectionCommand);
+program.addCommand(addBlockCommand);
+program.addCommand(pullCommand);
+program.addCommand(deleteCommand);
+program.parse();