@blamejs/blamejs-shop 0.2.27 → 0.2.29

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.2.26 (2026-05-29) — **Update the vendored blamejs runtime to v0.13.44.** The bundled blamejs runtime moves from v0.13.0 to v0.13.44, carrying a run of upstream security and reliability fixes through the crypto, storage, and middleware layers the shop is built on, with no API or configuration changes. Highlights: DNSSEC validation now bounds the work spent on colliding keys and signatures (KeyTrap / NSEC3 resource-exhaustion defense); a sealed database column that fails to unseal now returns null instead of risking forged or cross-row ciphertext; the encrypted database gains a temporary-storage free-space guard and a shutdown watchdog that preserves the final flush on exit; S/MIME chain verification binds the leaf certificate to the verifying signer key; archive extraction refuses Windows reserved and alternate-data-stream path names; and the replay-nonce store is memory-capped and fails closed under flood. **Changed:** *Database reliability under low temporary storage* — The encrypted database now refuses growth-writes with a clear error when its temporary storage drops below a safety headroom (rather than risking corruption), and a shutdown watchdog preserves the final database flush if a shutdown phase hangs. Both harden the container restart path. **Security:** *Bundled blamejs runtime updated to v0.13.44* — Pulls in the upstream security fixes accumulated since v0.13.0: DNSSEC KeyTrap / NSEC3 work caps, sealed-column null-on-unseal-failure (no forged or cross-row ciphertext), S/MIME leaf-to-signer binding, archive-extraction rejection of Windows reserved / alternate-data-stream names, static-file sibling-prefix path containment, and a memory-capped, fail-closed replay-nonce store. No API or configuration changes are required.

package/lib/admin.js

@@ -371,10 +371,16 @@ function mount(router, deps) {
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
   var customers     = deps.customers     || null;   // read-only customers console disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
+  var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
+  var printReceipts = deps.printReceipts || null;   // order receipt document disabled when absent
+  var packingSlips  = deps.packingSlips  || null;   // order packing-slip document disabled when absent
 
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
   // into every authed render call as `nav_available`.
+  // `reports` is always present in the nav (read-only sales summary needs no
+  // extra dep); its route mounts unconditionally and renders an unconfigured
+  // notice when the salesReports primitive isn't wired.
   var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
@@ -1379,6 +1385,10 @@ function mount(router, deps) {
         // Shipment/tracking panel only renders when the tracking primitive
         // is wired; the carrier + status enums drive its form selects.
         can_track:   !!orderTracking,
+        // Printable-document links — shown only when the render primitive is
+        // wired (its route is mounted only then).
+        can_receipt:      !!printReceipts,
+        can_packing_slip: !!packingSlips,
         shipments:   shipments,
         carriers:    orderTracking ? orderTracking.CARRIERS : null,
         statuses:    orderTracking ? orderTracking.STATUSES : null,
@@ -3160,6 +3170,288 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- reporting ------------------------------------------------------
+  //
+  // A sales/revenue report over a selectable date range: order count,
+  // gross/net revenue, refunds, AOV, top products, broken down by day and
+  // by status. Aggregated from the salesReports primitive (pure read-only
+  // SQL over orders/order_lines). The route mounts unconditionally so the
+  // always-present "Reports" nav link never points at a missing route; when
+  // the salesReports primitive isn't wired it renders an unconfigured
+  // notice. CSV export of the by-day series is exposed via `?format=csv`.
+  //
+  // Date range: `from`/`to` are epoch-ms query params (defaults to the last
+  // 30 days). A malformed range re-renders the page with a 400 + the
+  // validator's message rather than crashing — the report is config/entry
+  // tier, so a bad operator-typed range surfaces as a correction, not a 500.
+
+  // Parse a "YYYY-MM-DD" calendar-date param to the epoch-ms at UTC
+  // midnight. Returns null when the param is absent; throws TypeError on a
+  // malformed value so the config/entry-tier 400 path catches it. The
+  // browser date <input> submits this shape; the JSON API can use either
+  // this or the raw epoch-ms `from`/`to`.
+  function _parseDateParam(str, label) {
+    if (str == null || str === "") return null;
+    if (typeof str !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(str)) {
+      throw new TypeError("admin: " + label + " must be a YYYY-MM-DD date");
+    }
+    var ms = Date.parse(str + "T00:00:00Z");
+    if (!isFinite(ms)) throw new TypeError("admin: " + label + " is not a valid date");
+    return ms;
+  }
+
+  // Resolve the report window from the query string. Returns
+  // `{ from, to }` (epoch-ms) or throws TypeError on a malformed value.
+  // Accepts either the raw epoch-ms `from`/`to` pair (machine clients) or
+  // the calendar-date `from-date`/`to-date` pair (the browser date inputs);
+  // the epoch-ms form wins when both are present. Defaults: to = now,
+  // from = now - 30d. The salesReports primitive re-validates (from < to,
+  // span ≤ 1y), so this only coerces the shape.
+  function _reportWindow(url) {
+    var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+    var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+    if (from == null) from = _parseDateParam(url && url.searchParams.get("from-date"), "from");
+    // `to-date` is the inclusive end day — advance to the next UTC midnight
+    // so the window covers the whole selected day (salesReports treats `to`
+    // as exclusive: `updated_at < to`).
+    if (to == null) {
+      var toDate = _parseDateParam(url && url.searchParams.get("to-date"), "to");
+      if (toDate != null) to = toDate + b.constants.TIME.days(1);
+    }
+    var now  = Date.now();
+    return {
+      to:   to   == null ? now : to,
+      from: from == null ? (now - b.constants.TIME.days(30)) : from,
+    };
+  }
+
+  // Aggregate the report payload from the salesReports primitive. Composes
+  // the by-day revenue series, AOV, refund rate, the status funnel, and the
+  // top products into one object the HTML + CSV + JSON surfaces all read.
+  async function _buildReport(win) {
+    var byDay  = await salesReports.revenueByDay({ from: win.from, to: win.to });
+    var aov    = await salesReports.aov({ from: win.from, to: win.to });
+    var refund = await salesReports.refundRate({ from: win.from, to: win.to });
+    var funnel = await salesReports.funnel({ from: win.from, to: win.to });
+    var top    = await salesReports.topProducts({ from: win.from, to: win.to, limit: 10 });
+
+    // Headline totals from the by-day series — gross/net/refunds summed
+    // across every currency bucket in the window. The per-currency split
+    // stays on the by-day rows for the operator who needs it; the headline
+    // is the single-number summary a dashboard leads with.
+    var orderCount = 0, gross = 0, net = 0, refunds = 0;
+    var currency = (aov && aov.currency) || "USD";
+    for (var i = 0; i < byDay.length; i += 1) {
+      var row = byDay[i];
+      orderCount += row.order_count;
+      gross      += row.gross_revenue_minor;
+      net        += row.net_revenue_minor;
+      refunds    += row.refund_total_minor;
+    }
+    return {
+      from:                win.from,
+      to:                  win.to,
+      currency:            currency,
+      order_count:         orderCount,
+      gross_revenue_minor: gross,
+      net_revenue_minor:   net,
+      refund_total_minor:  refunds,
+      aov_minor:           (aov && aov.aov_minor) || 0,
+      refund_rate_bps:     (refund && refund.refund_rate_bps) || 0,
+      by_day:              byDay,
+      by_status:           funnel,
+      top_products:        (top && top.rows) || [],
+    };
+  }
+
+  // CSV body for the by-day revenue series. Composes `b.csv.stringify`
+  // (RFC 4180) — the cell values are integer aggregates + ISO date buckets
+  // + 3-letter currency codes, all framework-internal (never raw
+  // operator/customer prose), so the RFC-4180 quoting is sufficient here;
+  // there is no untrusted free-text column that would require b.guardCsv's
+  // formula-injection defenses.
+  function _reportCsv(report) {
+    var rows = report.by_day.map(function (r) {
+      return {
+        date:                r.bucket_start,
+        currency:            r.currency,
+        order_count:         r.order_count,
+        gross_revenue_minor: r.gross_revenue_minor,
+        net_revenue_minor:   r.net_revenue_minor,
+        refund_total_minor:  r.refund_total_minor,
+      };
+    });
+    return b.csv.stringify(rows, {
+      columns: ["date", "currency", "order_count", "gross_revenue_minor", "net_revenue_minor", "refund_total_minor"],
+      header:  true,
+      eol:     "\n",
+    });
+  }
+
+  router.get("/admin/reports", _pageOrApi(true,
+    R(async function (req, res) {
+      if (!salesReports) return _problem(res, 503, "reporting-unconfigured", "the salesReports primitive is not wired");
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      // A malformed from/to surfaces as a 400 problem (config/entry tier).
+      var win;
+      try { win = _reportWindow(url); }
+      catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+      var report;
+      try { report = await _buildReport(win); }
+      catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+      if (url && url.searchParams.get("format") === "csv") {
+        res.status(200);
+        if (res.setHeader) {
+          res.setHeader("content-type", "text/csv; charset=utf-8");
+          res.setHeader("content-disposition", "attachment; filename=\"sales-report.csv\"");
+        }
+        var csv = _reportCsv(report);
+        if (res.end) res.end(csv); else res.send(csv);
+        return;
+      }
+      _json(res, 200, report);
+    }),
+    async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      if (!salesReports) {
+        return _sendHtml(res, 200, renderAdminReports({
+          shop_name: deps.shop_name, nav_available: navAvailable, report: null,
+          notice: "Reporting isn't configured on this deployment.",
+        }));
+      }
+      var win, notice = null;
+      try { win = _reportWindow(url); }
+      catch (e) {
+        if (!(e instanceof TypeError)) throw e;
+        // Bad range → re-render with the default window + a correction
+        // notice (config/entry tier: the operator fixes the typo).
+        win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+        notice = e.message.replace(/^admin:\s*/, "");
+      }
+      // CSV download from the browser surface too (a link, not a fetch).
+      if (url && url.searchParams.get("format") === "csv") {
+        var report0;
+        try { report0 = await _buildReport(win); }
+        catch (e2) { if (!(e2 instanceof TypeError)) throw e2; report0 = null; }
+        if (report0) {
+          res.status(200);
+          if (res.setHeader) {
+            res.setHeader("content-type", "text/csv; charset=utf-8");
+            res.setHeader("content-disposition", "attachment; filename=\"sales-report.csv\"");
+          }
+          var csv0 = _reportCsv(report0);
+          if (res.end) res.end(csv0); else res.send(csv0);
+          return;
+        }
+      }
+      var report;
+      try { report = await _buildReport(win); }
+      catch (e3) {
+        if (!(e3 instanceof TypeError)) throw e3;
+        win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+        notice = e3.message.replace(/^salesReports:\s*/, "");
+        report = await _buildReport(win);
+      }
+      _sendHtml(res, 200, renderAdminReports({
+        shop_name: deps.shop_name, nav_available: navAvailable, report: report, notice: notice,
+      }));
+    },
+  ));
+
+  // ---- printable order documents --------------------------------------
+  //
+  // Operator-facing receipt + packing slip for an order. These are the
+  // warehouse/fulfilment paper trail (the customer's own order page is a
+  // separate storefront surface — untouched here). Each renders clean,
+  // self-contained, print-optimized HTML the operator prints or pipes to a
+  // PDF. Mounted only when the corresponding render primitive is wired.
+  //
+  // Failure modes: a malformed order id (TypeError from the primitive's id
+  // reader) → 404; a missing order → 404. Only TypeError is swallowed to a
+  // 404 — any other error propagates to the 500 path.
+
+  // The receipt + packing-slip render primitives emit a self-contained
+  // document driven purely by the order; the shop's own name + contact live
+  // in shop_config, so we read them here and inject a small masthead at the
+  // top of the document `<body>`. Both renderers emit a literal "<body>\n"
+  // marker; the header slots in right after it. When config is unwired or
+  // the keys are unset, the document renders without a masthead (the order
+  // data alone is still a complete, valid document).
+  async function _shopMastheadHtml() {
+    if (!deps.config) return "";
+    var name = null, contact = null;
+    try {
+      name = await deps.config.get("shop.name", deps.shop_name || null);
+      // The setup wizard persists the operator's contact under
+      // "shop.contact_email"; fall back to the conventional
+      // "shop.support_email" key the config module documents.
+      contact = await deps.config.get("shop.contact_email", null);
+      if (contact == null) contact = await deps.config.get("shop.support_email", null);
+    } catch (_e) {
+      // Config read failure must not break the print document — degrade to
+      // no masthead rather than 500-ing the operator's print job.
+      return "";
+    }
+    if (!name && !contact) return "";
+    var parts = "";
+    if (name)    parts += "<strong>" + _htmlEscape(String(name)) + "</strong>";
+    if (contact) parts += (name ? "<br>" : "") + _htmlEscape(String(contact));
+    // Inline style is acceptable here: this document is served standalone
+    // (not under the admin console's strict style-src CSP) and is built for
+    // printing, where an external stylesheet round-trip is undesirable.
+    return "<div style=\"margin-bottom:8mm;font-size:11pt;\">" + parts + "</div>\n";
+  }
+
+  function _injectMasthead(html, masthead) {
+    if (!masthead) return html;
+    var marker = "<body>\n";
+    var at = html.indexOf(marker);
+    if (at === -1) return html;                                  // renderer changed shape — emit the doc unaltered
+    return html.slice(0, at + marker.length) + masthead + html.slice(at + marker.length);
+  }
+
+  if (printReceipts) {
+    router.get("/admin/orders/:id/receipt", async function (req, res) {
+      if (!_htmlAuthed(req, expectedToken)) {
+        if (req.method === "GET" || !req.method) return _sendHtml(res, 200, renderAdminLogin({ shop_name: deps.shop_name }));
+        return _problem(res, 401, "unauthorized");
+      }
+      var html;
+      try {
+        html = await printReceipts.htmlPdf({ order_id: req.params.id });
+      } catch (e) {
+        if (e instanceof TypeError) {
+          return _sendHtml(res, 404, renderAdminOrders({
+            shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
+          }));
+        }
+        return _problem(res, 500, "internal-error", (e && e.message) || String(e));
+      }
+      _sendHtml(res, 200, _injectMasthead(html, await _shopMastheadHtml()));
+    });
+  }
+
+  if (packingSlips) {
+    router.get("/admin/orders/:id/packing-slip", async function (req, res) {
+      if (!_htmlAuthed(req, expectedToken)) {
+        if (req.method === "GET" || !req.method) return _sendHtml(res, 200, renderAdminLogin({ shop_name: deps.shop_name }));
+        return _problem(res, 401, "unauthorized");
+      }
+      var html;
+      try {
+        html = await packingSlips.renderHtml({ order_id: req.params.id });
+      } catch (e) {
+        if (e instanceof TypeError) {
+          return _sendHtml(res, 404, renderAdminOrders({
+            shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
+          }));
+        }
+        return _problem(res, 500, "internal-error", (e && e.message) || String(e));
+      }
+      _sendHtml(res, 200, _injectMasthead(html, await _shopMastheadHtml()));
+    });
+  }
+
   // ---- analytics ------------------------------------------------------
 
   var analytics = deps.analytics || null;
@@ -4505,6 +4797,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "products",     href: "/admin/products",     label: "Products" },
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
+  { key: "reports",      href: "/admin/reports",      label: "Reports" },
   { key: "customers",    href: "/admin/customers",    label: "Customers",    requires: "customers" },
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
@@ -4793,6 +5086,123 @@ function renderAdminOrders(opts) {
   return _renderAdminShell(opts.shop_name, "Orders", body, "orders", opts.nav_available);
 }
 
+// epoch-ms → "YYYY-MM-DD" for a date <input>'s value. Mirrors `_fmtDate`'s
+// guard so a bad value never throws inside the template.
+function _dateInputValue(v) {
+  var n = typeof v === "number" ? v : Date.parse(v);
+  if (!isFinite(n)) return "";
+  return new Date(n).toISOString().slice(0, 10);
+}
+
+// Sales/revenue report screen. Renders the headline totals (orders,
+// gross/net revenue, refunds, AOV, refund rate), the order-status funnel,
+// a by-day revenue table, and the top products — all for the selected
+// date range. A date-range form lets the operator retune the window; a CSV
+// link exports the by-day series. `opts.report` is null when reporting
+// isn't configured (renders the notice only).
+function renderAdminReports(opts) {
+  opts = opts || {};
+  var report = opts.report;
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  if (!report) {
+    var emptyBody = "<section><h2>Reports</h2>" + notice +
+      "<p class=\"empty\">No sales report available.</p></section>";
+    return _renderAdminShell(opts.shop_name, "Reports", emptyBody, "reports", opts.nav_available);
+  }
+
+  var fromVal = _dateInputValue(report.from);
+  // The window's `to` is exclusive (next UTC midnight after the operator's
+  // chosen end day); render the inclusive end day back into the date input
+  // by stepping one day back.
+  var toVal   = _dateInputValue(report.to - b.constants.TIME.days(1));
+
+  // Date-range form (GET so the window lives in the URL — bookmarkable +
+  // shareable). The browser submits calendar-date params; the CSV link
+  // carries the same window as raw epoch-ms.
+  var csvHref = "/admin/reports?format=csv" +
+    "&from=" + encodeURIComponent(String(report.from)) +
+    "&to="   + encodeURIComponent(String(report.to));
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/reports\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\"></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\"></label>" +
+      "<button class=\"btn\" type=\"submit\">Apply</button>" +
+      "<a class=\"btn btn--ghost\" href=\"" + _htmlEscape(csvHref) + "\">Export CSV</a>" +
+    "</form>";
+
+  // Headline stat cards. Money formats through the same pricing helper the
+  // dashboard + order pages use, in the report's headline currency.
+  var cur = report.currency;
+  var statsBlock =
+    "<section><h2>Summary</h2><div class=\"stat-grid\">" +
+      _statCard("Orders", String(report.order_count)) +
+      _statCard("Gross revenue", pricing.format(report.gross_revenue_minor, cur)) +
+      _statCard("Net revenue", pricing.format(report.net_revenue_minor, cur)) +
+      _statCard("Refunds", pricing.format(report.refund_total_minor, cur)) +
+      _statCard("Avg order value", pricing.format(report.aov_minor, cur)) +
+      _statCard("Refund rate", (report.refund_rate_bps / 100).toFixed(2) + "%") +
+    "</div></section>";
+
+  // Order-status funnel — each milestone counts orders that reached at
+  // least that stage within the window.
+  var f = report.by_status || {};
+  var funnelRows = [
+    ["Checkout started", f.checkout_started],
+    ["Payment intent created", f.payment_intent_created],
+    ["Paid", f.paid],
+    ["Fulfilled", f.fulfilled],
+    ["Refunded", f.refunded],
+  ].map(function (pair) {
+    return "<tr><td>" + _htmlEscape(pair[0]) + "</td><td class=\"num\">" + _htmlEscape(String(pair[1] == null ? 0 : pair[1])) + "</td></tr>";
+  }).join("");
+  var funnelBlock =
+    "<section><h2>Order status</h2><div class=\"panel\">" +
+      "<table><thead><tr><th scope=\"col\">Stage</th><th scope=\"col\" class=\"num\">Orders</th></tr></thead><tbody>" + funnelRows + "</tbody></table>" +
+    "</div></section>";
+
+  // Top products by gross revenue across the window.
+  var top = report.top_products || [];
+  var topRows = top.length
+    ? top.map(function (r) {
+        return "<tr><td>" + _htmlEscape(r.sku) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.units_sold)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(pricing.format(r.gross_revenue_minor, r.currency)) + "</td></tr>";
+      }).join("")
+    : "<tr><td colspan=\"3\" class=\"empty\">No sales in this window.</td></tr>";
+  var topBlock =
+    "<section><h2>Top products</h2><div class=\"panel\">" +
+      "<table><thead><tr><th scope=\"col\">SKU</th><th scope=\"col\" class=\"num\">Units</th><th scope=\"col\" class=\"num\">Revenue</th></tr></thead><tbody>" + topRows + "</tbody></table>" +
+    "</div></section>";
+
+  // By-day revenue series — one row per (day, currency) bucket.
+  var byDay = report.by_day || [];
+  var dayRows = byDay.length
+    ? byDay.map(function (r) {
+        return "<tr>" +
+          "<td>" + _htmlEscape(r.bucket_start) + "</td>" +
+          "<td>" + _htmlEscape(r.currency) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.order_count)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(pricing.format(r.gross_revenue_minor, r.currency)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(pricing.format(r.net_revenue_minor, r.currency)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(pricing.format(r.refund_total_minor, r.currency)) + "</td>" +
+          "</tr>";
+      }).join("")
+    : "<tr><td colspan=\"6\" class=\"empty\">No sales in this window.</td></tr>";
+  var dayBlock =
+    "<section><h2>By day</h2><div class=\"panel\">" +
+      "<table><thead><tr><th scope=\"col\">Date</th><th scope=\"col\">Currency</th><th scope=\"col\" class=\"num\">Orders</th><th scope=\"col\" class=\"num\">Gross</th><th scope=\"col\" class=\"num\">Net</th><th scope=\"col\" class=\"num\">Refunds</th></tr></thead><tbody>" + dayRows + "</tbody></table>" +
+    "</div></section>";
+
+  var body =
+    "<section><h2>Reports</h2>" + notice +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(report.from)) + " → " + _htmlEscape(_fmtDate(report.to)) + "</p>" +
+      rangeForm +
+    "</section>" +
+    statsBlock + funnelBlock + topBlock + dayBlock;
+  return _renderAdminShell(opts.shop_name, "Reports", body, "reports", opts.nav_available);
+}
+
 function renderAdminOrder(opts) {
   opts = opts || {};
   var o = opts.order;
@@ -4854,6 +5264,22 @@ function renderAdminOrder(opts) {
   }).filter(Boolean).join(" ");
   var actions = actionForms || "<span class=\"meta\">This order is in a final state — no further changes.</span>";
 
