@blamejs/blamejs-shop 0.2.28 → 0.2.29

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.2.x
 
+- v0.2.29 (2026-05-29) — **Show the real total before checkout and truthful stock on every product.** Two storefront truthfulness fixes. The cart and checkout now show the real total before payment — subtotal plus estimated tax, shipping, and any discount, all totalled — computed by the same engine that runs the actual charge, so the figure shown matches what will be charged (labelled estimated until an address narrows the tax and shipping, then exact; a destination with no matching rule reads 'calculated at checkout' rather than a wrong number). Cart lines also surface real stock state. On product pages, the buy box now reflects real per-variant inventory: an out-of-stock variant disables Add to cart with an honest message, and a low-stock variant shows 'Only N left'. **Fixed:** *The cart and checkout show your real total before you pay* — Previously the cart total was just the subtotal and checkout showed no tax/shipping until the payment step. Both now render subtotal + estimated tax + estimated shipping + discount + total, computed from the same tax/shipping primitives as the Stripe charge — the displayed estimate equals the confirmed order total to the cent. Figures are labelled 'estimated' until a shipping address is entered (then exact); a destination with no matching tax or shipping rule reads 'calculated at checkout', and the subtotal stays honest. Cart lines now also show out-of-stock / low-stock state. · *Product availability reflects real inventory* — The product buy box now reads real per-variant stock: an out-of-stock variant disables 'Add to cart' and shows an out-of-stock message (in the badge and the JSON-LD), and a variant at or below the configured low-stock threshold shows 'Only N left'. The add-to-cart control is no longer enabled for items that can't be bought.
+
 - v0.2.28 (2026-05-29) — **Sales reports and printable receipts in the admin console.** The admin console gains a Reports screen and printable order documents. Reports aggregates a sales and revenue summary over a date range you choose — order count, gross and net revenue, refunds, average order value, an order-status funnel, a by-day revenue table, and top products — with a CSV export of the daily series. Every order detail page now offers a printable receipt and a printable packing slip (print-optimized, carrying your shop name and contact), so you can pull a revenue report or print an order without querying the database directly. **Added:** *Reports screen* — `/admin/reports` aggregates a sales/revenue summary over a selectable date range: order count, gross and net revenue, refunds and refund rate, average order value, an order-status funnel, a by-day revenue table, and top products. The daily series exports to CSV. The screen reads only — it never writes. · *Printable receipts and packing slips* — `GET /admin/orders/:id/receipt` and `GET /admin/orders/:id/packing-slip` render self-contained, print-optimized order documents (lines, totals, ship-to, tracking barcode) with your shop name and contact in the masthead. Both are linked from a Documents panel on the admin order detail screen.
 
 - v0.2.27 (2026-05-29) — **Upload product images directly from the admin console.** The admin product media manager can now take an image file uploaded straight from your device, in addition to attaching one by URL. On the product detail screen, pick a PNG, JPEG, WebP, GIF, AVIF, or SVG and it streams to object storage and attaches to the product (or a specific variant) in one step. Every upload is validated by both its declared content type and its actual magic bytes — a mismatched or disguised file is refused — and capped at 10 MiB. The upload surface is only present when object storage is configured, so a store without it sees no change. **Added:** *Direct image-file upload in the admin product media manager* — A file picker on the admin product detail screen accepts a local image (`multipart/form-data`) alongside the existing attach-by-URL field. The file is content-type- and magic-byte-validated (png/jpeg/webp/gif/avif/svg), size-capped at 10 MiB, streamed to the object-storage bridge, and attached to the product or variant. JSON API: `POST /admin/products/:id/media/upload-file` and `POST /admin/media/upload-file`. The routes mount only when the object-storage bridge is configured.

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.2.28",
+  "version": "0.2.29",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",
       "fingerprinted": "css/admin.72c808274ebcefd9.css"
     },
     "css/main.css": {
-      "integrity": "sha384-E56XcvNC5nbTWyHJJcepF6sVA1KjRNo/MWFL5F5w2PDN10JNaHdzIAP9a46m2Md8",
-      "fingerprinted": "css/main.a76d36ac566703d6.css"
+      "integrity": "sha384-fnCp5krUbHLkDXg+zRbl1QWTkjKB4VJuu+gyfkn+7t/fsWqiKildlVjrs00p/bno",
+      "fingerprinted": "css/main.f9ddd7f75f5f7d09.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/storefront.js

@@ -1409,10 +1409,15 @@ var VARIANT_ROW =
 // keeps a per-row add form, so the same endpoint contract holds.
 // `variants` is the pre-formatted array [{ id, sku, title, price }]
 // the renderers already build; `escAttr` is the path's HTML escaper.
-// Mirrored byte-for-byte by worker/render/product.js#_buildBuyBox.
+// `availability` is the resolved `{ in_stock }` shape — when it reports
+// out of stock the add-to-cart control renders disabled with an honest
+// message instead of an active button, so the storefront never invites a
+// purchase the cart-hold path would reject. Mirrored byte-for-byte by
+// worker/render/product.js#_buildBuyBox.
 var BUYBOX_CHIP_LIMIT = 12;
 
-function _buildBuyBox(variants, escAttr) {
+function _buildBuyBox(variants, escAttr, availability) {
+  var inStock = !availability || availability.in_stock !== false;
   if (!variants || variants.length === 0) {
     return "<div class=\"pdp__variants\">\n" +
            "        <h2 class=\"pdp__variants-title\">Choose a variant</h2>\n" +
@@ -1430,10 +1435,27 @@ function _buildBuyBox(variants, escAttr) {
     "        <span class=\"pdp__badge\"><img class=\"pdp__badge-mark\" src=\"/assets/brand/favicon.svg\" alt=\"\" aria-hidden=\"true\" width=\"22\" height=\"22\"> Post-quantum secured checkout · ML-KEM-1024 key agreement · ML-DSA-65 receipt signature.</span>\n" +
     "      </div>";
 
+  // Out-of-stock add control: a disabled button + honest message,
+  // reused across all three buy-box shapes so a sold-out product never
+  // offers an active "add to cart" anywhere on the PDP.
+  var soldOutBtn =
+    "<button type=\"submit\" class=\"btn-primary cart-page__checkout\" disabled aria-disabled=\"true\">Out of stock</button>\n" +
+    "          <p class=\"pdp__soldout-note\" role=\"status\">This item is currently out of stock.</p>";
+  var soldOutRowBtn =
+    "<button type=\"submit\" class=\"btn-primary btn-primary--sm\" disabled aria-disabled=\"true\">Out of stock</button>";
+
   // Many variants → keep the compact table (still a per-row add form).
   if (variants.length > BUYBOX_CHIP_LIMIT) {
     var rows = variants.map(function (v) {
-      return _render(VARIANT_ROW, { title: v.title, sku: v.sku, price: v.price, variant_id: v.id });
+      var row = _render(VARIANT_ROW, { title: v.title, sku: v.sku, price: v.price, variant_id: v.id });
+      // When the product is out of stock, swap each per-row add button for
+      // the disabled control so no row offers an active purchase.
+      if (!inStock) {
+        row = row.replace(
+          "<button type=\"submit\" class=\"btn-primary btn-primary--sm\">Add to cart</button>",
+          soldOutRowBtn);
+      }
+      return row;
     }).join("");
     return "<div class=\"pdp__variants\">\n" +
            "        <h2 class=\"pdp__variants-title\">Choose a variant</h2>\n" +
@@ -1471,13 +1493,17 @@ function _buildBuyBox(variants, escAttr) {
       "          <div class=\"pdp__meta\">" + chips + "</div>\n" +
       "        </fieldset>";
 
+  var addControl = inStock
+    ? "<button type=\"submit\" class=\"btn-primary cart-page__checkout\">$ add to cart</button>"
+    : soldOutBtn;
+
   return "<div class=\"pdp__buybox\">\n" +
          "        <p class=\"featured-product__price\">" + escAttr(lead.price) + "</p>\n" +
          "        <form method=\"post\" action=\"/cart/lines\">\n" +
          "          " + variantBlock + "\n" +
          "          <label class=\"pdp__variants-title\" for=\"buybox-qty\">Quantity</label>\n" +
          "          <input id=\"buybox-qty\" type=\"number\" name=\"qty\" value=\"1\" min=\"1\" max=\"99\" class=\"variant-row__qty\" aria-label=\"Quantity\">\n" +
-         "          <button type=\"submit\" class=\"btn-primary cart-page__checkout\">$ add to cart</button>\n" +
+         "          " + addControl + "\n" +
          "        </form>\n" +
          "      </div>\n" +
          "      " + trustLine;
@@ -1489,16 +1515,22 @@ function _buildBuyBox(variants, escAttr) {
 // (the never-block-on-missing-inventory stance the cart-hold path already
 // takes). `requires_shipping` is true if ANY variant ships physically —
 // an all-digital product (`requires_shipping = 0` on every variant)
-// suppresses the "Ships in 1–2 business days" line. Returns a normalised
-// `{ in_stock, requires_shipping }` so the two render paths drive the
-// badge + JSON-LD from the same shape. Defensive request-shape reader:
-// missing/garbage inputs resolve to the available + physical default.
+// suppresses the "Ships in 1–2 business days" line. `low_stock` is the
+// smallest still-buyable count across the tracked variants when that count
+// sits at or below the variant's operator-configured `low_stock_threshold`
+// (null when no tracked variant is low, or no threshold is set) — drives
+// the honest "Only N left" nudge without hardcoding a global threshold.
+// Returns a normalised `{ in_stock, requires_shipping, low_stock }` so the
+// two render paths drive the badge + CTA + JSON-LD from the same shape.
+// Defensive request-shape reader: missing/garbage inputs resolve to the
+// available + physical default.
 function _resolveAvailability(variants, inventoryBySku) {
   variants = Array.isArray(variants) ? variants : [];
   var inv = (inventoryBySku && typeof inventoryBySku === "object") ? inventoryBySku : null;
   var anyTracked = false;
   var anyInStock = false;
   var requiresShipping = false;
+  var lowStock = null;
   for (var i = 0; i < variants.length; i += 1) {
     var v = variants[i] || {};
     // requires_shipping defaults to physical (true) unless the column is
@@ -1512,6 +1544,14 @@ function _resolveAvailability(variants, inventoryBySku) {
       var row = inv[v.sku];
       var available = row ? (Number(row.stock_on_hand) - Number(row.stock_held)) : 0;
       if (available > 0) anyInStock = true;
+      // Low-stock nudge: only when this variant is still buyable AND the
+      // operator set a threshold AND the count is at or below it. Track the
+      // smallest such count so a multi-variant product nudges on its
+      // scarcest in-stock variant.
+      var threshold = row ? Number(row.low_stock_threshold) : NaN;
+      if (available > 0 && Number.isFinite(threshold) && available <= threshold) {
+        if (lowStock === null || available < lowStock) lowStock = available;
+      }
     }
   }
   return {
@@ -1519,6 +1559,9 @@ function _resolveAvailability(variants, inventoryBySku) {
     // so the product reads as in stock (never-block stance).
     in_stock:          anyTracked ? anyInStock : true,
     requires_shipping: variants.length === 0 ? true : requiresShipping,
+    // Only surface a low-stock count when the product is actually in stock
+    // — an out-of-stock product never shows "Only N left".
+    low_stock:         (anyTracked ? anyInStock : true) ? lowStock : null,
   };
 }
 
@@ -1527,9 +1570,17 @@ function _resolveAvailability(variants, inventoryBySku) {
 // for-byte by worker/render/product.js#_buildAvailability.
 function _buildAvailability(availability) {
   var a = availability || { in_stock: true, requires_shipping: true };
-  var stockBadge = a.in_stock
-    ? "<span class=\"pdp__badge pdp__badge--ok\"><span class=\"dot dot--live\" aria-hidden=\"true\"></span> In stock</span>"
-    : "<span class=\"pdp__badge pdp__badge--out\">Out of stock</span>";
+  var low = Number(a.low_stock);
+  var stockBadge;
+  if (!a.in_stock) {
+    stockBadge = "<span class=\"pdp__badge pdp__badge--out\">Out of stock</span>";
+  } else if (Number.isFinite(low) && low > 0) {
+    // In stock but running low — an honest scarcity nudge driven by the
+    // operator's configured threshold, not a hardcoded number.
+    stockBadge = "<span class=\"pdp__badge pdp__badge--low\"><span class=\"dot dot--live\" aria-hidden=\"true\"></span> Only " + low + " left</span>";
+  } else {
+    stockBadge = "<span class=\"pdp__badge pdp__badge--ok\"><span class=\"dot dot--live\" aria-hidden=\"true\"></span> In stock</span>";
+  }
   // The "Ships in 1–2 business days" line only applies to a physical good;
   // an all-digital product suppresses it (nothing ships).
   var shipBadge = a.requires_shipping
@@ -3668,7 +3719,7 @@ function renderProduct(opts) {
   // loads ({ sku: { stock_on_hand, stock_held } }); absent it, the
   // product reads as in stock (never-block-on-missing-inventory stance).
   var availability = _resolveAvailability(variants, opts.inventory);
-  var buyboxHtml = _buildBuyBox(rendered, b.template.escapeHtml);
+  var buyboxHtml = _buildBuyBox(rendered, b.template.escapeHtml, availability);
   var availabilityHtml = _buildAvailability(availability);
   var shippingNoteHtml = _pdpShippingNote(availability);
   var galleryHtml = _buildPdpGallery(opts.product, opts.media || [], opts.asset_prefix || "/assets/");
@@ -3814,6 +3865,7 @@ var CART_LINE_EDITABLE =
   "      <span class=\"cart-line__product-meta\">\n" +
   "        <span class=\"cart-line__product-title\">{{product_title}}</span>\n" +
   "        <code class=\"cart-line__sku-chip\">{{sku}}</code>\n" +
+  "RAW_CART_LINE_STOCK" +
   "      </span>\n" +
   "    </a>\n" +
   "  </td>\n" +
@@ -3885,10 +3937,12 @@ function _shipToFromBody(body) {
 
 // Checkout mirrors the cart's two-column shell: the shipping form on the
 // left, a sticky order-summary rail on the right. The summary lists the
-// cart line items + the Subtotal, then the cart's exact honest microcopy
-// — tax + shipping can't be computed until the address is entered, so no
-// fabricated "Total" is shown. An "Edit cart" link near the summary lets
-// the shopper change quantities without losing form data.
+// cart line items + a full Subtotal → tax → shipping → discount → Total
+// breakdown, computed from the same tax/shipping primitives the charge
+// runs through (estimated against the destination until the shopper
+// submits an address; exact on the POST re-render of an entered address).
+// An "Edit cart" link near the summary lets the shopper change quantities
+// without losing form data.
 var CHECKOUT_PAGE =
   "<section class=\"checkout-page\">\n" +
   "  <header class=\"section-head\">\n" +
@@ -3912,9 +3966,9 @@ var CHECKOUT_PAGE =
   "      </div>\n" +
   "      <ul class=\"checkout-page__lines\">RAW_SUMMARY_LINES</ul>\n" +
   "      <dl class=\"totals-list\">\n" +
-  "        <div class=\"totals-list__grand\"><dt>Subtotal</dt><dd>{{subtotal}}</dd></div>\n" +
+  "RAW_TOTALS_ROWS" +
   "      </dl>\n" +
-  "      <p class=\"cart-page__note\">Tax and shipping are calculated on the next step. Payment runs through Stripe.</p>\n" +
+  "RAW_SUMMARY_NOTE" +
   "    </aside>\n" +
   "  </div>\n" +
   "</section>\n";
@@ -3973,13 +4027,25 @@ function renderCheckoutForm(opts) {
   var shopName = opts.shop_name || "blamejs.shop";
   var assetPrefix = opts.asset_prefix || "/assets/";
   var lookup = opts.product_lookup || {};
-  var subtotal = pricing.format(totals.subtotal_minor, totals.currency);
+  // Full totals breakdown when the route bundled one (`totals_detail` from
+  // _estimateCartTotals); else a subtotal-only fallback so an un-wired
+  // checkout still renders an honest Subtotal. Checkout formats in the
+  // order's own currency (no display-currency conversion at the pay step).
+  var detail = opts.totals_detail || {
+    totals: totals, estimated: true, tax_resolved: false, shipping_resolved: false, shipping_label: null,
+  };
+  var dTotals = detail.totals || totals;
+  var subtotal = pricing.format(dTotals.subtotal_minor, dTotals.currency);
+  var grandTotal = pricing.format(
+    dTotals.grand_total_minor == null ? dTotals.subtotal_minor : dTotals.grand_total_minor,
+    dTotals.currency);
   if (opts.theme) {
     return opts.theme.render("checkout", {
       title:          "Checkout",
       shop_name:      shopName,
       cart_count:     lines.length,
       subtotal:       subtotal,
+      total:          grandTotal,
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
@@ -3990,13 +4056,21 @@ function renderCheckoutForm(opts) {
   var summaryLines = lines.map(function (l) {
     return _checkoutSummaryLine(l, lookup, assetPrefix, pricing.format);
   }).join("");
+  var totalsRows = _buildCartTotalsRows(detail, pricing.format, subtotal, grandTotal);
+  // Honest summary microcopy: an estimate finalizes at the address step;
+  // an entered address reads as the exact total. Mirrors the cart CTA note.
+  var summaryNote = detail.estimated
+    ? "      <p class=\"cart-page__note\">Estimated tax and shipping for your destination; the exact total is confirmed when you continue. Payment runs through Stripe.</p>\n"
+    : "      <p class=\"cart-page__note\">Total includes tax and shipping for the address above. Payment runs through Stripe.</p>\n";
   // A coded gift-card / loyalty error from a rejected POST re-renders the
   // form with the message inline (role="alert") rather than dead-ending on
   // a separate error page — the shopper fixes the bad code in place.
   var inlineError = opts.inline_error
     ? "<p class=\"auth-form__message auth-form__message--err\" role=\"alert\">" + b.template.escapeHtml(String(opts.inline_error)) + "</p>"
     : "";
-  var body = _render(CHECKOUT_PAGE, { subtotal: subtotal })
+  var body = _render(CHECKOUT_PAGE, {})
+    .replace("RAW_TOTALS_ROWS", totalsRows)
+    .replace("RAW_SUMMARY_NOTE", summaryNote)
     .replace("RAW_INLINE_ERROR", inlineError)
     .replace("RAW_SHIPPING_FIELDS", _checkoutShippingFields(opts.prefill))
     .replace("RAW_SUMMARY_LINES", summaryLines);
@@ -4544,8 +4618,7 @@ var CART_PAGE =
   "    <aside class=\"cart-page__summary\">\n" +
   "      <h2 class=\"pdp__variants-title\">Order summary</h2>\n" +
   "      <dl class=\"totals-list\">\n" +
-  "        <div><dt>Subtotal</dt><dd>{{subtotal}}</dd></div>\n" +
-  "        <div class=\"totals-list__grand\"><dt>Total</dt><dd>{{total}}</dd></div>\n" +
+  "RAW_TOTALS_ROWS" +
   "      </dl>\n" +
   "RAW_CHECKOUT_CTA" +
   "    </aside>\n" +
@@ -4618,6 +4691,57 @@ function renderCheckoutError(opts) {
   });
 }
 
+// Build the order-summary `<dl>` rows shared by the cart + checkout
+// totals lists. Renders Subtotal, an optional discount, tax, shipping,
+// and the grand Total — composing the real tax/shipping/discount figures
+// the pricing primitive computed for the destination. Each of tax +
+// shipping is shown in one of two honest states:
+//
+//   - a real amount, under an "Estimated tax" / "Estimated shipping" /
+//     "Estimated total" label while the destination isn't yet confirmed
+//     by the shopper (so the figure is never read as the final charge);
+//   - "Calculated at checkout" when no rule/zone matched the destination
+//     (a labelled deferral, never a fabricated 0).
+//
+// `fmt` is the per-request price formatter (display-currency aware). When
+// `t.estimated` is false (the checkout POST re-render of an entered
+// address) the labels drop the "Estimated" prefix and the figures read
+// as exact. `subtotalStr`/`totalStr` are pre-formatted so the caller
+// controls display-currency conversion.
+function _buildCartTotalsRows(t, fmt, subtotalStr, totalStr) {
+  var totals    = t.totals;
+  var estimated = !!t.estimated;
+  var rows = "        <div><dt>Subtotal</dt><dd>" + subtotalStr + "</dd></div>\n";
+  if (totals.discount_minor > 0) {
+    rows += "        <div class=\"totals-list__discount\"><dt>Discount</dt><dd>−" +
+      fmt(totals.discount_minor, totals.currency) + "</dd></div>\n";
+  }
+  // Tax row.
+  var taxLabel = estimated ? "Estimated tax" : "Tax";
+  if (t.tax_resolved) {
+    rows += "        <div><dt>" + taxLabel + "</dt><dd>" + fmt(totals.tax_minor, totals.currency) + "</dd></div>\n";
+  } else if (totals.tax_minor > 0) {
+    // A non-zero tax with no jurisdiction match still reflects a real
+    // computed figure — show it under the estimate label.
+    rows += "        <div><dt>" + taxLabel + "</dt><dd>" + fmt(totals.tax_minor, totals.currency) + "</dd></div>\n";
+  } else {
+    rows += "        <div class=\"totals-list__pending\"><dt>Tax</dt><dd>Calculated at checkout</dd></div>\n";
+  }
+  // Shipping row.
+  var shipLabel = estimated ? "Estimated shipping" : "Shipping";
+  if (t.shipping_resolved) {
+    var shipValue = totals.shipping_minor === 0 ? "Free" : fmt(totals.shipping_minor, totals.currency);
+    rows += "        <div><dt>" + shipLabel + "</dt><dd>" + shipValue + "</dd></div>\n";
+  } else {
+    rows += "        <div class=\"totals-list__pending\"><dt>Shipping</dt><dd>Calculated at checkout</dd></div>\n";
+  }
+  // Grand total. On an estimate, label it so the figure is never read as
+  // the committed charge before the address step.
+  var totalLabel = estimated ? "Estimated total" : "Total";
+  rows += "        <div class=\"totals-list__grand\"><dt>" + totalLabel + "</dt><dd>" + totalStr + "</dd></div>\n";
+  return rows;
+}
+
 function renderCart(opts) {
   if (!opts) throw new TypeError("storefront.renderCart: opts required");
   var lines  = opts.lines  || [];
@@ -4628,6 +4752,10 @@ function renderCart(opts) {
   // route handler bundles it in. Lines without an entry render with
   // a dashed-placeholder tile + the SKU as the fallback title.
   var lookup  = opts.product_lookup || {};
+  // Per-line stock state map (variant_id → "out" | "low" | "ok"), bundled
+  // by the route handler. Absent for back-compat callers / the edge empty
+  // cart — those lines render with no badge (the never-block stance).
+  var lineStock = opts.line_stock || {};
   var fmt = _priceFormatter(opts);
   var rendered = lines.map(function (l) {
     var match  = lookup[l.variant_id] || null;
@@ -4645,6 +4773,7 @@ function renderCart(opts) {
       product_url:    prod ? ("/products/" + prod.slug) : "#",
       image_url:      imageUrl,
       image_alt:      imageAlt,
+      stock:          lineStock[l.variant_id] || "ok",
     };
   });
   var subtotal = fmt(totals.subtotal_minor,    totals.currency);
@@ -4678,6 +4807,16 @@ function renderCart(opts) {
       var saveBtn = canSave
         ? "<form method=\"post\" action=\"/cart/lines/" + _escAttr(l.id) + "/save\"><button type=\"submit\" class=\"cart-line__btn cart-line__btn--save\">Save for later</button></form>"
         : "";
+      // Real per-line availability badge — never a hardcoded "in stock".
+      // Out-of-stock + low-stock surface a status pill so the shopper sees
+      // the truth before they commit; an "ok" line shows nothing (the
+      // implied default). `role="status"` so a screen reader announces it.
+      var stockBadge = "";
+      if (l.stock === "out") {
+        stockBadge = "        <span class=\"cart-line__stock cart-line__stock--out\" role=\"status\">Out of stock</span>\n";
+      } else if (l.stock === "low") {
+        stockBadge = "        <span class=\"cart-line__stock cart-line__stock--low\" role=\"status\">Low stock</span>\n";
+      }
       return _render(CART_LINE_EDITABLE, {
         sku:            l.sku,
         qty:            l.qty,
@@ -4686,27 +4825,55 @@ function renderCart(opts) {
         line_id:        l.id,
         product_title:  l.product_title,
         product_url:    l.product_url,
-      }).replace("RAW_CART_LINE_THUMB", thumb).replace("RAW_CART_LINE_SAVE", saveBtn);
+      }).replace("RAW_CART_LINE_THUMB", thumb).replace("RAW_CART_LINE_STOCK", stockBadge).replace("RAW_CART_LINE_SAVE", saveBtn);
     }).join("");
     // Checkout CTA — only a live button when checkout is actually wired
     // (Stripe configured). Absent that, render a clear, disabled "not set
     // up" notice instead of a link that 404s. Backward-compatible: callers
     // that don't pass the flag (older tests) keep the button.
     var checkoutAvailable = opts.checkout_available !== false;
+    // Truthful CTA note. When the route bundled an estimated totals
+    // breakdown, say the figures are an estimate that finalizes once the
+    // shipping address is entered — never the stale "calculated on the next
+    // step" (which implied the cart total was just the subtotal). Without a
+    // breakdown (back-compat caller), keep the prior note.
+    var ctaNote;
+    if (opts.totals_detail && opts.totals_detail.estimated) {
+      ctaNote = "      <p class=\"cart-page__note\">Estimated tax and shipping shown above; the exact total is confirmed once you enter your shipping address. Payment runs through Stripe.</p>\n";
+    } else if (opts.totals_detail) {
+      ctaNote = "      <p class=\"cart-page__note\">Total includes tax and shipping for your address. Payment runs through Stripe.</p>\n";
+    } else {
+      ctaNote = "      <p class=\"cart-page__note\">Tax and shipping are calculated on the next step. Payment runs through Stripe.</p>\n";
+    }
     var checkoutCta = checkoutAvailable
       ? "      <a href=\"/checkout\" class=\"btn-primary cart-page__checkout\">Continue to checkout <span aria-hidden=\"true\">→</span></a>\n" +
-        "      <p class=\"cart-page__note\">Tax and shipping are calculated on the next step. Payment runs through Stripe.</p>\n"
+        ctaNote
       : "      <button type=\"button\" class=\"btn-primary cart-page__checkout\" disabled aria-disabled=\"true\">Checkout unavailable</button>\n" +
         "      <p class=\"cart-page__note cart-page__note--warn\" role=\"status\">Online checkout isn't set up for this store yet — payments aren't configured. Your cart is saved; please check back soon.</p>\n";
     // Post-add confirmation banner — rendered only on the `?added=1`
     // redirect from POST /cart/lines so the shopper gets explicit feedback
     // their item landed (the audit found the silent 303 left no cue).
     var notice = opts.added ? CART_ADDED_NOTICE : "";
+    // The order-summary rows. When the route bundled a totals breakdown
+    // (`totals_detail` from _estimateCartTotals), render the full Subtotal
+    // → tax → shipping → discount → Total list with the destination's real
+    // computed figures (estimate-labelled until the address step). Absent
+    // that — a back-compat caller passing only `opts.totals` — fall back to
+    // the bare Subtotal + Total list (byte-identical to the prior shape).
+    var totalsRows;
+    if (opts.totals_detail) {
+      totalsRows = _buildCartTotalsRows(opts.totals_detail, fmt, subtotal, total);
+    } else {
+      totalsRows =
+        "        <div><dt>Subtotal</dt><dd>" + subtotal + "</dd></div>\n" +
+        "        <div class=\"totals-list__grand\"><dt>Total</dt><dd>" + total + "</dd></div>\n";
+    }
     body = _render(CART_PAGE, {
       line_rows: "RAW_LINES",
-      subtotal:  subtotal,
-      total:     total,
-    }).replace("RAW_LINES", rows).replace("RAW_CHECKOUT_CTA", checkoutCta).replace("RAW_CART_NOTICE", notice);
+    }).replace("RAW_LINES", rows)
+      .replace("RAW_TOTALS_ROWS", totalsRows)
+      .replace("RAW_CHECKOUT_CTA", checkoutCta)
+      .replace("RAW_CART_NOTICE", notice);
   }
   return _wrap(Object.assign({
     title:      "Cart",
@@ -6834,6 +7001,177 @@ function mount(router, deps) {
     return out;
   }
 
+  // Resolve the destination the cart/checkout totals estimate against,
+  // most-specific first: (1) the signed-in customer's default shipping
+  // address, (2) the operator's `shop.estimate_destination` config, (3) a
+  // bare `{ country: "US" }`. Every read is best-effort — a missing
+  // address table, an unmigrated config row, or a malformed saved value
+  // degrades to the next fallback rather than 500-ing the cart. The
+  // returned shape is the `ship_to` the tax/shipping primitives consume,
+  // plus `from_saved` so the renderer can say "estimated for your saved
+  // address" vs "estimated for <country>". A garbage country code from
+  // any source is dropped (→ the US default) so the estimate never throws
+  // inside the primitive's strict validators.
+  async function _estimateDestination(req) {
+    function _normalize(d, fromSaved) {
+      if (!d || typeof d !== "object") return null;
+      var country = typeof d.country === "string" ? d.country.toUpperCase() : "";
+      if (!/^[A-Z]{2}$/.test(country)) return null;
+      var state = (typeof d.state === "string" && /^[A-Za-z0-9]{1,5}$/.test(d.state))
+        ? d.state.toUpperCase() : undefined;
+      var postal = (typeof d.postal === "string" && /^[A-Za-z0-9 -]{1,16}$/.test(d.postal))
+        ? d.postal : undefined;
+      return { ship_to: { country: country, state: state, postal: postal }, from_saved: !!fromSaved };
+    }
+    // (1) Signed-in customer's default shipping address.
+    var coAuth = _currentCustomerEnv(req);
+    if (deps.addresses && coAuth) {
+      try {
+        var rows = await deps.addresses.listForCustomer(coAuth.customer_id, { limit: 50 });
+        var pick = null;
+        for (var ai = 0; ai < rows.length; ai += 1) {
+          if (Number(rows[ai].is_default_shipping) === 1) { pick = rows[ai]; break; }
+        }
+        if (!pick && rows.length) pick = rows[0];
+        if (pick) {
+          var n = _normalize({
+            country: pick.country,
+            // Saved `region` is free-text ("California"); _normalize only
+            // carries it when it already matches the subdivision-code shape.
+            state:   pick.region,
+            postal:  pick.postal_code,
+          }, true);
+          if (n) return n;
+        }
+      } catch (_e) { /* fall through to config / default */ }
+    }
+    // (2) Operator-configured default destination.
+    if (deps.config && typeof deps.config.get === "function") {
+      try {
+        var cfg = await deps.config.get("shop.estimate_destination", null);
+        var c2 = _normalize(cfg, false);
+        if (c2) return c2;
+      } catch (_e) { /* fall through to the US default */ }
+    }
+    // (3) Bare US default — the storefront's documented estimate locale.
+    return { ship_to: { country: "US" }, from_saved: false };
+  }
+
+  // Compute the cart/checkout totals the shopper sees BEFORE paying.
+  // Composes the SAME tax + shipping primitives the charge runs through
+  // (via checkout.quote, which prices tax against the post-discount
+  // subtotal + picks shipping rates for the destination), so the
+  // displayed grand total agrees with what Stripe is later asked to
+  // charge for that destination. Returns:
+  //
+  //   {
+  //     totals,            // pricing.totals() breakdown (always present)
+  //     estimated,         // true when tax/shipping are an estimate
+  //                        //   (destination not yet confirmed by the shopper)
+  //     tax_resolved,      // a tax rule matched the destination
+  //     shipping_resolved, // a shipping service priced the destination
+  //     shipping_label,    // the chosen estimate service's label, or null
+  //     destination,       // { ship_to, from_saved } the estimate used
+  //   }
+  //
+  // `opts.confirmed` marks a destination the shopper actually entered
+  // (the checkout POST re-render) so the figures read as exact, not an
+  // estimate. Degrades gracefully at every step: no checkout dep, a
+  // quote failure, or no shipping zone match all fall back to a
+  // subtotal-only breakdown with tax/shipping flagged unresolved — the
+  // subtotal is always honest, and the renderer labels the rest
+  // "calculated at checkout" rather than fabricating a number.
+  async function _estimateCartTotals(req, c, lines, opts) {
+    opts = opts || {};
+    var base = pricing.totals(c, lines, {});   // subtotal-only, always valid
+    var result = {
+      totals:            base,
+      estimated:         !opts.confirmed,
+      tax_resolved:      false,
+      shipping_resolved: false,
+      shipping_label:    null,
+      destination:       null,
+    };
+    if (!deps.checkout || typeof deps.checkout.quote !== "function") return result;
+    var dest = opts.ship_to
+      ? { ship_to: opts.ship_to, from_saved: false }
+      : await _estimateDestination(req);
+    result.destination = dest;
+    try {
+      // quote() without a selected_shipping_id returns the tax row + ALL
+      // available shipping services without throwing on selection; we pick
+      // the cheapest as the estimate so the shopper sees the lowest real
+      // shipping figure for the destination (they choose the exact service
+      // at the address step).
+      var quote = await deps.checkout.quote({
+        cart_id:  c.id,
+        ship_to:  dest.ship_to,
+      });
+      var taxMinor = quote.totals.tax_minor;
+      result.tax_resolved = quote.tax_rate_bps > 0 ||
+        (quote.tax_jurisdiction && quote.tax_jurisdiction !== "fallback");
+      var rates = Array.isArray(quote.shipping_rates) ? quote.shipping_rates : [];
+      var cheapest = null;
+      for (var i = 0; i < rates.length; i += 1) {
+        if (cheapest === null || rates[i].amount_minor < cheapest.amount_minor) cheapest = rates[i];
+      }
+      var shippingMinor = 0;
+      if (cheapest) {
+        shippingMinor = cheapest.amount_minor;
+        result.shipping_resolved = true;
+        result.shipping_label = cheapest.label;
+      }
+      result.totals = pricing.totals(c, lines, {
+        tax_minor:      taxMinor,
+        shipping_minor: shippingMinor,
+        discount_minor: quote.totals.discount_minor || 0,
+      });
+    } catch (_e) {
+      // Quote failed (cart not active, primitive error) — keep the honest
+      // subtotal-only breakdown; the renderer shows "calculated at
+      // checkout" for the unresolved lines.
+      return result;
+    }
+    return result;
+  }
+
+  // Per-line stock truth for the cart: maps each line's variant SKU to its
+  // availability state so the cart can say "Low stock" / "Out of stock"
+  // instead of an implied always-buyable. Best-effort — a SKU with no
+  // inventory row (or a read failure) is treated as available, matching the
+  // storefront's never-block-on-missing-inventory stance. Returns a map
+  // keyed by variant_id → "out" | "low" | "ok". Low is the operator's
+  // configured low-stock threshold (`shop.low_stock_threshold`, default 5)
+  // applied to available-on-hand (stock_on_hand − stock_held).
+  async function _cartLineStock(lines) {
+    var out = {};
+    if (!deps.catalog || !deps.catalog.inventory || typeof deps.catalog.inventory.get !== "function") {
+      return out;
+    }
+    var threshold = 5;
+    if (deps.config && typeof deps.config.get === "function") {
+      try {
+        var t = await deps.config.get("shop.low_stock_threshold", 5);
+        if (Number.isInteger(t) && t >= 0) threshold = t;
+      } catch (_e) { /* keep the default */ }
+    }
+    for (var i = 0; i < lines.length; i += 1) {
+      var vId = lines[i].variant_id;
+      if (Object.prototype.hasOwnProperty.call(out, vId)) continue;
+      var sku = lines[i].sku;
+      if (!sku) { out[vId] = "ok"; continue; }
+      try {
+        var inv = await deps.catalog.inventory.get(sku);
+        if (!inv) { out[vId] = "ok"; continue; }
+        var avail = Number(inv.stock_on_hand || 0) - Number(inv.stock_held || 0);
+        out[vId] = avail <= 0 ? "out" : (avail <= threshold ? "low" : "ok");
+      } catch (_e) {
+        out[vId] = "ok";   // drop-silent — a read failure never blocks the cart
+      }
+    }
+    return out;
+  }
+
   // POST /currency — set (or clear) the visitor's display-currency choice.
   // Registered only when multi-currency display is wired. Display-only:
   // this NEVER touches the cart / order / payment currency — it sets the
@@ -7506,7 +7844,16 @@ function mount(router, deps) {
     // 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, {});
+    // Real total before pay: compose the same tax + shipping primitives the
+    // charge runs through (estimated against the shopper's saved/default
+    // destination until they confirm an address at checkout). Falls back to
+    // a subtotal-only breakdown — with tax/shipping labelled "calculated at
+    // checkout" — when checkout isn't wired or no zone matches.
+    var totalsDetail = await _estimateCartTotals(req, c, lines, {});
+    var totals = totalsDetail.totals;
+    // Truthful per-line stock state (out / low / ok) so the cart never
+    // implies a sold-out line is buyable.
+    var lineStock = await _cartLineStock(lines);
     // Build the variant_id → { product, hero_media } lookup the
     // renderer uses to decorate each line with a thumbnail + title.
     // Cache by variant_id so a cart with the same variant twice
@@ -7527,6 +7874,8 @@ function mount(router, deps) {
     _send(res, 200, renderCart(Object.assign({
       lines:           lines,
       totals:          totals,
+      totals_detail:   totalsDetail,
+      line_stock:      lineStock,
       product_lookup:  productLookup,
       can_save:        !!(deps.saveForLater && deps.customers),
       checkout_available: !!(deps.checkout && deps.order),
@@ -7578,8 +7927,18 @@ function mount(router, deps) {
     // catch (so a rejected gift-card / loyalty code re-renders the same
     // form inline instead of dead-ending). `inlineError` is the optional
     // message to surface at the top of the form.
-    async function _checkoutRenderOpts(req, c, lines, inlineError) {
-      var totals = pricing.totals(c, lines, {});
+    async function _checkoutRenderOpts(req, c, lines, inlineError, confirmedShipTo) {
+      // Full totals breakdown the summary renders. When the shopper has
+      // entered an address (the POST re-render passes `confirmedShipTo`),
+      // compute the EXACT total against it (estimated:false); otherwise
+      // estimate against the saved/default destination so the summary
+      // still shows a real Subtotal → tax → shipping → Total rather than a
+      // bare subtotal. Composes the same tax/shipping primitives the charge
+      // runs through (via checkout.quote inside _estimateCartTotals).
+      var totalsDetail = await _estimateCartTotals(req, c, lines, confirmedShipTo
+        ? { ship_to: confirmedShipTo, confirmed: true }
+        : {});
+      var totals = totalsDetail.totals;
       // variant_id → { product, hero_media } lookup for the summary
       // thumbnails + titles — same shape (and caching) the cart route uses.
       var checkoutLookup = {};
@@ -7630,7 +7989,8 @@ function mount(router, deps) {
         } catch (_e) { prefill = null; }
       }
       return {
-        lines: lines, totals: totals, shop_name: shopName, theme: theme,
+        lines: lines, totals: totals, totals_detail: totalsDetail,
+        shop_name: shopName, theme: theme,
         product_lookup: checkoutLookup,
         paypal_client_id: deps.paypal ? deps.paypal_client_id : null,
         loyalty_balance: loyaltyBalance,
@@ -7739,7 +8099,11 @@ function mount(router, deps) {
           try {
             var coLines = await _repriceCartLines(await deps.cart.listLines(c.id));
             if (coLines.length) {
-              return _send(res, 400, renderCheckoutForm(await _checkoutRenderOpts(req, c, coLines, msg)));
+              // The shopper already entered an address on this POST — re-price
+              // the summary against it (exact, not estimated) so the inline
+              // re-render shows the same total the confirm path computed.
+              var confirmedTo = (shipTo && /^[A-Z]{2}$/.test(shipTo.country)) ? shipTo : null;
+              return _send(res, 400, renderCheckoutForm(await _checkoutRenderOpts(req, c, coLines, msg, confirmedTo)));
             }
           } catch (_re) { /* fall through to the styled error page */ }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "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": {