@blamejs/blamejs-shop 0.1.31 → 0.1.32

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.32 (2026-05-26) — **Bundles and quantity discounts — sell products together at a set price, and reward buying more.** Two merchandising surfaces go live on the product page and in the cart, both priced authoritatively on the server. A product that belongs to a bundle shows a "Bundle & save" offer with its member products and the bundle price against the sum of the parts; one action adds the whole bundle to the cart at that price, all-or-nothing, and the discount is split across the member lines so the cart subtotal equals the quoted bundle price. Separately, a product with quantity breaks shows its price tiers ("1–2 / 3–5 / 6+") on the page, and the cart applies the right unit price for each line's quantity — recomputed on every cart render and again at checkout, so the line, cart, and order totals all reflect the break. The client never sends a price: it sends a bundle code or a quantity, and the server prices both from the live catalog. A bundle whose member is archived or out of stock is shown unavailable rather than adding a broken line, and a missing offer simply renders nothing. **Added:** *Bundles on the product page* — A product that is part of one or more bundles shows a "Bundle & save" offer listing the bundle's member products, the bundle price, and the saving against buying the parts separately. `POST /cart/bundle` adds the whole bundle to the cart in one action: the bundle price is recomputed from the live catalog and allocated across the member lines (proportional to each member's list price, with the rounding remainder on the last line) so the cart subtotal equals the quoted price. The add is atomic — if any member is archived or out of stock the bundle is shown unavailable and the action adds nothing rather than a partial set. A product in no bundle shows no offer; an unpriceable bundle (a missing member price or a currency mismatch) is shown unavailable, never a server error. The offer renders identically from the edge worker and the container. · *Quantity discounts on the product page and in the cart* — A product with quantity breaks shows its price tiers on the page (for example 1–2, 3–5, 6+ at descending unit prices). In the cart, each line is priced at the unit price for its quantity — applied server-side on every cart render so changing the quantity re-prices the line, and applied again at checkout so the per-line price and the order total written onto the order reflect the break, not the list price. A quantity below the first tier falls back to the base price; a quantity above the top tier takes the top tier. Stacks with the rest of the cart math. The tier table renders identically from the edge worker and the container. **Fixed:** *Themed product template carries the compare control* — The file-backed default product template now includes the Add-to-compare slot, matching the built-in render path so the comparison control appears on the product page whichever template is in use.
+
 - v0.1.31 (2026-05-26) — **Product compare — a side-by-side comparison table any shopper can build from the product pages.** Shoppers can now line products up against each other. Every product page gains an "Add to compare" control; a "Compare" link in the footer opens a side-by-side table of the chosen products — image, price, availability, and each product's attributes in aligned rows. No sign-in is required: the comparison basket rides the visitor's existing sealed session cookie, and a signed-in shopper's customer id is carried alongside. The basket holds up to four products (a fifth add is refused with a notice rather than quietly dropping one), the toggle is idempotent, and a product that goes archived or out of stock resolves out of the table with a remove control instead of breaking the page. The control and table render identically from the edge and the container, and the comparison page reuses the catalog grid styling, so no new stylesheet ships. **Added:** *Add to compare on the product page* — Each product page shows an "Add to compare" / "Remove from compare" control reflecting whether the product is already in the basket. `POST /compare/toggle` adds or removes it and redirects back to where the shopper was (the redirect target is validated, so a crafted `return_to` can't bounce the visitor off-site). Comparing needs no account — the basket is keyed on the visitor's existing sealed session cookie; a signed-in shopper's customer id is captured alongside. The basket is capped at four products: a fifth add is refused with a notice and the basket is left unchanged. · *The comparison table* — `GET /compare` renders the selected products side by side — image, title, price, availability, and the per-product attributes resolved through the catalog, in aligned rows. Each column has a remove control, and `POST /compare/clear` empties the whole basket. A product that has since been archived or sold out shows in a gone/out-of-stock state with a remove control rather than failing the render. An empty basket shows a friendly empty state and mints no cookie. A "Compare" link sits in the footer on every page.
 
 - v0.1.30 (2026-05-26) — **Product Q&A — customer questions and seller answers on the product page.** Products gain a question-and-answer thread alongside reviews. A signed-in shopper asks a question from the product page; it lands pending and surfaces only after an operator approves it. Operators moderate at `/admin/questions`: a status-filtered queue of every question across the catalog, and a per-question detail page where they approve or reject the question, post the authoritative seller answer, approve / reject individual answers, and pin one answer as the definitive 'top answer'. Approved questions and their approved answers render on the product page in both the edge and container render paths, reusing the reviews section's styling so no new CSS ships. As with reviews, a missing Q&A table degrades the product page to an empty Q&A state rather than failing the render. **Added:** *Ask a question on the product page* — `GET /products/:slug/question` renders an auth-gated question form; `POST /products/:slug/question` submits it. Asking requires a signed-in customer — a logged-out shopper is redirected to sign in. The question is stored pending and is not shown on the product page until an operator approves it. A malformed submission re-renders the form with the reason and a 400; an unknown product is a 404. · *Published Q&A on the product page* — The product page shows approved questions with their approved answers below the reviews section. Each answer carries a source badge — 'Answered by the seller', 'Customer answer', or 'Automated answer' — and the operator-pinned answer is flagged 'Top answer'. The empty state invites the first question. Rendered identically by the edge worker and the container so the page is the same whichever serves it; the read degrades to the empty state when the Q&A tables aren't present. · *Q&A moderation console* — `/admin/questions` is the question queue across all products, with pending / approved / rejected status-filter chips. Each question opens a detail page showing its full answer thread (every status), an approve / reject control for the question, a form to post the seller's answer, and per-answer approve / reject / pin controls. Posting an answer leaves it pending; approving it publishes it on the product page. Pinning floats one operator answer to the top of the thread. Every path content-negotiates: a bearer-token client gets a JSON contract, a signed-in browser gets the HTML console. An unknown id or a refused transition redirects back with a notice, never a 500. · *productQA read APIs for the storefront and console* — `answersForQuestion` returns the approved answers under a question (pinned first) for the product-page thread; `listAnswersForQuestion` returns every answer regardless of status for the moderation detail; `listQuestionsByStatus` and `listAnswersByStatus` return the cross-product moderation queues. **Changed:** *Console nav gains Q&A; product page wires the Q&A primitive* — The signed-in admin nav includes Q&A, shown only when the Q&A primitive is wired so the link never points at an unmounted route. The storefront and admin share one Q&A instance, wired with the customer primitive so an authenticated questioner's id is verified before the row is stored.

