@numueg/theme-cli 0.4.1 → 0.6.0

package/dist/index.js

@@ -878,359 +878,80 @@ function detectAuthor() {
   if (name) return name;
   return "Theme Author";
 }
-var initCommand = new import_commander.Command("init").description("Scaffold a new NUMU theme project").argument("<name>", "Theme name").option("--template <template>", "Starter template", "basic").action(async (name, _options) => {
-  const dir = path.resolve(process.cwd(), name);
-  if (fs.existsSync(dir)) {
-    console.error(`Directory "${name}" already exists`);
-    process.exit(1);
+function scaffoldRoot() {
+  const candidates = [
+    path.join(__dirname, "..", "templates", "scaffold"),
+    path.join(__dirname, "..", "..", "templates", "scaffold")
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
   }
-  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: detectAuthor(),
-        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>
+  throw new Error(
+    "Could not locate the scaffold templates. Reinstall @numueg/theme-cli."
   );
 }
-`
-  );
-  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
-    )
+var SUBSTITUTED = /* @__PURE__ */ new Set([
+  "theme.json",
+  "package.json",
+  "index.html",
+  path.join("src", "dev-entry.tsx")
+]);
+function applyTokens(content, tokens) {
+  return content.replace(
+    /__([A-Z_]+)__/g,
+    (whole, key) => key in tokens ? tokens[key] : whole
   );
-  fs.writeFileSync(
-    path.join(dir, "src/main.tsx"),
-    `import type { ComponentType } from "react";
-import { defineThemeEntry } from "@numueg/theme-sdk";
-import type { ThemeSettingsV3 } from "@numueg/theme-sdk";
-import Hero from "./sections/Hero";
-
-const SECTION_REGISTRY: Record<string, ComponentType<any>> = {
-  hero: Hero,
-};
-
-interface ThemeProps {
-  themeSettings: ThemeSettingsV3;
-  currentTemplate: string;
 }
-
-export default function Theme({ themeSettings, currentTemplate }: ThemeProps) {
-  const template =
-    themeSettings.templates?.[currentTemplate] || 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>
-  );
+function copyTree(from, to, rel, tokens) {
+  const entries = fs.readdirSync(from, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(from, entry.name);
+    const dstPath = path.join(to, entry.name);
+    const relPath = rel ? path.join(rel, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      fs.mkdirSync(dstPath, { recursive: true });
+      copyTree(srcPath, dstPath, relPath, tokens);
+    } else {
+      let content = fs.readFileSync(srcPath, "utf-8");
+      if (SUBSTITUTED.has(relPath)) content = applyTokens(content, tokens);
+      fs.writeFileSync(dstPath, content);
+    }
+  }
 }
-
-// SSR rule of thumb: everything rendered above must be deterministic and
-// browser-free (no window/document/Date.now in the render path \u2014 put those
-// in useEffect). \`numu-theme lint\` checks this for you.
-const entry = defineThemeEntry(({ themeSettings, currentTemplate }) => (
-  <Theme themeSettings={themeSettings} currentTemplate={currentTemplate} />
-));
-
-export const mount = entry.mount;
-export const createApp = entry.createApp;
-`
-  );
-  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} currentTemplate="home" />,
-  );
-`
-  );
-  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",
-          // Render-verify every template against fixtures (Phase 2).
-          verify: "numu-theme verify"
-        },
-        dependencies: { "@numueg/theme-sdk": "^0.4.0" },
-        devDependencies: {
-          "@numueg/theme-cli": "^0.4.0",
-          "@numueg/theme-plugin": "^0.4.0",
-          "@vitejs/plugin-react": "^4.3.0",
-          vite: "^6.0.0",
-          typescript: "^5.8.0",
-          "@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"
-  );
+var initCommand = new import_commander.Command("init").description("Scaffold a new NUMU theme project from the standard starter").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);
+  }
+  const themeId = name.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  const tokens = {
+    THEME_NAME: name,
+    THEME_ID: themeId,
+    PKG_NAME: themeId,
+    AUTHOR: detectAuthor(),
+    VERSION: "0.1.0"
+  };
+  console.log(`Creating NUMU theme: ${name}...`);
+  let root;
+  try {
+    root = scaffoldRoot();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  copyTree(root, dir, "", tokens);
   console.log(
     `
-Theme "${name}" created.
+Theme "${name}" created from the NUMU Starter.
 
 Next steps:
   cd ${name}
   npm install
-  npx numu-theme dev   # local preview
-  npx numu-theme build # production build
+  npx numu-theme dev     # local preview
+  npx numu-theme check   # validate
+  npx numu-theme build   # production build
 `
   );
 });
@@ -3001,21 +2722,29 @@ var featuredProducts = {
   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";
+import { ProductCard, useProducts, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function FeaturedProducts({ settings }: SectionProps) {
+  const t = useT();
   const ids = (settings.product_ids as string[]) || [];
   const limit = (settings.limit as number) || 8;
-  const title = (settings.title as string) || "Featured products";
+  const title = (settings.title as string) || t("Featured products", "\u0645\u0646\u062A\u062C\u0627\u062A \u0645\u0645\u064A\u0632\u0629");
 
-  // 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,
-  });
+  // Pull the catalog (fetching if the route didn't pre-load it), then narrow
+  // to the merchant's hand-picked ids when provided, else take the top-N.
+  const { products: all, loading } = useProducts({ fetchIfMissing: true, limit });
+  const products =
+    ids.length > 0 ? all.filter((p) => ids.includes(p.id)) : all;
 
-  if (loading) return <section className="py-16 text-center text-gray-500">Loading\u2026</section>;
+  if (loading) return <section className="py-16 text-center text-gray-500">{t("Loading\u2026", "\u062C\u0627\u0631\u064D \u0627\u0644\u062A\u062D\u0645\u064A\u0644\u2026")}</section>;
   if (!products.length) return null;
 
   return (
@@ -3067,9 +2796,18 @@ var imageWithText = {
   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";
+import { useDirection, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function ImageWithText({ settings }: SectionProps) {
+  const t = useT();
   const dir = useDirection();
   const image = settings.image as string | undefined;
   const layout = (settings.image_position as string) || "left";
@@ -3164,13 +2902,22 @@ var newsletterSignup = {
   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";
+import { Form, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function NewsletterSignup({ settings }: SectionProps) {
-  const heading = (settings.heading as string) || "Stay in touch";
+  const t = useT();
+  const heading = (settings.heading as string) || t("Stay in touch", "\u0627\u0628\u0642\u064E \u0639\u0644\u0649 \u062A\u0648\u0627\u0635\u0644");
   const subheading = (settings.subheading as string) || "";
-  const placeholder = (settings.placeholder as string) || "Email address";
-  const buttonLabel = (settings.button_label as string) || "Subscribe";
+  const placeholder = (settings.placeholder as string) || t("Email address", "\u0627\u0644\u0628\u0631\u064A\u062F \u0627\u0644\u0625\u0644\u0643\u062A\u0631\u0648\u0646\u064A");
+  const buttonLabel = (settings.button_label as string) || t("Subscribe", "\u0627\u0634\u062A\u0631\u0627\u0643");
   const consent = (settings.consent_text as string) || "";
 
   return (
@@ -3251,10 +2998,19 @@ 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";
+  component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { Block, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
-export default function MultiColumn({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+export default function MultiColumn({ settings, blocks, blockOrder }: SectionProps) {
+  const t = useT();
   const heading = (settings.heading as string) || "";
   const cols = (settings.columns as number) || 3;
   const gridCols =
@@ -3262,31 +3018,38 @@ export default function MultiColumn({ settings, blocks }: SectionProps & { block
     cols === 4 ? "md:grid-cols-2 lg:grid-cols-4" :
     "md:grid-cols-3";
 
+  // Blocks arrive as a {id: instance} map + an order array \u2014 mirror the
+  // section\u2192block render: walk the order and look each id up.
+  const map = blocks || {};
+  const order = blockOrder || Object.keys(map);
+
   return (
-    <section className="py-16 px-6 max-w-7xl mx-auto">
+    <section className="py-16 px-6 max-w-7xl mx-auto" aria-label={t("Features", "\u0627\u0644\u0645\u0645\u064A\u0632\u0627\u062A")}>
       {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" && (
+        {order.map((id) => {
+          const b = map[id];
+          if (!b || b.type !== "column") return null;
+          return (
+            <Block key={id} id={id} type={b.type}>
               <div className="text-center">
-                {block.settings.icon ? (
+                {b.settings.icon ? (
                   <img
-                    src={block.settings.icon as string}
+                    src={b.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) || ""}
+                  {(b.settings.title as string) || ""}
                 </h3>
-                <p className="text-gray-600">{(block.settings.text as string) || ""}</p>
+                <p className="text-gray-600">{(b.settings.text as string) || ""}</p>
               </div>
-            )}
-          </Block>
-        ))}
+            </Block>
+          );
+        })}
       </div>
     </section>
   );
@@ -3350,9 +3113,19 @@ var testimonials = {
   name: "Testimonials",
   description: "Customer reviews carousel with quote, author, role, optional photo",
   component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function Testimonials({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
-  const heading = (settings.heading as string) || "What our customers say";
+  const t = useT();
+  const heading = (settings.heading as string) || t("What our customers say", "\u0622\u0631\u0627\u0621 \u0639\u0645\u0644\u0627\u0626\u0646\u0627");
   return (
     <section className="py-16 px-6 bg-gray-50">
       <div className="max-w-5xl mx-auto">
@@ -3405,9 +3178,19 @@ var faqAccordion = {
   name: "FAQ Accordion",
   description: "Collapsible question/answer pairs using native <details>/<summary>",
   component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function FaqAccordion({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
-  const heading = (settings.heading as string) || "Frequently asked questions";
+  const t = useT();
+  const heading = (settings.heading as string) || t("Frequently asked questions", "\u0627\u0644\u0623\u0633\u0626\u0644\u0629 \u0627\u0644\u0634\u0627\u0626\u0639\u0629");
   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>
@@ -3453,8 +3236,18 @@ var logoCloud = {
   name: "Logo Cloud",
   description: "Row of partner / press / payment logos in grayscale with hover restore",
   component: `import type { SectionProps, BlockProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function LogoCloud({ settings, blocks }: SectionProps & { blocks?: BlockProps[] }) {
+  const t = useT();
   const heading = (settings.heading as string) || "";
   return (
     <section className="py-12 px-6 bg-white">
@@ -3501,17 +3294,25 @@ var collectionList = {
   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";
+import { CollectionCard, useCollections, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function CollectionListSection({ settings }: SectionProps) {
+  const t = useT();
   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>;
+  const heading = (settings.heading as string) || t("Shop by collection", "\u062A\u0633\u0648\u0651\u0642 \u062D\u0633\u0628 \u0627\u0644\u0645\u062C\u0645\u0648\u0639\u0629");
+  const { collections: all, loading } = useCollections({ fetchIfMissing: true, limit });
+  const collections =
+    ids.length > 0 ? all.filter((c) => ids.includes(c.id)) : all;
+  if (loading) return <section className="py-16 text-center text-gray-500">{t("Loading\u2026", "\u062C\u0627\u0631\u064D \u0627\u0644\u062A\u062D\u0645\u064A\u0644\u2026")}</section>;
   if (!collections.length) return null;
   return (
     <section className="py-16 px-6 max-w-7xl mx-auto">
@@ -3541,8 +3342,18 @@ var videoEmbed = {
   name: "Video Embed",
   description: "Responsive 16:9 video (YouTube / Vimeo / self-hosted MP4)",
   component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function VideoEmbed({ settings }: SectionProps) {
+  const t = useT();
   const heading = (settings.heading as string) || "";
   const url = (settings.video_url as string) || "";
   const poster = (settings.poster as string) || undefined;
@@ -3558,14 +3369,14 @@ export default function VideoEmbed({ settings }: SectionProps) {
           ) : (
             <iframe
               src={url}
-              title={heading || "Video"}
+              title={heading || t("Video", "\u0641\u064A\u062F\u064A\u0648")}
               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 className="flex items-center justify-center h-full text-white/60">{t("Set a video URL", "\u0623\u062F\u062E\u0644 \u0631\u0627\u0628\u0637 \u0627\u0644\u0641\u064A\u062F\u064A\u0648")}</div>
         )}
       </div>
     </section>
@@ -3590,9 +3401,18 @@ var richText = {
   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";
+import { RichText, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function RichTextSection({ settings }: SectionProps) {
+  const t = useT();
   const heading = (settings.heading as string) || "";
   const body = (settings.body as string) || "";
   const align = (settings.alignment as string) || "left";
@@ -3639,11 +3459,21 @@ var announcementBar = {
   name: "Announcement Bar",
   description: "Thin top-of-page bar for promos / shipping notices, optionally dismissible",
   component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
 import { useEffect, useState } from "react";
 
 const DISMISS_KEY = "numu_announcement_dismissed";
 
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+
 export default function AnnouncementBar({ settings }: SectionProps) {
+  const t = useT();
   const message = (settings.message as string) || "";
   const linkLabel = settings.link_label as string | undefined;
   const linkHref = (settings.link_href as string) || "/";
@@ -3658,7 +3488,7 @@ export default function AnnouncementBar({ settings }: SectionProps) {
   if (!message || dismissed) return null;
 
   return (
-    <div role="region" aria-label="Announcement" className="bg-gray-900 text-white text-sm">
+    <div role="region" aria-label={t("Announcement", "\u0625\u0639\u0644\u0627\u0646")} 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}
@@ -3672,7 +3502,7 @@ export default function AnnouncementBar({ settings }: SectionProps) {
         {dismissible && (
           <button
             type="button"
-            aria-label="Dismiss announcement"
+            aria-label={t("Dismiss announcement", "\u0625\u063A\u0644\u0627\u0642 \u0627\u0644\u0625\u0639\u0644\u0627\u0646")}
             onClick={() => {
               setDismissed(true);
               try { window.sessionStorage.setItem(DISMISS_KEY, "1"); } catch {}
@@ -3706,8 +3536,17 @@ var countdownTimer = {
   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 { useLocale } from "@numueg/theme-sdk";
 import { useEffect, useState } from "react";
 
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+
 function diff(target: number) {
   const ms = Math.max(0, target - Date.now());
   const d = Math.floor(ms / 86_400_000);
@@ -3718,14 +3557,15 @@ function diff(target: number) {
 }
 
 export default function CountdownTimer({ settings }: SectionProps) {
-  const heading = (settings.heading as string) || "Sale ends in";
+  const t = useT();
+  const heading = (settings.heading as string) || t("Sale ends in", "\u064A\u0646\u062A\u0647\u064A \u0627\u0644\u0639\u0631\u0636 \u062E\u0644\u0627\u0644");
   const targetIso = settings.end_at as string | undefined;
   const target = targetIso ? Date.parse(targetIso) : 0;
-  const [t, setT] = useState(() => diff(target));
+  const [time, setTime] = useState(() => diff(target));
 
   useEffect(() => {
     if (!target) return;
-    const id = window.setInterval(() => setT(diff(target)), 1000);
+    const id = window.setInterval(() => setTime(diff(target)), 1000);
     return () => window.clearInterval(id);
   }, [target]);
 
@@ -3734,17 +3574,17 @@ export default function CountdownTimer({ settings }: SectionProps) {
   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>
+      {time.done ? (
+        <p className="text-lg text-red-700">{t("The sale has ended.", "\u0627\u0646\u062A\u0647\u0649 \u0627\u0644\u0639\u0631\u0636.")}</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 },
+            { key: "days", label: t("days", "\u0623\u064A\u0627\u0645"), value: time.d },
+            { key: "hrs", label: t("hrs", "\u0633\u0627\u0639\u0627\u062A"), value: time.h },
+            { key: "min", label: t("min", "\u062F\u0642\u0627\u0626\u0642"), value: time.m },
+            { key: "sec", label: t("sec", "\u062B\u0648\u0627\u0646\u064D"), value: time.s },
           ].map((u) => (
-            <div key={u.label} className="bg-white rounded-lg p-3 min-w-[64px] shadow-sm">
+            <div key={u.key} 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>
@@ -3772,6 +3612,7 @@ var featuredBlogPosts = {
   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";
+import { useLocale } from "@numueg/theme-sdk";
 
 interface Article {
   handle: string;
@@ -3781,8 +3622,17 @@ interface Article {
   cover_image?: string | null;
 }
 
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+
 export default function FeaturedBlogPosts({ settings }: SectionProps) {
-  const heading = (settings.heading as string) || "From the blog";
+  const t = useT();
+  const heading = (settings.heading as string) || t("From the blog", "\u0645\u0646 \u0627\u0644\u0645\u062F\u0648\u0646\u0629");
   // 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.
@@ -3826,9 +3676,19 @@ var contactMap = {
   name: "Contact + Map",
   description: "Two-column contact info (address / phone / hours) + embedded map iframe",
   component: `import type { SectionProps } from "@numueg/theme-sdk";
+import { useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
 
 export default function ContactMap({ settings }: SectionProps) {
-  const heading = (settings.heading as string) || "Visit us";
+  const t = useT();
+  const heading = (settings.heading as string) || t("Visit us", "\u0632\u0648\u0631\u0648\u0646\u0627");
   const address = (settings.address as string) || "";
   const phone = (settings.phone as string) || "";
   const hours = (settings.hours as string) || "";
@@ -3841,19 +3701,19 @@ export default function ContactMap({ settings }: SectionProps) {
         <div className="space-y-6">
           {address && (
             <div>
-              <h3 className="font-semibold mb-1">Address</h3>
+              <h3 className="font-semibold mb-1">{t("Address", "\u0627\u0644\u0639\u0646\u0648\u0627\u0646")}</h3>
               <p className="text-gray-700 whitespace-pre-line">{address}</p>
             </div>
           )}
           {phone && (
             <div>
-              <h3 className="font-semibold mb-1">Phone</h3>
+              <h3 className="font-semibold mb-1">{t("Phone", "\u0627\u0644\u0647\u0627\u062A\u0641")}</h3>
               <a href={\`tel:\${phone}\`} className="text-blue-700 hover:underline">{phone}</a>
             </div>
           )}
           {hours && (
             <div>
-              <h3 className="font-semibold mb-1">Hours</h3>
+              <h3 className="font-semibold mb-1">{t("Hours", "\u0633\u0627\u0639\u0627\u062A \u0627\u0644\u0639\u0645\u0644")}</h3>
               <p className="text-gray-700 whitespace-pre-line">{hours}</p>
             </div>
           )}
@@ -3862,14 +3722,14 @@ export default function ContactMap({ settings }: SectionProps) {
           {mapUrl ? (
             <iframe
               src={mapUrl}
-              title="Map"
+              title={t("Map", "\u062E\u0631\u064A\u0637\u0629")}
               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 className="flex items-center justify-center h-full text-gray-400">{t("Set a map embed URL", "\u0623\u0636\u0641 \u0631\u0627\u0628\u0637 \u062A\u0636\u0645\u064A\u0646 \u0627\u0644\u062E\u0631\u064A\u0637\u0629")}</div>
           )}
         </div>
       </div>
@@ -3891,6 +3751,547 @@ export default function ContactMap({ settings }: SectionProps) {
   }
 };
 
+// src/section-library/entries/product-details.ts
+var productDetails = {
+  slug: "product-details",
+  name: "Product Details",
+  description: "PDP buy box: gallery, variant/size pickers (size-chart aware) that gate add-to-cart",
+  component: `import { useState } from "react";
+import type { SectionProps } from "@numueg/theme-sdk";
+import {
+  useProductOptional,
+  useVariantSelection,
+  useProductSizeChart,
+  useCart,
+  useLocalization,
+  useShop,
+  useLocale,
+  defaultVariant,
+} from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+// Coerce API money (often string-decimals) before any math.
+const toNum = (v: unknown) => Number(v) || 0;
+
+/**
+ * Product detail buy box. Renders the variant picker from real option axes
+ * when present; otherwise derives required size buttons from the product's
+ * size chart (common single-SKU case) and gates add-to-cart on a size pick \u2014
+ * recording the chosen size on the cart note so the merchant fulfils it.
+ */
+export default function ProductDetails({ settings }: SectionProps) {
+  const t = useT();
+  const product = useProductOptional();
+  const { cart, addItem, updateNote } = useCart();
+  const { formatMoney } = useLocalization();
+  const shop = useShop();
+  const chart = useProductSizeChart();
+  const [qty, setQty] = useState(1);
+  const [pickedSize, setPickedSize] = useState<string | undefined>(undefined);
+  const [pending, setPending] = useState(false);
+
+  const variantSel = useVariantSelection(
+    product ?? { options: [], variants: [] },
+    { autoSelect: true },
+  );
+
+  if (!product) {
+    return (
+      <section className="py-16 px-6 text-center text-gray-500">
+        {t("Product not found.", "\u0644\u0645 \u064A\u062A\u0645 \u0627\u0644\u0639\u062B\u0648\u0631 \u0639\u0644\u0649 \u0627\u0644\u0645\u0646\u062A\u062C.")}
+      </section>
+    );
+  }
+
+  const opts = product.options ?? [];
+  const variants = product.variants ?? [];
+  const hasOptions = opts.length > 0;
+  const { selection, variant, select, availability, isComplete } = variantSel;
+
+  const chartSizes = (chart?.rows ?? [])
+    .map((r) => r.size)
+    .filter((sz): sz is string => Boolean(sz));
+  const needsSize = !hasOptions && variants.length <= 1 && chartSizes.length > 0;
+
+  const activeVariant = hasOptions
+    ? variant
+    : (defaultVariant(product) ?? variants[0] ?? null);
+  const currency = product.currency || shop?.currency;
+  const price = toNum(activeVariant?.price ?? product.price);
+  const images = product.images ?? [];
+  const productName = product.name;
+  const productId = product.id;
+
+  const purchasable =
+    product.in_stock &&
+    (activeVariant?.is_in_stock ?? true) &&
+    (hasOptions ? isComplete : true) &&
+    (needsSize ? Boolean(pickedSize) : true);
+
+  async function handleAdd() {
+    if (pending || !purchasable) return;
+    setPending(true);
+    try {
+      if (needsSize && pickedSize) {
+        const prefix = "\u2022 " + productName + " \u2014 ";
+        const tag = prefix + t("Size", "\u0627\u0644\u0645\u0642\u0627\u0633") + ": ";
+        const prev = cart?.note ?? "";
+        const kept = prev
+          .split("\\n")
+          .filter((line) => line && !line.startsWith(prefix))
+          .join("\\n");
+        await updateNote((kept ? kept + "\\n" : "") + tag + pickedSize);
+      }
+      await addItem(productId, activeVariant?.id, qty);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  const box =
+    "min-w-[3rem] h-12 px-3 inline-flex items-center justify-center border rounded-md text-sm font-medium";
+  const boxActive = "bg-black text-white border-black";
+
+  return (
+    <section className="py-10 px-6 max-w-6xl mx-auto grid grid-cols-1 md:grid-cols-2 gap-10">
+      <div>
+        {images[0] ? (
+          <img
+            src={images[0].url}
+            alt={images[0].alt || productName}
+            className="w-full aspect-square object-cover rounded-lg bg-gray-100"
+          />
+        ) : (
+          <div className="w-full aspect-square rounded-lg bg-gray-100" />
+        )}
+      </div>
+
+      <div>
+        <h1 className="text-2xl font-bold mb-2">{productName}</h1>
+        <p className="text-xl font-semibold mb-6">
+          {formatMoney(price, currency)}
+        </p>
+
+        {opts.map((opt) => (
+          <div key={opt.name} className="mb-5">
+            <span className="block text-sm font-semibold mb-2">{opt.name}</span>
+            <div className="flex flex-wrap gap-2">
+              {opt.values.map((value) => {
+                const sel = selection[opt.name] === value;
+                const reachable = availability[opt.name]?.has(value) ?? true;
+                return (
+                  <button
+                    key={value}
+                    type="button"
+                    disabled={!reachable && !sel}
+                    onClick={() => select(opt.name, value)}
+                    className={box + (sel ? " " + boxActive : "") + (!reachable && !sel ? " opacity-40 line-through" : "")}
+                  >
+                    {value}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        ))}
+
+        {needsSize ? (
+          <div className="mb-5">
+            <span className="block text-sm font-semibold mb-2">
+              {t("Size", "\u0627\u0644\u0645\u0642\u0627\u0633")}
+            </span>
+            <div className="flex flex-wrap gap-2">
+              {chartSizes.map((sz) => (
+                <button
+                  key={sz}
+                  type="button"
+                  onClick={() => setPickedSize(sz)}
+                  className={box + (pickedSize === sz ? " " + boxActive : "")}
+                >
+                  {sz}
+                </button>
+              ))}
+            </div>
+            {!pickedSize ? (
+              <p className="text-xs text-red-600 mt-2">
+                {t("Please select a size", "\u0627\u062E\u062A\u0631 \u0627\u0644\u0645\u0642\u0627\u0633 \u0645\u0646 \u0641\u0636\u0644\u0643")}
+              </p>
+            ) : null}
+          </div>
+        ) : null}
+
+        <div className="flex items-center gap-3 mb-5">
+          <span className="text-sm font-semibold">{t("Quantity", "\u0627\u0644\u0643\u0645\u064A\u0629")}</span>
+          <div className="inline-flex items-center border rounded-md">
+            <button type="button" className="px-3 py-2" onClick={() => setQty((q) => Math.max(1, q - 1))}>
+              \u2212
+            </button>
+            <span className="px-3">{qty}</span>
+            <button type="button" className="px-3 py-2" onClick={() => setQty((q) => q + 1)}>
+              +
+            </button>
+          </div>
+        </div>
+
+        <button
+          type="button"
+          disabled={!purchasable || pending}
+          onClick={handleAdd}
+          className="w-full py-3 rounded-full bg-black text-white font-semibold disabled:opacity-50"
+        >
+          {pending
+            ? "\u2026"
+            : !product.in_stock
+              ? t("Sold out", "\u0646\u0641\u0630 \u0627\u0644\u0645\u062E\u0632\u0648\u0646")
+              : needsSize && !pickedSize
+                ? t("Select a size", "\u0627\u062E\u062A\u0631 \u0627\u0644\u0645\u0642\u0627\u0633")
+                : (settings.add_to_cart_label as string) ||
+                  t("Add to cart", "\u0623\u0636\u0641 \u0625\u0644\u0649 \u0627\u0644\u0633\u0644\u0629")}
+        </button>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "product-details",
+    name: "Product Details",
+    locales: { ar: { name: "\u062A\u0641\u0627\u0635\u064A\u0644 \u0627\u0644\u0645\u0646\u062A\u062C" } },
+    settings: [
+      {
+        type: "text",
+        id: "add_to_cart_label",
+        label: "Add-to-cart label",
+        locales: { ar: { label: "\u0646\u0635 \u0632\u0631 \u0627\u0644\u0625\u0636\u0627\u0641\u0629" } },
+        default: "Add to cart"
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/frequently-bought.ts
+var frequentlyBought = {
+  slug: "frequently-bought",
+  name: "Frequently Bought Together",
+  description: "Bundle the current product with related items; checkboxes + one-tap add-all",
+  component: `import { useMemo, useState } from "react";
+import type { SectionProps } from "@numueg/theme-sdk";
+import {
+  useProductOptional,
+  useRelatedProducts,
+  useProducts,
+  useCart,
+  useLocalization,
+  useShop,
+  useLocale,
+  type Product,
+} from "@numueg/theme-sdk";
+
+// --- Standards (self-contained so the snippet stays forkable) -------------
+// Bilingual AR/EN text without a shared import.
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+// Coerce API money (often string-decimals) so totals add instead of concat.
+const toNum = (v: unknown) => Number(v) || 0;
+// Tolerate images as {url} objects OR raw url strings.
+const imgUrl = (p?: Product) => {
+  const raw = p?.images?.[0] as unknown;
+  return typeof raw === "string"
+    ? raw
+    : (raw as { url?: string } | undefined)?.url;
+};
+
+interface FbtSettings {
+  title?: string;
+  max_items?: number;
+}
+
+/**
+ * Frequently bought together \u2014 seeds the bundle with the current product and
+ * appends related items, falling back to the catalog. Each row is a toggle;
+ * "add all" adds every checked product in one pass. Hidden when < 2 items.
+ */
+export default function FrequentlyBought({ settings }: SectionProps) {
+  const s = settings as FbtSettings;
+  const t = useT();
+  const max = Math.max(2, Math.min(4, s.max_items ?? 3));
+
+  const product = useProductOptional();
+  const related = useRelatedProducts(product?.id, { limit: max });
+  const catalog = useProducts({ fetchIfMissing: true });
+  const { addItem } = useCart();
+  const { formatMoney } = useLocalization();
+  const shop = useShop();
+
+  const bundle = useMemo(() => {
+    const pool = related.items.length > 0 ? related.items : catalog.products;
+    const seen = new Set<string>();
+    const list: Product[] = [];
+    if (product) {
+      list.push(product);
+      seen.add(product.id);
+    }
+    for (const p of pool) {
+      if (list.length >= max) break;
+      if (seen.has(p.id)) continue;
+      seen.add(p.id);
+      list.push(p);
+    }
+    return list;
+  }, [product, related.items, catalog.products, max]);
+
+  const [selected, setSelected] = useState<Record<string, boolean>>({});
+  const isOn = (id: string) => selected[id] !== false; // default on
+  const [pending, setPending] = useState(false);
+
+  const currency = product?.currency || shop?.currency;
+  const total = bundle
+    .filter((p) => isOn(p.id))
+    .reduce((sum, p) => sum + toNum(p.price), 0);
+
+  if (bundle.length < 2) return null;
+
+  async function addAll() {
+    if (pending) return;
+    setPending(true);
+    try {
+      for (const p of bundle) {
+        if (!isOn(p.id)) continue;
+        await addItem(p.id, p.variants?.[0]?.id, 1);
+      }
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <section className="py-12 px-6 max-w-3xl mx-auto">
+      <h2 className="text-lg font-semibold mb-4">
+        {s.title || t("Frequently bought together", "\u064A\u064F\u0634\u062A\u0631\u0649 \u0639\u0627\u062F\u0629\u064B \u0645\u0639\u0627\u064B")}
+      </h2>
+      <div className="flex flex-wrap items-stretch gap-3">
+        {bundle.map((p, i) => (
+          <div key={p.id} className="flex items-center gap-3">
+            <label className="flex items-center gap-3 border rounded-lg p-3 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={isOn(p.id)}
+                onChange={(e) =>
+                  setSelected((prev) => ({ ...prev, [p.id]: e.target.checked }))
+                }
+              />
+              {imgUrl(p) ? (
+                <img
+                  src={imgUrl(p)}
+                  alt={p.name}
+                  loading="lazy"
+                  className="w-12 h-12 object-cover rounded"
+                />
+              ) : (
+                <span className="w-12 h-12 rounded bg-gray-100" />
+              )}
+              <span className="text-sm">
+                <span className="block font-medium">{p.name}</span>
+                <span className="block text-gray-500">
+                  {formatMoney(toNum(p.price), currency)}
+                </span>
+              </span>
+            </label>
+            {i < bundle.length - 1 ? (
+              <span className="text-gray-400" aria-hidden="true">
+                +
+              </span>
+            ) : null}
+          </div>
+        ))}
+      </div>
+      <div className="flex items-center justify-between mt-5">
+        <p className="text-sm">
+          {t("Total", "\u0627\u0644\u0625\u062C\u0645\u0627\u0644\u064A")}:{" "}
+          <strong>{formatMoney(total, currency)}</strong>
+        </p>
+        <button
+          type="button"
+          disabled={pending || total <= 0}
+          onClick={addAll}
+          className="px-5 py-2.5 rounded-full bg-black text-white text-sm font-semibold disabled:opacity-50"
+        >
+          {pending ? "\u2026" : t("Add all to cart", "\u0623\u0636\u0641 \u0627\u0644\u0643\u0644 \u0644\u0644\u0633\u0644\u0629")}
+        </button>
+      </div>
+    </section>
+  );
+}
+`,
+  schema: {
+    type: "frequently-bought",
+    name: "Frequently Bought Together",
+    locales: { ar: { name: "\u064A\u064F\u0634\u062A\u0631\u0649 \u0645\u0639\u0627\u064B" } },
+    settings: [
+      {
+        type: "text",
+        id: "title",
+        label: "Section title",
+        locales: { ar: { label: "\u0639\u0646\u0648\u0627\u0646 \u0627\u0644\u0642\u0633\u0645" } },
+        default: "Frequently bought together"
+      },
+      {
+        type: "range",
+        id: "max_items",
+        label: "Max items in bundle",
+        locales: { ar: { label: "\u0623\u0642\u0635\u0649 \u0639\u062F\u062F \u0644\u0644\u0645\u0646\u062A\u062C\u0627\u062A" } },
+        min: 2,
+        max: 4,
+        default: 3
+      }
+    ]
+  }
+};
+
+// src/section-library/entries/size-guide.ts
+var sizeGuide = {
+  slug: "size-guide",
+  name: "Size Guide",
+  description: "Size-chart trigger + modal table, resolved from the product/store size chart",
+  component: `import { useState } from "react";
+import type { SectionProps } from "@numueg/theme-sdk";
+import { useProductSizeChart, useLocale } from "@numueg/theme-sdk";
+
+// Bilingual AR/EN text without a shared import (keeps the snippet forkable).
+function useT() {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en: string, ar: string) => (isAr ? ar : en);
+}
+
+/**
+ * Size guide \u2014 renders a trigger button and a modal table. The chart is
+ * resolved by the SDK from the product chart (\`product.attributes.size_chart\`)
+ * with a fallback to the store-wide default. Renders nothing when there's no
+ * chart to show, or when an enabled chart is still empty.
+ */
+export default function SizeGuide({ settings }: SectionProps) {
+  const t = useT();
+  const [open, setOpen] = useState(false);
+  const chart = useProductSizeChart();
+
+  const hasContent =
+    !!chart &&
+    ((chart.rows?.length ?? 0) > 0 || Boolean(chart.image_url));
+  if (!hasContent || !chart) return null;
+
+  const label = (settings.label as string) || t("Size guide", "\u062F\u0644\u064A\u0644 \u0627\u0644\u0645\u0642\u0627\u0633\u0627\u062A");
+
+  return (
+    <div className="py-4 px-6 max-w-3xl mx-auto">
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="inline-flex items-center gap-2 text-sm font-medium underline underline-offset-4"
+      >
+        {label}
+      </button>
+
+      {open ? (
+        <div
+          role="dialog"
+          aria-modal="true"
+          aria-label={label}
+          className="fixed inset-0 z-50 flex items-center justify-center p-4"
+        >
+          <div
+            className="absolute inset-0 bg-black/50"
+            onClick={() => setOpen(false)}
+          />
+          <div className="relative bg-white rounded-xl max-w-lg w-full max-h-[85vh] overflow-auto p-6">
+            <div className="flex items-center justify-between mb-4">
+              <h2 className="text-lg font-semibold">
+                {label}
+                {chart.unit ? " (" + chart.unit + ")" : ""}
+              </h2>
+              <button
+                type="button"
+                onClick={() => setOpen(false)}
+                aria-label={t("Close", "\u0625\u063A\u0644\u0627\u0642")}
+                className="p-1"
+              >
+                \u2715
+              </button>
+            </div>
+            {chart.image_url ? (
+              <img
+                src={chart.image_url}
+                alt=""
+                className="w-full rounded mb-4"
+              />
+            ) : null}
+            {chart.rows?.length ? (
+              <table className="w-full text-sm border-collapse">
+                <thead>
+                  <tr>
+                    <th className="text-start p-2 border-b">
+                      {t("Size", "\u0627\u0644\u0645\u0642\u0627\u0633")}
+                    </th>
+                    {chart.column_headers.map((h, i) => (
+                      <th key={i} className="text-start p-2 border-b">
+                        {h}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {chart.rows.map((row, ri) => (
+                    <tr key={ri}>
+                      <th scope="row" className="text-start p-2 border-b font-medium">
+                        {row.size}
+                      </th>
+                      {chart.column_headers.map((_, ci) => (
+                        <td key={ci} className="p-2 border-b">
+                          {row.values[ci] ?? "\u2014"}
+                        </td>
+                      ))}
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            ) : null}
+            {chart.notes ? (
+              <p className="text-xs text-gray-500 mt-4">{chart.notes}</p>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+`,
+  schema: {
+    type: "size-guide",
+    name: "Size Guide",
+    locales: { ar: { name: "\u062F\u0644\u064A\u0644 \u0627\u0644\u0645\u0642\u0627\u0633\u0627\u062A" } },
+    settings: [
+      {
+        type: "text",
+        id: "label",
+        label: "Trigger label",
+        locales: { ar: { label: "\u0646\u0635 \u0627\u0644\u0632\u0631" } },
+        default: "Size guide"
+      }
+    ]
+  }
+};
+
 // src/section-library/index.ts
 var LIBRARY = [
   heroWithCta,
@@ -3907,7 +4308,10 @@ var LIBRARY = [
   announcementBar,
   countdownTimer,
   featuredBlogPosts,
-  contactMap
+  contactMap,
+  productDetails,
+  frequentlyBought,
+  sizeGuide
 ];
 function findEntry(slug) {
   return LIBRARY.find((e) => e.slug === slug);
@@ -3972,7 +4376,7 @@ var addSectionCommand = new import_commander13.Command("add-section").descriptio
         ]
       };
     }
-    const componentPath = path12.join(themeDir, "src/sections", `${pascal}.tsx`);
+    const componentPath = path12.join(themeDir, "src/sections", `${slug}.tsx`);
     ensureDirOf(componentPath);
     if (fs12.existsSync(componentPath)) {
       console.error(`Already exists: ${componentPath}`);
@@ -3985,7 +4389,7 @@ var addSectionCommand = new import_commander13.Command("add-section").descriptio
     tryWireMain(themeDir, slug, pascal);
     tryAddToHomePreset(themeDir, slug);
     console.log(`\u2714 Created section '${slug}'.`);
-    console.log(`  \u2022 src/sections/${pascal}.tsx`);
+    console.log(`  \u2022 src/sections/${slug}.tsx`);
     console.log(`  \u2022 schemas/sections/${slug}.json`);
     console.log(
       options.fromLibrary ? `
@@ -4024,8 +4428,8 @@ function tryWireMain(themeDir, slug, pascal) {
   const mainPath = path12.join(themeDir, "src/main.tsx");
   if (!fs12.existsSync(mainPath)) return;
   const src = fs12.readFileSync(mainPath, "utf-8");
-  if (src.includes(`./sections/${pascal}`)) return;
-  const importLine = `import ${pascal} from "./sections/${pascal}";
+  if (src.includes(`./sections/${slug}"`)) return;
+  const importLine = `import ${pascal} from "./sections/${slug}";
 `;
   const lines = src.split("\n");
   let lastImportIdx = -1;
@@ -4037,6 +4441,14 @@ function tryWireMain(themeDir, slug, pascal) {
   } else {
     lines.unshift(importLine.trimEnd());
   }
+  for (let i = 0; i < lines.length; i++) {
+    if (/SECTION_REGISTRY[^=]*=\s*\{/.test(lines[i])) {
+      const indent = (lines[i].match(/^\s*/)?.[0] ?? "") + "  ";
+      lines.splice(i + 1, 0, `${indent}"${slug}": ${pascal},`);
+      fs12.writeFileSync(mainPath, lines.join("\n"));
+      return;
+    }
+  }
   let inserted = false;
   for (let i = 0; i < lines.length; i++) {
     if (/section\.type\s*===\s*['"]/.test(lines[i])) {