+  // Printable operator documents — a receipt + a packing slip, each opening
+  // the print-optimized HTML in a new tab. Rendered only when the matching
+  // render primitive is wired (the routes mount only then).
+  var docLinks = [];
+  if (opts.can_receipt) {
+    docLinks.push("<a class=\"btn btn--ghost\" href=\"/admin/orders/" + _htmlEscape(o.id) + "/receipt\" target=\"_blank\" rel=\"noopener\">Print receipt</a>");
+  }
+  if (opts.can_packing_slip) {
+    docLinks.push("<a class=\"btn btn--ghost\" href=\"/admin/orders/" + _htmlEscape(o.id) + "/packing-slip\" target=\"_blank\" rel=\"noopener\">Print packing slip</a>");
+  }
+  var documentsPanel = docLinks.length
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Documents</h3>" +
+        "<div class=\"order-actions\">" + docLinks.join(" ") + "</div>" +
+      "</div>"
+    : "";
+
   // Shipment + tracking panel. Renders only when the tracking primitive is
   // wired (`can_track`). For each existing shipment: the carrier, status,
   // tracking number (linked to the carrier's public URL when known), and
@@ -4938,6 +5364,7 @@ function renderAdminOrder(opts) {
       "<div class=\"panel mt\"><h3 class=\"subhead\">Actions</h3>" +
         "<div class=\"order-actions\">" + actions + "</div>" +
       "</div>" +
+      documentsPanel +
       trackingPanel +
     "</section>";
   return _renderAdminShell(opts.shop_name, "Order " + o.id.slice(0, 8), body, "orders", opts.nav_available);

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.2.27",
+  "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.27",
+  "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": {