package/README.md

@@ -72,6 +72,8 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/loyalty.js`** + **`lib/loyalty-earn-rules.js`** + **`lib/loyalty-redemption.js`** | Customer rewards. `loyalty` owns the points balance, lifetime total, tier (bronze → platinum on operator-tunable thresholds), and an audited transaction ledger. `loyalty-earn-rules` defines how points are minted (per-dollar-spent, per-order, signup, birthday, …) keyed to lifecycle events; `loyalty-redemption` is the reward catalog customers spend points against. Customers see all of it at `/account/loyalty` — balance + tier, the earn rules in plain language, the reward catalog with a one-click Redeem, past redemptions, and the paginated earn/redeem ledger (login-gated). Paid orders award points automatically: the order FSM's paid transition fans out to the earn rules fire-and-forget, deduped on the order id so a re-delivered payment webhook never double-credits. At checkout a signed-in customer can spend points for a credit against the order total — valued by the redemption ratio (100 points = $1 default), capped at the order's worth and the balance, debited once behind a balance-guarded SQL decrement, stacking with any gift-card credit; surplus points stay in the balance. |
 | **`lib/referrals.js`** + **`lib/referral-leaderboard.js`** | Refer-a-friend with two-sided rewards. `referrals` issues each customer an 8-character code (32-glyph confusion-resistant alphabet via `b.crypto.generateBytes`) and tracks each referred friend through the funnel (invited → visited → joined → converted); referred emails are stored hash-only (`b.crypto.namespaceHash`), never plaintext. `referral-leaderboard` sits on top for top-referrer rankings + operator-tunable tier bonuses. Customers see all of it at `/account/referrals` — their code, an absolute shareable link, the friends they've referred (funnel stage + dates, no personal data), and an in-account leaderboard (rank + initials only). A public `/r/<code>` landing captures an inbound referral into a short-lived sealed first-party cookie (first-touch), which attributes the new customer to the referrer when they sign up by passkey / Google / Apple — self-referral and double-attribution guarded. When a referred customer's first order reaches paid, the order FSM's paid transition marks that referral converted and bumps the referrer's count fire-and-forget, deduped on the order id so a re-delivered webhook never double-counts; guest orders and a customer's later orders don't qualify. Issuing the payout itself (gift card / store credit / loyalty points) is an explicit operator action via the referrals reward API, so the reward instrument and any fraud review stay the operator's. |
 | **`lib/product-compare.js`** | Side-by-side product comparison, no sign-in required. Each product page gets an "Add to compare" / "Remove from compare" control; `POST /compare/toggle` adds or removes the product and `GET /compare` renders the comparison table — image, price, availability, and the per-product attributes resolved through the catalog. The basket is keyed on the visitor's existing sealed session cookie (a signed-in shopper's customer id rides alongside), capped at four products (a fifth add is refused with a notice rather than silently dropping one), and is idempotent. Products that go archived or out of stock resolve out of the table with a remove control instead of breaking the render; an empty basket shows a friendly empty state. `POST /compare/clear` empties it. Linked from the footer on every page. |
+| **`lib/bundles.js`** | Sell products together at a set price. A product page shows the bundles it belongs to as a "Bundle & save" offer — the member products, the bundle price, and the saving against the parts. `POST /cart/bundle` adds the whole bundle in one action: the price is recomputed from the live catalog and allocated across the member lines (proportional to list price, remainder on the last line) so the cart subtotal matches the quoted price. The add is atomic — an archived or out-of-stock member shows the bundle unavailable and adds nothing rather than a partial set; an unpriceable bundle (missing member price / currency mismatch) is shown unavailable, never a 500. The client sends only the bundle code; the server prices it. The offer renders identically from the edge worker and the container. |
+| **`lib/quantity-discounts.js`** | Reward buying more. A product with quantity breaks shows its price tiers on the page (e.g. 1–2 / 3–5 / 6+ at descending unit prices). In the cart, each line is priced at the unit price for its quantity — reapplied on every cart render so changing the quantity re-prices, and again at checkout so the per-line price and order total written onto the order reflect the break, not the list price. A quantity under the first tier falls back to the base price; over the top tier takes the top tier. The client sends only a quantity; the server prices it. The tier table renders identically from the edge worker and the container. |
 | **`lib/recently-viewed.js`** | Signed-in customer browse history. A product-page visit records the view server-side against the customer's account (drop-silent — never blocks the page); `/account/recently-viewed` lists them newest-first as a grid with a Clear-history control. De-duped + capped per customer, archived products drop out, login-gated. Guest/session history is opt-in (a client beacon) and not shipped — the lib's `forSession` + `merge` support it. |
 | **`lib/recommendations.js`** | Product-recommendation engine. Operator-curated override pins first (`setOverride` — "when viewing A, show B", kind-scoped + weight-ordered), then a signal-based fallback: co-purchase (products bought in the same orders), category-popular, and in-stock-random filler. `recommendForProduct` / `recommendForCart` / `recommendForCustomer` / `recommendForCategory` each return renderable picks (active + in-stock, source product excluded). The order confirmation page (`/orders/:id`) renders a "Customers also bought" rail from it — best-effort, anchored on the order's items, excluding what was just bought. |
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |

package/lib/asset-manifest.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.1.31",
+  "version": "0.1.32",
   "assets": {
     "css/admin.css": "sha384-rvjL1QySBgNJGEUDusbbMCkL3fsjmzcwUvTp9pljo/0Nn/lErxq2AbY8EYvDF9Ch",
-    "css/main.css": "sha384-qBY97FWZDGOploZRppwrDi0A/+R4R3iCFtyS1dfrAlqHNEPluPmY0R3HB9cJntyV",
+    "css/main.css": "sha384-A2m9cYLHIlIrFvTluTOaZz9r8F90yWIKd3SHOlyNwQwtaOBrzlsn/NDR1vso6dSF",
     "js/passkey-login.js": "sha384-65i1wVHIkiS2e0YiOV6oUOF9+tNR7s6QRvpnWaEne43P+B8UvKLTpDgp4MSKNGqX",
     "js/passkey-register.js": "sha384-RaSkJbTpc6ClfPy5QyaY96doIqBqa9CLeIB1CzWnL05pSSJEA9IrIK0S7V7igRxY"
   }

package/lib/bundles.js

@@ -333,6 +333,33 @@ function create(opts) {
     return { rows: r.rows, next_cursor: next };
   }
 
+  // ---- bundlesForComponent ----------------------------------------------
+
+  // Every bundle that lists `sku` as a direct component, newest-edited
+  // first. Backs the storefront "Bundle & save" rail — a product page
+  // shows the bundles its variant SKUs belong to. Returns the same
+  // shape as getBundle (definition + ordered components) so the caller
+  // can price + render each without a second round trip per bundle.
+  // Only direct membership is resolved; a bundle that contains `sku`
+  // transitively (via a nested child bundle) is reachable by walking
+  // its own bundlesForComponent, which the storefront doesn't surface
+  // on a leaf PDP.
+  async function bundlesForComponent(sku) {
+    _sku(sku, "sku");
+    var r = await query(
+      "SELECT DISTINCT bc.bundle_sku FROM bundle_components bc " +
+      "JOIN bundles b ON b.bundle_sku = bc.bundle_sku " +
+      "WHERE bc.sku = ?1 ORDER BY b.updated_at DESC, b.bundle_sku DESC",
+      [sku],
+    );
+    var out = [];
+    for (var i = 0; i < r.rows.length; i += 1) {
+      var full = await getBundle(r.rows[i].bundle_sku);
+      if (full) out.push(full);
+    }
+    return out;
+  }
+
   // ---- expand ------------------------------------------------------------
 
   // Flatten a bundle into its leaf components with multipliers applied.
@@ -569,6 +596,7 @@ function create(opts) {
     defineBundle: defineBundle,
     getBundle:    getBundle,
     listBundles:  listBundles,
+    bundlesForComponent: bundlesForComponent,
     expand:       expand,
     priceBundle:  priceBundle,
     updateBundle: updateBundle,

package/lib/checkout.js

@@ -121,6 +121,47 @@ function create(deps) {
   // checkout never re-derives the conversion constant. Disabled when
   // the handle is absent — the rest of the flow is unchanged.
   var loyalty       = deps.loyalty || null;
+  // Optional quantity-discount engine. When wired, each cart line is
+  // repriced at confirm/quote time by reapplying the active per-line
+  // quantity break at the line's current quantity, so the order total
+  // (and the per-line price written onto the order) reflects the break
+  // — never the bare add-time snapshot. Disabled when absent: lines
+  // pass through at their snapshot price. The repricing is the same
+  // server-authoritative computation the cart page renders, so the
+  // "review your order" subtotal and the charged amount agree.
+  var quantityDiscounts = deps.quantityDiscounts || null;
+
+  // Reprice a list of cart lines through the quantity-discount engine.
+  // Returns a shallow copy with `unit_amount_minor` overwritten by the
+  // discounted unit for each line's SKU at its quantity. A line whose
+  // SKU has no active tier (or any apply failure) keeps its snapshot.
+  // No-op pass-through when the engine isn't wired.
+  async function _repriceLines(c, lines) {
+    if (!quantityDiscounts) return lines;
+    var out = [];
+    for (var i = 0; i < lines.length; i += 1) {
+      var l = lines[i];
+      var unit = l.unit_amount_minor;
+      try {
+        var v = await catalog.variants.get(l.variant_id);
+        var applied = await quantityDiscounts.applyToLine({
+          line: {
+            sku:              l.sku,
+            quantity:         l.qty,
+            unit_price_minor: l.unit_amount_minor,
+            product_id:       v ? v.product_id : undefined,
+          },
+        });
+        unit = applied.discounted_unit_minor;
+      } catch (_e) {
+        // Unpriceable line keeps its snapshot — the quantity-break is
+        // an adjustment, never a hard gate on the buy path.
+        unit = l.unit_amount_minor;
+      }
+      out.push(Object.assign({}, l, { unit_amount_minor: unit }));
+    }
+    return out;
+  }
 
   // Validate a gift-card code against a priced quote: the card exists,
   // is active, not expired, and matches the order currency. Returns
@@ -289,8 +330,13 @@ function create(deps) {
     var c = await cart.get(input.cart_id);
     if (!c)                       throw new TypeError("checkout: cart " + input.cart_id + " not found");
     if (c.status !== "active")    throw new TypeError("checkout: cart status is " + c.status + ", cannot quote");
-    var lines = await cart.listLines(c.id);
-    if (lines.length === 0)       throw new TypeError("checkout: cart is empty");
+    var rawLines = await cart.listLines(c.id);
+    if (rawLines.length === 0)    throw new TypeError("checkout: cart is empty");
+    // Reapply the active quantity-break for each line at confirm time —
+    // the order total + the per-line price written onto the order
+    // reflect the break, not the bare add-time snapshot. Pass-through
+    // when the engine isn't wired.
+    var lines = await _repriceLines(c, rawLines);
 
     // Variants for shipping weight + requires_shipping flag.
     var enrichedLines = [];

package/lib/storefront.js

@@ -745,10 +745,12 @@ var PRODUCT_PAGE =
   "          </table>\n" +
   "        </div>\n" +
   "      </div>\n" +
+  "      RAW_QTYBREAK_PLACEHOLDER\n" +
   "      RAW_WISHLIST_PLACEHOLDER\n" +
   "      RAW_COMPARE_PLACEHOLDER\n" +
   "    </div>\n" +
   "  </div>\n" +
+  "  RAW_BUNDLES_PLACEHOLDER\n" +
   "  RAW_REVIEWS_PLACEHOLDER\n" +
   "  RAW_QA_PLACEHOLDER\n" +
   "</section>\n";
@@ -890,6 +892,109 @@ function _buildReviews(summary, reviews, ctaHtml) {
          "</section>";
 }
 
+// Builds the PDP "Bundle & save" rail from the offers the route
+// resolved. Each offer carries its component list (with display
+// titles + per-member quantity), the sum-of-parts list price, the
+// bundle price, and the saving — every figure already formatted to a
+// currency string by the route (price math stays server-side; the
+// builder is pure string assembly so the container + edge renderers
+// emit byte-identical markup). An unavailable offer (a member is
+// archived / out of stock) renders disabled with a reason instead of
+// the add form, so a customer never hits a broken atomic add. Returns
+// "" when there are no offers so the PDP shows no empty rail. Mirrors
+// the edge renderer (`worker/render/product.js#_buildBundles`).
+function _buildBundles(offers) {
+  return _renderBundles(offers, b.template.escapeHtml);
+}
+
+// Shared pure-string assembler. `esc` is the caller's HTML-escaper
+// (b.template.escapeHtml in the container, escapeHtml at the edge) —
+// both produce the same output, so the markup is identical across
+// render paths.
+function _renderBundles(offers, esc) {
+  offers = offers || [];
+  if (offers.length === 0) return "";
+  var cards = "";
+  for (var i = 0; i < offers.length; i += 1) {
+    var o = offers[i];
+    var members = "";
+    for (var j = 0; j < o.components.length; j += 1) {
+      var c = o.components[j];
+      members +=
+        "<li class=\"bundle-card__member\">" +
+          "<span class=\"bundle-card__member-qty\">" + esc(String(c.quantity)) + "&times;</span> " +
+          "<span class=\"bundle-card__member-title\">" + esc(String(c.title)) + "</span> " +
+          "<code class=\"bundle-card__member-sku\">" + esc(String(c.sku)) + "</code>" +
+        "</li>";
+    }
+    var pricing =
+      "<div class=\"bundle-card__pricing\">" +
+        "<span class=\"bundle-card__list\">Buy separately " + esc(o.list_total_str) + "</span>" +
+        "<span class=\"bundle-card__price price\">Bundle price " + esc(o.amount_str) + "</span>" +
+        (o.discount_str ? "<span class=\"bundle-card__save\">You save " + esc(o.discount_str) + "</span>" : "") +
+      "</div>";
+    var action;
+    if (o.available) {
+      action =
+        "<form method=\"post\" action=\"/cart/bundle\" class=\"bundle-card__form\">" +
+          "<input type=\"hidden\" name=\"bundle_sku\" value=\"" + esc(o.bundle_sku) + "\">" +
+          "<button type=\"submit\" class=\"btn-primary btn-primary--sm\">Add bundle to cart</button>" +
+        "</form>";
+    } else {
+      action =
+        "<p class=\"bundle-card__unavailable\">" +
+          esc(o.unavailable_reason || "This bundle is currently unavailable.") +
+        "</p>";
+    }
+    cards +=
+      "<article class=\"bundle-card" + (o.available ? "" : " bundle-card--unavailable") + "\">" +
+        "<h3 class=\"bundle-card__title\">" + esc(String(o.title)) + "</h3>" +
+        "<ul class=\"bundle-card__members\">" + members + "</ul>" +
+        pricing +
+        action +
+      "</article>";
+  }
+  return "<section class=\"bundles\" aria-labelledby=\"bundles-title\">" +
+           "<h2 id=\"bundles-title\" class=\"bundles__heading\">Bundle &amp; save</h2>" +
+           "<div class=\"bundles__grid\">" + cards + "</div>" +
+         "</section>";
+}
+
+// Builds the PDP quantity-break table for the displayed variant. Each
+// row is a (range label, unit price) pair the route already resolved +
+// formatted (the unit price comes from the quantity-discount
+// primitive's tierBreakdown against the variant's list price — the math
+// is server-side; the builder only lays out strings). Returns "" when
+// the product has no active breaks so the PDP shows no empty table.
+// Mirrors the edge renderer (`worker/render/product.js#_buildQtyBreaks`).
+function _buildQtyBreaks(breaks) {
+  return _renderQtyBreaks(breaks, b.template.escapeHtml);
+}
+
+function _renderQtyBreaks(breaks, esc) {
+  breaks = breaks || [];
+  if (breaks.length === 0) return "";
+  var rows = "";
+  for (var i = 0; i < breaks.length; i += 1) {
+    var br = breaks[i];
+    rows +=
+      "<tr>" +
+        "<td class=\"qty-break__range\">" + esc(String(br.label)) + "</td>" +
+        "<td class=\"qty-break__unit price\">" + esc(String(br.unit_str)) + "</td>" +
+      "</tr>";
+  }
+  return "<div class=\"qty-breaks\">" +
+           "<h2 class=\"qty-breaks__title\">Buy more, save more</h2>" +
+           "<div class=\"table-scroll\">" +
+             "<table class=\"qty-break-table\">" +
+               "<thead><tr><th>Quantity</th><th>Price each</th></tr></thead>" +
+               "<tbody>" + rows + "</tbody>" +
+             "</table>" +
+           "</div>" +
+           "<p class=\"qty-breaks__note\">Discount applies automatically in your cart.</p>" +
+         "</div>";
+}
+
 var REVIEW_FORM_PAGE =
   "<section class=\"review-form-page\">\n" +
   "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
