create-brainerce-store 1.80.0 → 1.82.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.80.0",
+      version: "1.82.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -330,6 +330,26 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // both to show the merchant's welcome offer beside the field. On an older
   // SDK a scaffolded store fails type-check at creation, exactly like the KIT
   // floor above — so this floor is load-bearing, not cosmetic.
+  //
+  // ⛔⛔ RAISING THIS FLOOR: the version you pin must already be at least SEVEN
+  // DAYS OLD on npm, and template code must not call an SDK API until the
+  // version carrying it has aged that long.
+  //
+  // `minimumReleaseAge` — a package-age cooldown that refuses any dependency
+  // published within the last week — is now a standard supply-chain defence.
+  // pnpm ships the setting (`minimumReleaseAge: 10080`), and ChatGPT Sites
+  // enforces seven days on publish. Our SDK cadence is close to daily, so a
+  // floor set the day a release lands is a floor that NO cooldown-enforcing
+  // environment can install. Measured 2026-09-10: of every 2.x release, only
+  // 2.0.2 was over seven days old, and it predates `getBenefit` — which is why
+  // a Sites publish against this pin is blocked outright with no same-day fix
+  // available on our side, and why lowering the pin would not have helped.
+  // The failure is invisible here: `pnpm install` in this repo is happy, and
+  // the refusal only appears in someone else's environment, at publish time.
+  //
+  // So the ordering is: ship the SDK, wait out the week, THEN adopt its API in
+  // `templates/` and raise this floor in the same change. A feature is not
+  // late for waiting seven days; a template nobody can publish is worse.
   brainerce: "^2.7.0",
   "isomorphic-dompurify": "^3.8.0"
 });
@@ -401,6 +421,106 @@ function detectInvokingPackageManager() {
   return "npm";
 }
 
+// ../cli-shared/src/seed-products.ts
+var SEED_MIN_PRODUCTS = 1;
+var SEED_MAX_PRODUCTS = 20;
+var SEED_MAX_NAME = 191;
+var SEED_MAX_DESCRIPTION = 5e3;
+var SEED_FIELDS = ["name", "basePrice", "description"];
+function parseSeedProducts(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return {
+      error: "--seed-products was passed with no value. Give it a JSON array of products, quoted as one shell argument, or drop the flag entirely to connect without seeding."
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      error: `--seed-products is not valid JSON (${error instanceof Error ? error.message : String(error)}). Pass the array as a single quoted argument, or put it in BRAINERCE_SEED_PRODUCTS if your shell keeps breaking the quoting.`
+    };
+  }
+  const list = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.products) ? parsed.products : null;
+  if (!list) {
+    return {
+      error: '--seed-products must be a JSON array of products, or an object with a "products" array. A single product object on its own is not accepted; wrap it in an array.'
+    };
+  }
+  if (list.length < SEED_MIN_PRODUCTS) {
+    return {
+      error: "--seed-products was an empty list. Seeding needs at least one product; if the user has not described what they sell, leave the flag off and build against the empty catalog."
+    };
+  }
+  if (list.length > SEED_MAX_PRODUCTS) {
+    return {
+      error: `--seed-products carries ${list.length} products and the limit is ${SEED_MAX_PRODUCTS}. This is a starter catalog, not an import: pick the ${SEED_MAX_PRODUCTS} that best show the store, and point the merchant at the dashboard or Apps > Browse > Migration Tool for the rest.`
+    };
+  }
+  const products = [];
+  for (let i = 0; i < list.length; i += 1) {
+    const entry = list[i];
+    const at = `--seed-products product ${i + 1}`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return {
+        error: `${at} is not an object. Each entry looks like {"name":"...","basePrice":0}.`
+      };
+    }
+    const unknown = Object.keys(entry).filter(
+      (k) => !SEED_FIELDS.includes(k)
+    );
+    if (unknown.length > 0) {
+      return {
+        error: `${at} carries ${unknown.map((k) => `"${k}"`).join(", ")}, which the seed route does not accept and will not ignore \u2014 one unknown key rejects the whole request. Only ${SEED_FIELDS.join(
+          ", "
+        )} are allowed: no sku, no type, no options or variants, no categories, no images. Every seeded product lands as a simple, active product.`
+      };
+    }
+    if (typeof entry.name !== "string" || entry.name.trim() === "") {
+      return { error: `${at} has no usable "name". It must be a non-empty string.` };
+    }
+    if (entry.name.length > SEED_MAX_NAME) {
+      return {
+        error: `${at} ("${entry.name.slice(0, 40)}...") has a name of ${entry.name.length} characters and the limit is ${SEED_MAX_NAME}.`
+      };
+    }
+    if (!("basePrice" in entry)) {
+      return {
+        error: `${at} ("${entry.name}") has no "basePrice". Every seeded product needs one, as a number: {"name":"${entry.name}","basePrice":0} is the minimum shape.`
+      };
+    }
+    if (typeof entry.basePrice === "string") {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" quoted as text. Send ${entry.basePrice.trim() === "" ? "149" : entry.basePrice} without the quotes \u2014 the API does not coerce a quoted price, it rejects it.`
+      };
+    }
+    if (typeof entry.basePrice !== "number" || !Number.isFinite(entry.basePrice)) {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" that is not a number. It must be a plain finite number, not null, not a string and not an expression.`
+      };
+    }
+    if (entry.basePrice < 0) {
+      return { error: `${at} ("${entry.name}") has a negative "basePrice".` };
+    }
+    if ("description" in entry) {
+      if (typeof entry.description !== "string") {
+        return {
+          error: `${at} ("${entry.name}") has a "description" that is not a string. Omit the key entirely rather than sending null.`
+        };
+      }
+      if (entry.description.length > SEED_MAX_DESCRIPTION) {
+        return {
+          error: `${at} ("${entry.name}") has a description of ${entry.description.length} characters and the limit is ${SEED_MAX_DESCRIPTION}.`
+        };
+      }
+    }
+    const product = { name: entry.name, basePrice: entry.basePrice };
+    if (typeof entry.description === "string") product.description = entry.description;
+    products.push(product);
+  }
+  return { products };
+}
+
 // src/cli.ts
 async function runInteractive(defaults) {
   const questions = [];
@@ -914,6 +1034,174 @@ var logger = {
   }
 };
 
+// src/device-flow.ts
+var import_node_child_process = require("child_process");
+function isOpenableUrl(value, apiBaseUrl) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  const apiHost = (() => {
+    try {
+      return new URL(apiBaseUrl).hostname;
+    } catch {
+      return "";
+    }
+  })();
+  const base = apiHost.replace(/^api(-staging)?\./, "");
+  return url.hostname === base || url.hostname.endsWith(`.${base}`);
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const [cmd, args] = platform === "win32" ? ["cmd", ["/c", "start", "", url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    const child = (0, import_node_child_process.spawn)(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readError(res) {
+  try {
+    const body = await res.json();
+    const message = body?.message;
+    return Array.isArray(message) ? message.join("; ") : message ?? `HTTP ${res.status}`;
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+}
+async function runSeed(apiBaseUrl, deviceCode, products) {
+  let res;
+  try {
+    res = await fetch(`${apiBaseUrl}/api/device-auth/seed`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ deviceCode, products })
+    });
+  } catch (error) {
+    logger.error(
+      `  Could not reach the seeding endpoint (${error instanceof Error ? error.message : String(error)}).
+  The request may or may not have landed, so do not claim either way: check the
+  catalog in the dashboard and add what is missing there.`
+    );
+    return;
+  }
+  if (!res.ok) {
+    const message = await readError(res);
+    if (message.startsWith("That seeding window has closed")) {
+      logger.error(
+        "  The seeding window is closed \u2014 the grant was already spent, or more than ten\n  minutes passed since the approval. The connection itself is fine; add the\n  products in the dashboard."
+      );
+    } else {
+      logger.error(
+        `  The seed request was refused before the grant was touched: ${message}
+  The store is connected and still empty. Report this message as written and
+  add the products in the dashboard rather than retrying.`
+      );
+    }
+    return;
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    logger.error(
+      "  The seed endpoint answered with something that is not JSON. Products may have\n  been created. Check the catalog in the dashboard rather than assuming either way."
+    );
+    return;
+  }
+  const created = Array.isArray(body.created) ? body.created : [];
+  const failed = Array.isArray(body.failed) ? body.failed : [];
+  if (created.length > 0) {
+    logger.success(
+      `  Seeded ${created.length} product(s): ${created.map((p) => p.name).join(", ")}`
+    );
+  }
+  for (const f of failed) {
+    logger.info(`  Not created: ${f.name} \u2014 ${f.reason}`);
+  }
+  if (failed.length > 0) {
+    logger.info(
+      `  ${created.length} of ${products.length} product(s) went in; ${failed.length} refused.`
+    );
+    logger.info("  The window is now spent, so add the refused ones in the dashboard.");
+  }
+}
+async function runDeviceFlow(apiBaseUrl, options = {}) {
+  let start;
+  try {
+    const res = await fetch(`${apiBaseUrl}/api/device-auth/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        clientName: options.clientName || process.env.BRAINERCE_CLIENT_NAME || "create-brainerce-store"
+      })
+    });
+    if (!res.ok) {
+      logger.error(
+        `Could not start the browser approval (HTTP ${res.status}).
+  Create a sales channel in the dashboard instead, then re-run with --connection-id vc_xxx.`
+      );
+      return null;
+    }
+    start = await res.json();
+  } catch (error) {
+    logger.error(
+      `Could not reach Brainerce to start the approval: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+  const opened = isOpenableUrl(start.verificationUriComplete, apiBaseUrl) && openBrowser(start.verificationUriComplete);
+  console.log();
+  logger.info(
+    opened ? "  Opened your browser to approve this connection." : "  Open this link to approve this connection:"
+  );
+  console.log(`  ${start.verificationUriComplete}`);
+  console.log(`  The page should show the code ${start.userCode} \u2014 check that it matches.`);
+  console.log();
+  logger.info("  Waiting for approval. A store and a sales channel are created if you have none.");
+  const deadline = Date.now() + start.expiresIn * 1e3;
+  let interval = (start.interval || 5) * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, interval));
+    let result;
+    try {
+      const res = await fetch(`${apiBaseUrl}/api/device-auth/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ deviceCode: start.deviceCode })
+      });
+      result = await res.json();
+    } catch {
+      continue;
+    }
+    if (result.status === "approved" && result.connectionId) {
+      logger.success("  Approved.");
+      if (options.seedProducts?.length) {
+        await runSeed(apiBaseUrl, start.deviceCode, options.seedProducts);
+      }
+      return { connectionId: result.connectionId, storeId: result.storeId ?? null };
+    }
+    if (result.status === "denied") {
+      logger.error("  The connection request was declined. Nothing was created.");
+      return null;
+    }
+    if (result.status === "expired") {
+      logger.error("  The code expired before it was approved. Run the command again.");
+      return null;
+    }
+    if (result.status === "slow_down") interval += 1e3;
+  }
+  logger.error("  Timed out waiting for approval. Run the command again for a fresh code.");
+  return null;
+}
+
 // src/utils/spinner.ts
 var import_ora = __toESM(require("ora"));
 function createSpinner(text) {
@@ -959,6 +1247,7 @@ async function checkForUpdate(name, current) {
     return null;
   }
 }
+var DEFERRED_CONNECTION_ID = "vc_REPLACE_ME_RUN_npm_run_connect";
 async function resolveStoreInfoOrExit(connectionId, candidateApiUrls) {
   const spinner = createSpinner("Fetching store info...");
   spinner.start();
@@ -989,6 +1278,12 @@ async function resolveStoreInfoOrExit(connectionId, candidateApiUrls) {
 }
 var program = new import_commander.Command();
 program.name("create-brainerce-store").description("Scaffold a production-ready e-commerce storefront connected to Brainerce").version(pkg.version).argument("[project-name]", "Name for the project directory").option("--connection-id <id>", "Brainerce vibe-coded connection ID (vc_*)").option(
+  "--defer-connection",
+  "Scaffold now and connect later. Skips the browser approval and writes a placeholder id; finish with `npm run connect` inside the project."
+).option(
+  "--seed-products <json>",
+  "Starter catalog to create during the browser approval, as a JSON array of {name, basePrice, description?}. Only valid on the run that performs the approval: with --connection-id there is no grant, and with --defer-connection the approval happens later, in `npm run connect --seed-products`."
+).option(
   "--api-url <url>",
   "Brainerce API base URL (overrides BRAINERCE_API_URL env, defaults to https://api.brainerce.com)"
 ).option("--language <lang>", "Store language (en, he)").addOption(new import_commander.Option("--framework <framework>", "Framework to use").default("nextjs").hideHelp()).addOption(new import_commander.Option("--design <design>", "Storefront design pack").hideHelp()).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
@@ -1010,6 +1305,28 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       scaffoldInPlace = true;
     }
     let connectionId = options.connectionId;
+    let seedProducts;
+    const seedRaw = options.seedProducts ?? process.env.BRAINERCE_SEED_PRODUCTS;
+    if (seedRaw !== void 0) {
+      if (connectionId) {
+        logger.error(
+          "--seed-products needs a browser approval, and --connection-id skips it: a channel\nyou already have carries no seeding grant. Scaffold without --connection-id to\napprove and seed in one step, or add the products in the dashboard."
+        );
+        process.exit(1);
+      }
+      if (options.deferConnection === true) {
+        logger.error(
+          "--seed-products does not belong on a deferred scaffold: the approval happens later,\ninside the project, and that is where the seeding grant is opened. Scaffold as\nnormal, then finish with:\n  npm run connect -- --seed-products '[...]'"
+        );
+        process.exit(1);
+      }
+      const parsed = parseSeedProducts(seedRaw);
+      if (parsed.error) {
+        logger.error(parsed.error);
+        process.exit(1);
+      }
+      seedProducts = parsed.products;
+    }
     const explicitApiUrl = (options.apiUrl || process.env.BRAINERCE_API_URL || "").replace(/\/$/, "");
     const apiUrlError = validateApiUrl(explicitApiUrl);
     if (apiUrlError) {
@@ -1058,11 +1375,28 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     let storeInfo = null;
     let resolvedApiUrl = candidateApiUrls[0];
     if (connectionId) {
-      const connError2 = validateConnectionId(connectionId);
-      if (connError2) {
-        logger.error(connError2);
+      const connError = validateConnectionId(connectionId);
+      if (connError) {
+        logger.error(connError);
+        process.exit(1);
+      }
+      const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
+      storeInfo = resolved.info;
+      resolvedApiUrl = resolved.apiBaseUrl;
+    } else if (options.deferConnection === true) {
+      connectionId = DEFERRED_CONNECTION_ID;
+      storeInfo = {
+        name: projectName || "My Store",
+        storeName: projectName || "My Store",
+        currency: "USD",
+        language: language || "en"
+      };
+    } else {
+      const approved = await runDeviceFlow(candidateApiUrls[0], { seedProducts });
+      if (!approved) {
         process.exit(1);
       }
+      connectionId = approved.connectionId;
       const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
       storeInfo = resolved.info;
       resolvedApiUrl = resolved.apiBaseUrl;
@@ -1072,6 +1406,16 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     const storeSlug = storeInfo ? slugify(storeInfo.storeName) : "";
     const projectNameSuggestion = channelSlug || storeSlug || void 0;
     language = language || storeInfo?.language;
+    if (!projectName && !process.stdin.isTTY) {
+      if (!projectNameSuggestion) {
+        logger.error(
+          "No project name given, and no terminal to ask on. Pass one: npm create brainerce-store@latest my-store"
+        );
+        process.exit(1);
+      }
+      projectName = projectNameSuggestion;
+      logger.info(`  No project name given. Using "${projectName}", from your store.`);
+    }
     if (!projectName || !connectionId || !language) {
       const answers = await runInteractive({
         projectName,
@@ -1095,12 +1439,14 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       logger.error(nameError);
       process.exit(1);
     }
-    const connError = validateConnectionId(connectionId);
-    if (connError) {
-      logger.error(connError);
-      process.exit(1);
+    if (connectionId !== DEFERRED_CONNECTION_ID) {
+      const connError = validateConnectionId(connectionId);
+      if (connError) {
+        logger.error(connError);
+        process.exit(1);
+      }
     }
-    if (!storeInfo) {
+    if (!storeInfo && connectionId !== DEFERRED_CONNECTION_ID) {
       const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
       storeInfo = resolved.info;
       resolvedApiUrl = resolved.apiBaseUrl;
@@ -1196,7 +1542,27 @@ Your store will be running at http://localhost:3000
       if (!scaffoldInPlace) {
         logger.step(`cd ${projectName}`);
       }
+      if (connectionId === DEFERRED_CONNECTION_ID) {
+        logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} connect`);
+      }
       logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} dev`);
+      if (connectionId === DEFERRED_CONNECTION_ID) {
+        logger.info(
+          `
+This store is not connected yet. \`connect\` opens one browser approval,
+writes the sales channel id into .env.local, and creates a store and a
+channel for you if you have neither.
+
+Know what this store sells? Seed the catalog in that same command \u2014 the
+approval opens a short window that needs no admin key, and it is the only
+moment it is open:
+
+  ${pkgManager}${pkgManager === "npm" ? " run" : ""} connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389}]'
+
+(PowerShell mangles that quoting: put the same JSON in BRAINERCE_SEED_PRODUCTS
+instead.) Without it the store starts empty and products come from the dashboard.`
+        );
+      }
       logger.info(`
 Your store will be running at http://localhost:3000`);
       logger.info(

package/messages/en.json

@@ -104,6 +104,8 @@
     "addToCart": "Add to Cart",
     "addingToCart": "Adding...",
     "addedToCart": "Added to Cart!",
+    "cartFull": "Your cart is full. Remove an item before adding this one.",
+    "addToCartFailed": "We could not add this to your cart. Please try again.",
     "outOfStock": "Out of Stock",
     "inStock": "In Stock",
     "unavailable": "Unavailable",
@@ -127,7 +129,7 @@
   },
   "reviews": {
     "title": "Reviews",
-    "noReviews": "No reviews yet — be the first to share your experience.",
+    "noReviews": "No reviews yet. Be the first to share your experience.",
     "verifiedPurchase": "Verified purchase",
     "loading": "Loading…",
     "signIn": "Sign in",
@@ -191,12 +193,17 @@
     "upgrade": "Upgrade",
     "upgrading": "Upgrading...",
     "dismissUpgrade": "Dismiss",
+    "upgradeOriginalNotRemoved": "We added the upgrade to your cart, but we could not remove the original item. Press Upgrade again to remove it.",
     "bundleOffers": "Bundle & Save",
     "addBundleItem": "Add & Save",
     "addingBundle": "Adding...",
     "selectOptions": "Select options",
     "outOfStock": "Out of stock",
-    "unavailableItemsHint": "Remove the items marked out of stock or unavailable to continue to checkout."
+    "unavailableItemsHint": "Remove the items marked out of stock or unavailable to continue to checkout.",
+    "notEnoughStock": "There is not enough stock left for that quantity.",
+    "itemUnavailable": "This item can no longer be bought. Remove it to continue.",
+    "quantityUpdateFailed": "We could not update the quantity. Please try again.",
+    "removeFailed": "We could not remove this item. Please try again."
   },
   "checkout": {
     "pageTitle": "Checkout",
@@ -282,7 +289,7 @@
     "customFieldsApplying": "Updating…",
     "customFieldsFailed": "Failed to save selections",
     "customFieldsRequired": "Required",
-    "customFieldsSelectPlaceholder": "— Select —",
+    "customFieldsSelectPlaceholder": "Select an option",
     "customFieldsImageUpload": "Click to upload an image",
     "customFieldsImageRemove": "Remove",
     "customFieldsImageUploading": "Uploading...",
@@ -315,7 +322,7 @@
     "address": "Address",
     "streetAddress": "Street address",
     "searchingAddress": "Searching…",
-    "outsideDeliveryZone": "This address is outside our regular delivery zones. You can still continue — we'll confirm delivery by phone.",
+    "outsideDeliveryZone": "This address is outside our regular delivery zones. You can still continue, and we'll confirm delivery by phone.",
     "apartmentSuite": "Apartment, suite, etc.",
     "aptPlaceholder": "Apt, suite, unit, etc. (optional)",
     "city": "City",
@@ -567,7 +574,7 @@
     "placeholder": "your@email.com",
     "submit": "Subscribe",
     "submitting": "Sending...",
-    "checkEmailTitle": "Almost there — check your email",
+    "checkEmailTitle": "Almost there. Check your email",
     "checkEmailBody": "We've sent you a link to confirm. Look in your spam folder too; you won't get another copy for 24 hours.",
     "offerPercent": "{value}% off your first order",
     "offerAmount": "{value} off your first order",
@@ -611,6 +618,6 @@
     "locked": "Payment has already started, so this order can no longer take a gift card.",
     "lockedHint": "A gift card is added before the payment step.",
     "removeFailed": "We could not remove that gift card.",
-    "applied": "Gift card applied — {amount}"
+    "applied": "Gift card applied for {amount}"
   }
 }

package/messages/he.json

@@ -104,6 +104,8 @@
     "addToCart": "הוסף לעגלה",
     "addingToCart": "מוסיף...",
     "addedToCart": "נוסף לעגלה!",
+    "cartFull": "העגלה מלאה. הסירו מוצר אחד לפני הוספת המוצר הזה.",
+    "addToCartFailed": "לא הצלחנו להוסיף את המוצר לעגלה. נסו שוב.",
     "outOfStock": "אזל מהמלאי",
     "inStock": "במלאי",
     "unavailable": "לא זמין",
@@ -127,7 +129,7 @@
   },
   "reviews": {
     "title": "ביקורות",
-    "noReviews": "אין עדיין ביקורות — היו הראשונים לשתף.",
+    "noReviews": "אין עדיין ביקורות. היו הראשונים לשתף.",
     "verifiedPurchase": "רכישה מאומתת",
     "loading": "טוען…",
     "signIn": "התחברו",
@@ -191,12 +193,17 @@
     "upgrade": "שדרג",
     "upgrading": "משדרג...",
     "dismissUpgrade": "סגור",
+    "upgradeOriginalNotRemoved": "הוספנו את השדרוג לעגלה, אבל לא הצלחנו להסיר את המוצר המקורי. לחצו שוב על שדרוג כדי להסיר אותו.",
     "bundleOffers": "חבילה וחיסכון",
     "addBundleItem": "הוסף וחסוך",
     "addingBundle": "מוסיף...",
     "selectOptions": "בחר אפשרויות",
     "outOfStock": "אזל מהמלאי",
-    "unavailableItemsHint": "הסירו את המוצרים שמסומנים כאזלו מהמלאי או כלא זמינים כדי להמשיך לתשלום."
+    "unavailableItemsHint": "הסירו את המוצרים שמסומנים כאזלו מהמלאי או כלא זמינים כדי להמשיך לתשלום.",
+    "notEnoughStock": "אין מספיק מלאי לכמות הזו.",
+    "itemUnavailable": "לא ניתן לרכוש את המוצר הזה יותר. הסירו אותו כדי להמשיך.",
+    "quantityUpdateFailed": "לא הצלחנו לעדכן את הכמות. נסו שוב.",
+    "removeFailed": "לא הצלחנו להסיר את המוצר. נסו שוב."
   },
   "checkout": {
     "pageTitle": "תשלום",
@@ -282,7 +289,7 @@
     "customFieldsApplying": "מעדכן…",
     "customFieldsFailed": "שגיאה בשמירת הבחירות",
     "customFieldsRequired": "חובה",
-    "customFieldsSelectPlaceholder": "— בחר —",
+    "customFieldsSelectPlaceholder": "בחר אפשרות",
     "customFieldsImageUpload": "לחץ להעלאת תמונה",
     "customFieldsImageRemove": "הסר",
     "customFieldsImageUploading": "...מעלה",
@@ -315,7 +322,7 @@
     "address": "כתובת",
     "streetAddress": "רחוב ומספר",
     "searchingAddress": "מחפש…",
-    "outsideDeliveryZone": "הכתובת הזו מחוץ לאזורי המשלוח הרגילים שלנו. ניתן להמשיך — ניצור איתך קשר טלפוני לתיאום המשלוח.",
+    "outsideDeliveryZone": "הכתובת הזו מחוץ לאזורי המשלוח הרגילים שלנו. ניתן להמשיך, וניצור איתך קשר טלפוני לתיאום המשלוח.",
     "apartmentSuite": "דירה, קומה וכו׳",
     "aptPlaceholder": "דירה, קומה, כניסה (אופציונלי)",
     "city": "עיר",
@@ -567,7 +574,7 @@
     "placeholder": "your@email.com",
     "submit": "הרשמה",
     "submitting": "שולח...",
-    "checkEmailTitle": "כמעט סיימנו — בדקו את המייל",
+    "checkEmailTitle": "כמעט סיימנו. בדקו את המייל",
     "checkEmailBody": "שלחנו לכם קישור לאישור. בדקו גם בתיקיית הספאם; עותק נוסף לא יישלח ב-24 השעות הקרובות.",
     "offerPercent": "{value}% הנחה על ההזמנה הראשונה",
     "offerAmount": "{value} הנחה על ההזמנה הראשונה",
@@ -611,6 +618,6 @@
     "locked": "התשלום כבר התחיל, אז אי אפשר להוסיף כרטיס מתנה להזמנה הזאת.",
     "lockedHint": "כרטיס מתנה מוסיפים לפני שלב התשלום.",
     "removeFailed": "לא הצלחנו להסיר את כרטיס המתנה.",
-    "applied": "כרטיס מתנה — {amount}"
+    "applied": "כרטיס מתנה בסך {amount}"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.80.0",
+  "version": "1.82.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "homepage": "https://brainerce.com",
   "repository": {

package/templates/nextjs/base/.eslintrc.json

@@ -17,6 +17,8 @@
                   "!@/core/lib/capabilities",
                   "!@/core/lib/display-price",
                   "!@/core/lib/image-hosts",
+                  "!@/core/lib/kit",
+                  "!@/core/lib/add-to-cart-error",
                   "!@/core/lib/navigation",
                   "!@/core/lib/product-options",
                   "!@/core/lib/sanitize",

package/templates/nextjs/base/AI-GUIDE.md

@@ -59,8 +59,38 @@ UI components get *everything* from `@/core/hooks/*` and
 - `useHomeData()` → `{ products, banners, loading }`
 - `useProductListing()` → products + filters/sort/facets/pagination + handlers
 - `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
-  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, customization
-  + modifier state and errors
+  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
+  customization + modifier state and errors
+  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
+    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
+    distinct products and the 51st add is refused, so a design that drops this
+    leaves the shopper tapping a button that resets and adds nothing. Copy lives
+    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
+  - Five more components hold the same message in their OWN local state, because
+    they add to the cart without this hook: `ui/product/product-card.tsx`,
+    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
+    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
+    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
+    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
+    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
+    calls only, so dropping one of these leaves a green build and a silent button.
+  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
+    in its own `lineError` state: a failed quantity change or a failed Remove
+    used to log to the console and leave the row looking untouched. It uses
+    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
+    cap cannot refuse a quantity change, and "we could not add this" would be a
+    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
+    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
+    The first two are for refusals a retry can never clear, so do not collapse
+    them into the generic one. Nothing checks that you kept any of this either.
+  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
+    another, and the ORDER of its two SDK calls is a correctness property, not a
+    style choice: it **adds the upgrade first and removes the original second**,
+    so a failed add leaves the cart untouched instead of losing the shopper's
+    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
+    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
+    where the add landed and the removal did not. If you rebuild that component,
+    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
 - `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`
 
 Hooks return data and handlers, never JSX. All catalog content (names, prices,