@@ -2321,6 +2426,8 @@ function renderProduct(opts) {
       // include the slot; a custom theme opts in by adding it.
       reviews_html:   _buildReviews(opts.review_summary, opts.reviews, opts.review_cta),
       qa_html:        _buildProductQa(opts.qa_questions, opts.qa_cta),
+      bundles_html:   _buildBundles(opts.bundle_offers),
+      qty_breaks_html: _buildQtyBreaks(opts.qty_breaks),
       wishlist_html:  _buildWishlist(opts.product.id, opts.wishlist_count),
       compare_html:   _buildCompare(opts.product.id),
       asset_css_main: opts.theme.assetUrl("css/main.css"),
@@ -2333,6 +2440,8 @@ function renderProduct(opts) {
   var galleryHtml = _buildPdpGallery(opts.product, opts.media || [], opts.asset_prefix || "/assets/");
   var reviewsHtml = _buildReviews(opts.review_summary, opts.reviews, opts.review_cta);
   var qaHtml = _buildProductQa(opts.qa_questions, opts.qa_cta);
+  var bundlesHtml = _buildBundles(opts.bundle_offers);
+  var qtyBreaksHtml = _buildQtyBreaks(opts.qty_breaks);
   var wishlistHtml = _buildWishlist(opts.product.id, opts.wishlist_count);
   var compareHtml = _buildCompare(opts.product.id);
   var body = _render(PRODUCT_PAGE, {
@@ -2342,8 +2451,10 @@ function renderProduct(opts) {
   })
     .replace("RAW_GALLERY_PLACEHOLDER", galleryHtml)
     .replace("RAW_ROWS_PLACEHOLDER", rows)
+    .replace("RAW_QTYBREAK_PLACEHOLDER", qtyBreaksHtml)
     .replace("RAW_WISHLIST_PLACEHOLDER", wishlistHtml)
     .replace("RAW_COMPARE_PLACEHOLDER", compareHtml)
+    .replace("RAW_BUNDLES_PLACEHOLDER", bundlesHtml)
     .replace("RAW_REVIEWS_PLACEHOLDER", reviewsHtml)
     .replace("RAW_QA_PLACEHOLDER", qaHtml);
   // Product-specific OpenGraph + Twitter Card values so shares
@@ -3610,6 +3721,204 @@ function mount(router, deps) {
     return { sid: sid, cart: created };
   }
 
+  // ---- bundle + quantity-discount pricing (server-authoritative) --------
+  //
+  // Every price below is recomputed from the catalog + the bundle /
+  // quantity-discount primitives on each render. The client never
+  // sends a price; the cart line's stored snapshot is the add-time
+  // catalog price, and the quantity-break adjustment is reapplied each
+  // time the cart renders (idempotent — the same line quantity always
+  // yields the same adjusted unit), so a stale or forged client value
+  // can't survive a round trip.
+
+  // A pricing.priceFor(sku) adapter over the catalog, for
+  // bundles.priceBundle. Returns the current price row in `currency`
+  // (or null when a member SKU has no price configured, which the
+  // caller treats as "bundle unavailable"). Memoized per call site so
+  // a bundle that repeats a SKU only hits the catalog once.
+  function _skuPricer(currency) {
+    var cache = Object.create(null);
+    return {
+      priceFor: async function (sku) {
+        if (cache[sku] !== undefined) return cache[sku];
+        var variant = await deps.catalog.variants.bySku(sku);
+        if (!variant) { cache[sku] = null; return null; }
+        var price = await deps.catalog.prices.current(variant.id, currency);
+        cache[sku] = price
+          ? { amount_minor: price.amount_minor, currency: price.currency }
+          : null;
+        return cache[sku];
+      },
+    };
+  }
+
+  // Is a SKU buyable right now — a real, in-stock catalog variant?
+  // A bundle with any unbuyable member is shown as unavailable so the
+  // atomic add never half-completes. Inventory is optional: a SKU with
+  // no inventory row is treated as available (the operator hasn't opted
+  // into stock tracking for it), matching the rest of the storefront's
+  // never-block-on-missing-inventory stance.
+  async function _skuBuyable(sku) {
+    var variant = await deps.catalog.variants.bySku(sku);
+    if (!variant) return null;
+    var inv = await deps.catalog.inventory.get(sku);
+    if (inv && (inv.stock_on_hand - inv.stock_held) <= 0) return false;
+    return variant;
+  }
+
+  // Resolve the "Bundle & save" offers for a product's variant SKUs.
+  // For each bundle a SKU belongs to: price it (sum-of-parts vs bundle
+  // price via the primitive's stored discount), check every member is
+  // buyable, and shape the display offer the renderer consumes. An
+  // unpriceable or unbuyable-member bundle is surfaced as unavailable
+  // (never hidden silently — the customer sees why). Dedupes bundles
+  // reachable via multiple variant SKUs. Drop-silent on a primitive
+  // error so a bundles read failure can't 500 the PDP — the rail just
+  // doesn't render (mirrors the reviews/Q&A degrade-to-empty stance).
+  async function _resolveBundleOffers(variantSkus, currency) {
+    if (!deps.bundles) return [];
+    var seen = Object.create(null);
+    var offers = [];
+    try {
+      for (var s = 0; s < variantSkus.length; s += 1) {
+        var bundleList = await deps.bundles.bundlesForComponent(variantSkus[s]);
+        for (var i = 0; i < bundleList.length; i += 1) {
+          var bundle = bundleList[i];
+          if (seen[bundle.bundle_sku]) continue;
+          seen[bundle.bundle_sku] = true;
+
+          // Decorate each member with a display title; flag unbuyable.
+          var componentsOut = [];
+          var allBuyable = true;
+          for (var j = 0; j < bundle.components.length; j += 1) {
+            var comp = bundle.components[j];
+            var buyable = await _skuBuyable(comp.sku);
+            if (!buyable) allBuyable = false;
+            var memberVariant = buyable || (await deps.catalog.variants.bySku(comp.sku));
+            var memberTitle = comp.sku;
+            if (memberVariant) {
+              var memberProduct = await deps.catalog.products.get(memberVariant.product_id);
+              memberTitle = (memberProduct && memberProduct.title) || memberVariant.title || comp.sku;
+            }
+            componentsOut.push({ sku: comp.sku, quantity: comp.quantity, title: memberTitle });
+          }
+
+          var priced = null;
+          try {
+            priced = await deps.bundles.priceBundle({ bundle_sku: bundle.bundle_sku, pricing: _skuPricer(currency) });
+          } catch (_e) {
+            // A missing member price / mixed currency makes the bundle
+            // unpriceable — surface it as unavailable rather than 500.
+            priced = null;
+          }
+
+          var available = allBuyable && priced != null;
+          var listMinor = priced ? priced.list_total_minor : 0;
+          var amountMinor = priced ? priced.amount_minor : 0;
+          var discountMinor = priced ? priced.discount_minor : 0;
+          var cur = (priced && priced.currency) || currency;
+          offers.push({
+            bundle_sku:         bundle.bundle_sku,
+            title:              bundle.title,
+            components:         componentsOut,
+            list_total_str:     pricing.format(listMinor, cur),
+            amount_str:         pricing.format(amountMinor, cur),
+            discount_str:       discountMinor > 0 ? pricing.format(discountMinor, cur) : null,
+            available:          available,
+            unavailable_reason: available
+              ? null
+              : (priced == null
+                  ? "Pricing for this bundle isn't available right now."
+                  : "One or more items in this bundle are out of stock."),
+          });
+        }
+      }
+    } catch (_e) {
+      // Bundles table not migrated / read failure — degrade to no rail.
+      return [];
+    }
+    return offers;
+  }
+
+  // Resolve the quantity-break table rows for a variant's SKU, against
+  // its list price. Composes the quantity-discount primitive's
+  // tierBreakdown with a sample unit = the variant's current price, so
+  // the displayed "price each" matches what the cart will charge at
+  // that quantity. Rows read as ascending ranges ("1–4", "5–9",
+  // "10+"). Returns [] when no active sku-scoped tier set exists.
+  // Drop-silent on a read failure so the PDP still renders.
+  async function _resolveQtyBreaks(sku, unitMinor, currency) {
+    if (!deps.quantityDiscounts || unitMinor == null) return [];
+    var breakdown;
+    try {
+      breakdown = await deps.quantityDiscounts.tierBreakdown({
+        scope:                   "sku",
+        scope_id:                sku,
+        sample_unit_price_minor: unitMinor,
+      });
+    } catch (_e) {
+      return [];
+    }
+    var rows = breakdown.rows || [];
+    if (rows.length === 0) return [];
+    // Order by min_quantity ascending; build the implicit range each
+    // tier covers (this tier's min up to the next tier's min minus 1,
+    // open-ended on the last). The base price (below the first tier)
+    // rides as the leading "1–(min-1)" row so the table shows the full
+    // ladder including the undiscounted band.
+    var sorted = rows.slice().sort(function (a, b2) { return a.min_quantity - b2.min_quantity; });
+    var out = [];
+    if (sorted[0].min_quantity > 1) {
+      out.push({
+        label:    "1–" + (sorted[0].min_quantity - 1),
+        unit_str: pricing.format(unitMinor, currency),
+      });
+    }
+    for (var i = 0; i < sorted.length; i += 1) {
+      var t = sorted[i];
+      var next = sorted[i + 1];
+      var label = next ? (t.min_quantity + "–" + (next.min_quantity - 1)) : (t.min_quantity + "+");
+      var unit = t.sample_discounted_unit_minor != null ? t.sample_discounted_unit_minor : unitMinor;
+      out.push({ label: label, unit_str: pricing.format(unit, currency) });
+    }
+    return out;
+  }
+
+  // Reprice cart lines for display + totals by reapplying the active
+  // quantity-break for each line's SKU at its current quantity. Returns
+  // a shallow copy of each line with `unit_amount_minor` overwritten by
+  // the discounted unit (the stored snapshot is never mutated — the
+  // adjustment is recomputed every render, so it stays correct as the
+  // quantity changes and as the operator edits tier schedules). When
+  // the quantity-discount primitive isn't wired, the lines pass through
+  // unchanged. Drop-silent per line so one unpriceable SKU can't break
+  // the cart total.
+  async function _repriceCartLines(lines) {
+    if (!deps.quantityDiscounts) return lines;
+    var out = [];
+    for (var i = 0; i < lines.length; i += 1) {
+      var l = lines[i];
+      var unit = l.unit_amount_minor;
+      try {
+        var variant = await deps.catalog.variants.get(l.variant_id);
+        var applied = await deps.quantityDiscounts.applyToLine({
+          line: {
+            sku:              l.sku,
+            quantity:         l.qty,
+            unit_price_minor: l.unit_amount_minor,
+            product_id:       variant ? variant.product_id : undefined,
+          },
+        });
+        unit = applied.discounted_unit_minor;
+      } catch (_e) {
+        // Unpriceable line (no tier / bad shape) keeps its snapshot.
+        unit = l.unit_amount_minor;
+      }
+      out.push(Object.assign({}, l, { unit_amount_minor: unit }));
+    }
+    return out;
+  }
+
   router.get("/", async function (_req, res) {
     var page = await deps.catalog.products.list({ status: "active", limit: 24 });
     // Best-effort "starting price" + "hero media" lookup. Each
@@ -3768,6 +4077,19 @@ function mount(router, deps) {
         catch (_e) { /* drop-silent — recently-viewed is supplementary to the buy path */ }
       }
     }
+    // Bundle offers + quantity-break table. Both compose the
+    // server-authoritative pricing primitives (the customer never sends
+    // a price); both degrade to empty on a missing-table / read failure
+    // so the buy path renders regardless. The quantity-break table is
+    // built against the first variant's list price — the band a shopper
+    // sees on the PDP matches what the cart charges at that quantity.
+    var variantSkus = variants.map(function (v) { return v.sku; });
+    var bundleOffers = await _resolveBundleOffers(variantSkus, "USD");
+    var firstVariant = variants[0] || null;
+    var firstPrice = firstVariant ? prices[firstVariant.id] : null;
+    var qtyBreaks = firstVariant && firstPrice
+      ? await _resolveQtyBreaks(firstVariant.sku, firstPrice.amount_minor, firstPrice.currency)
+      : [];
     var html = renderProduct({
       product:        product,
       variants:       variants,
@@ -3778,6 +4100,8 @@ function mount(router, deps) {
       review_cta:     reviewCta,
       qa_questions:   qaQuestions,
       qa_cta:         qaCta,
+      bundle_offers:  bundleOffers,
+      qty_breaks:     qtyBreaks,
       wishlist_count: wishlistCount,
       shop_name:      shopName,
       cart_count:     cartCount,
@@ -4111,7 +4435,13 @@ function mount(router, deps) {
         shop_name: shopName, theme: theme,
       }));
     }
-    var lines = await deps.cart.listLines(c.id);
+    var rawLines = await deps.cart.listLines(c.id);
+    // Reapply the active quantity-break for each line at its current
+    // quantity before totals — the unit price the customer sees on the
+    // line, the line total, and the cart subtotal all reflect the break.
+    // Recomputed every render (idempotent); the stored snapshot is never
+    // mutated, so changing a line's quantity re-prices it automatically.
+    var lines = await _repriceCartLines(rawLines);
     var totals = pricing.totals(c, lines, {});
     // Build the variant_id → { product, hero_media } lookup the
     // renderer uses to decorate each line with a thumbnail + title.
@@ -6142,6 +6472,141 @@ function mount(router, deps) {
     res.end ? res.end() : res.send("");
   });
 
+  // POST /cart/bundle — add every member of a bundle to the cart at the
+  // bundle price, atomically. Reads `bundle_sku` from the form body.
+  // The price is recomputed server-side from the catalog + the bundle
+  // primitive (the client sends only the SKU, never a price). The
+  // bundle discount is allocated across the member lines proportional
+  // to each member's list contribution, so the cart subtotal equals the
+  // bundle's quoted price; integer-cent remainder lands on the last
+  // line. Mounted only when the bundles primitive is wired.
+  if (deps.bundles) {
+    router.post("/cart/bundle", async function (req, res) {
+      var body = req.body || {};
+      var bundleSku = body.bundle_sku;
+      if (!bundleSku || typeof bundleSku !== "string") {
+        res.status(400);
+        return res.end ? res.end("Invalid request") : res.send("Invalid request");
+      }
+      var currency = "USD";
+      // Resolve + price the bundle. A malformed sku throws TypeError
+      // (→ 400); an unknown sku resolves to no bundle (→ 404).
+      var bundle, leaves, priced;
+      try {
+        bundle = await deps.bundles.getBundle(bundleSku);
+        if (!bundle) {
+          res.status(404);
+          return res.end ? res.end("Bundle not found") : res.send("Bundle not found");
+        }
+        leaves = await deps.bundles.expand({ bundle_sku: bundleSku, quantity: 1 });
+        priced = await deps.bundles.priceBundle({ bundle_sku: bundleSku, pricing: _skuPricer(currency) });
+      } catch (e) {
+        if (e instanceof TypeError) {
+          res.status(400);
+          return res.end ? res.end((e && e.message) || "Invalid bundle") : res.send((e && e.message) || "Invalid bundle");
+        }
+        res.status(500);
+        return res.end ? res.end("Error") : res.send("Error");
+      }
+
+      // Pre-flight: every leaf must resolve to a buyable variant + a
+      // current price. All-or-nothing — if any member is unavailable,
+      // add nothing and bounce back to the PDP with a notice (no
+      // half-filled cart). `leaf.quantity` is the per-bundle demand.
+      var members = [];
+      for (var i = 0; i < leaves.length; i += 1) {
+        var leaf = leaves[i];
+        var variant = await _skuBuyable(leaf.sku);
+        if (!variant) {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/cart?bundle=unavailable");
+          return res.end ? res.end() : res.send("");
+        }
+        var price = await deps.catalog.prices.current(variant.id, currency);
+        if (!price) {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/cart?bundle=unavailable");
+          return res.end ? res.end() : res.send("");
+        }
+        members.push({
+          variant_id:   variant.id,
+          qty:          leaf.quantity,
+          list_each:    price.amount_minor,
+          list_line:    price.amount_minor * leaf.quantity,
+        });
+      }
+
+      // Allocate the bundle total across members proportional to each
+      // member's list contribution, then express each share as an integer
+      // per-unit price. The cart stores one integer unit price per line and
+      // charges qty*unit, so flooring a share to a per-unit price loses up
+      // to (qty-1) cents on a multi-unit line. Those cents are added back
+      // below so the cart subtotal equals the bundle price exactly — never
+      // undercharging the advertised bundle.
+      var listTotal = priced.list_total_minor;
+      var bundleTotal = priced.amount_minor;
+      var allocated = 0;
+      for (var m = 0; m < members.length; m += 1) {
+        var mem = members[m];
+        var share = listTotal > 0
+          ? Math.floor((bundleTotal * mem.list_line) / listTotal)
+          : Math.floor(bundleTotal / members.length);
+        mem.alloc_line = share;
+        allocated += share;
+      }
+      // The proportional floor leaves a whole-cent remainder; park it on the
+      // last member's line so the per-line allocations sum to the bundle
+      // total exactly.
+      if (members.length > 0) members[members.length - 1].alloc_line += (bundleTotal - allocated);
+
+      // Convert each member's line allocation to a uniform integer per-unit
+      // price (floor) and tally the cents lost to that floor across all
+      // lines. A single-unit line (the usual bundle shape) absorbs the whole
+      // shortfall exactly; failing that, the cents are returned in qty-sized
+      // steps to the smallest-quantity lines, with any final sub-step residual
+      // rounded up onto the smallest line — so the realized subtotal is never
+      // below the quoted bundle price.
+      var lostCents = 0;
+      for (var u = 0; u < members.length; u += 1) {
+        var me = members[u];
+        me.unit = me.qty > 0 ? Math.floor(me.alloc_line / me.qty) : me.alloc_line;
+        lostCents += me.alloc_line - (me.unit * me.qty);
+      }
+      if (lostCents > 0 && members.length > 0) {
+        var byQty = members.slice().sort(function (a, b) { return a.qty - b.qty; });
+        var single = null;
+        for (var s = 0; s < byQty.length; s += 1) { if (byQty[s].qty === 1) { single = byQty[s]; break; } }
+        if (single) {
+          single.unit += lostCents;
+        } else {
+          for (var g = 0; g < byQty.length && lostCents > 0; g += 1) {
+            while (lostCents >= byQty[g].qty) { byQty[g].unit += 1; lostCents -= byQty[g].qty; }
+          }
+          if (lostCents > 0) { byQty[0].unit += 1; lostCents = 0; }
+        }
+      }
+
+      var resolved = await _getOrCreateCart(req, res, currency);
+      try {
+        for (var k = 0; k < members.length; k += 1) {
+          var mk = members[k];
+          await deps.cart.addLine(resolved.cart.id, {
+            variant_id:        mk.variant_id,
+            qty:               mk.qty,
+            unit_amount_minor: mk.unit,
+            unit_currency:     currency,
+          });
+        }
+      } catch (e) {
+        res.status(e instanceof TypeError ? 400 : 500);
+        return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+      }
+      res.status(303);
+      res.setHeader && res.setHeader("location", "/cart");
+      res.end ? res.end() : res.send("");
+    });
+  }
+
   // POST /cart/lines/:line_id/update — change qty on an existing
   // line. Form value `qty` is the new quantity (1..99). HTML forms
   // only support GET/POST so the verb is in the path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {