@blamejs/blamejs-shop 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.2.x
 
+- v0.2.12 (2026-05-28) — **Truthful product availability and real SEO metadata — canonical URLs, structured data, and per-page descriptions.** Two related improvements to the storefront's honesty and discoverability. Product pages now report real availability from inventory (instead of a hardcoded 'In stock') and reflect it in their structured data, and the shipping line is suppressed for digital products. Separately, every page now emits a canonical URL and a populated Open Graph URL (previously empty — which broke social-share unfurls and let sort/currency query parameters fork into duplicate indexed pages), the home page emits the same Organization/Website structured data the edge already did, breadcrumb structured data uses absolute URLs, and the home, category, and search pages get their own meta descriptions instead of one shared default. The footer's account links are regrouped and a shipping-and-returns link was added. **Changed:** *Product availability is truthful* — The product page's stock badge and its `Product`/`AggregateOffer` structured-data `availability` are now driven by real per-SKU inventory (`InStock` / `OutOfStock`) rather than a hardcoded value, so a sold-out item reads as sold out everywhere and structured data no longer mismatches reality. The shipping-time line is suppressed for all-digital products (shown as delivered on purchase). Identical across the edge and container render paths. · *Footer account links regrouped* — The footer's operator-oriented column is now a customer 'Your account' grouping (Account / Orders / Contact), the public Admin link was removed, and a 'Shipping & returns' link was added to the policy area. · *Form fields are legible on the dark theme* — Text inputs, selects, and textareas (checkout, address book, search, sign-in) previously rendered with a 10%-opacity hairline that disappeared against the near-black canvas — fields read as empty voids. They now have a clearly-bounded outline and a lifted fill, stretch to fill their column, and the rule covers `tel`/`url`/`password` inputs it previously missed. **Fixed:** *Canonical + Open Graph URLs on every page* — Every page now includes `<link rel="canonical">` and a populated `og:url` (both were absent/empty before). This fixes social-share previews that unfurled with no link target and prevents tracking/sort/currency query-string variants from being indexed as duplicate pages. Emitted on both render paths, derived from the request's own origin. · *Consistent structured data + unique page descriptions* — The home page now emits the `Organization` and `WebSite` (search-action) structured data that previously only appeared on the edge render, breadcrumb structured-data item URLs are absolute (so the breadcrumb rich result is eligible), and the home, category, and search pages each carry their own meta/OG description instead of sharing one generic string.
+
+- v0.2.11 (2026-05-27) — **A clearer checkout — itemised order summary, honest pricing, and recoverable errors.** Reworks the checkout and cart experience. Checkout now uses the same two-column layout as the cart, with a sticky order-summary rail that lists the actual items being bought (thumbnail, title, quantity, line total) rather than a bare number in a lonely column. The summary no longer shows a misleading 'Total' equal to the subtotal — it shows the subtotal plus an honest note that tax and shipping are calculated at the payment step, matching the cart. Adding an item now confirms it and offers to keep shopping, checkout and cart failures render as proper pages you can recover from instead of a blank error string, required fields announce themselves to screen readers, and the header 'Framework' link works from every page. **Changed:** *Checkout shows an itemised, sticky order summary* — The checkout page adopts the cart's two-column layout: the shipping form on the left and a sticky order summary on the right that lists each item (thumbnail, title, quantity, line total) with an 'Edit cart' link back to the cart. Previously the form was a narrow column with a bare subtotal box and no way back. · *Honest checkout pricing* — The order summary no longer renders a 'Total (plus tax + shipping)' line bound to the subtotal value (which read as the final price but wasn't). It now shows the subtotal and the same honest note the cart uses — tax and shipping are calculated at the payment step. · *Add-to-cart confirmation + continue shopping* — Adding an item lands on the cart with a dismissible 'Added to cart' confirmation, and the cart now has a 'Continue shopping' link so multi-item shoppers aren't dead-ended. **Fixed:** *Checkout and cart errors are recoverable, not blank pages* — A declined gift card, an invalid input, or a checkout failure previously dumped an unstyled plain-text error. These now render as styled pages with the reason and a way back — gift-card and loyalty errors re-display the checkout form with the message inline so the shopper can correct it without losing their place. · *Required fields announce to screen readers* — Required form fields kept only a red asterisk (color-only); they now include a visually-hidden '(required)' so assistive technology conveys it. · *Header 'Framework' link works on every page* — It pointed at an on-page anchor that only existed on the home page (a no-op elsewhere); it now resolves from any page.
+
 - v0.2.10 (2026-05-27) — **Accessibility and mobile polish — the cookie bar stops covering the page, and forms behave on phones.** A round of default-theme refinements focused on the cookie consent bar, mobile ergonomics, and accessibility. The consent bar previously floated over page content — on a product page or checkout it could sit on top of the price, variant picker, and the add-to-cart / continue-to-payment button on a first visit. It is now a compact bottom bar that reserves its own space (so nothing important is ever hidden under it), scrolls within itself if the text is long, and receives keyboard focus when it appears. Alongside it: mobile form inputs no longer trigger iOS zoom-on-focus, the header touch targets meet the 44px minimum, inline text links are underlined, and a consistency pass tightened button shapes, table-label typography, and small-screen layout. **Changed:** *Visual consistency pass* — Action buttons share a single corner radius (primary and secondary no longer differ in shape), uppercase micro-labels use the monospace face consistently across tables and forms, the catalog grid shows two columns on small phones instead of one, the hero stat row breathes on narrow screens, and a few dark-theme borders/placeholders that read muddy were moved onto the semantic token palette. **Fixed:** *Cookie consent bar no longer covers page content* — On a first visit the consent bar could overlap the product buy box and the checkout form (the price, variant selector, and primary button). It is now a compact bottom-docked bar that reserves matching space at the foot of the page until a choice is made, caps its height and scrolls internally for long text, and moves keyboard focus to its first control when shown — so the page's primary action is never hidden and the bar is reachable without tabbing the whole page. · *Mobile form inputs no longer zoom on iOS* — Text inputs, selects, and textareas render at a 16px minimum on touch devices, so mobile Safari no longer zooms the viewport when a field is focused (which previously left the page zoomed-in and pannable mid-checkout). · *Header touch targets meet the 44px minimum on mobile* — The account and cart controls in the header — the two primary controls on a phone — are now at least 44×44px. · *Clearer link and prompt-glyph affordances* — Inline text links in body copy are underlined (no longer distinguished by color alone), and the terminal prompt glyph on the dark accent bands renders in full contrast.
 
 - v0.2.9 (2026-05-27) — **Storefront read pages stay fast for every visitor — the cart badge updates client-side.** Restores full edge-render speed for returning and signed-in shoppers. Every storefront read page (home, product listing, search, blog) now renders at the edge for all visitors again; the nav cart badge renders server-side and a tiny client island corrects the number from a new lightweight endpoint. The result: the fast cached page AND an accurate cart count, without sending a shopper-with-a-cart through the slower origin on every page. **Added:** *`GET /cart/count` + a cart-count island* — A new endpoint returns the current session's cart line count as JSON (`{"count": N}`), cached `no-store`, with no product hydration. A small deferred same-origin script (`assets/js/cart-count.js`) reads it on load and updates the nav badge text and its aria-label. A visitor with JavaScript off keeps the server-rendered badge. The script is a same-origin external file, so the existing `script-src 'self'` policy already permits it — no CSP change required. **Fixed:** *Fast read pages for shoppers who have a session* — A visitor carrying a cart or sign-in cookie is once again served the edge-rendered storefront pages instead of being routed to the origin container, so the home page and other read pages load quickly for returning visitors, not just first-time guests. The nav cart count stays correct via the island below.

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.2.10",
+  "version": "0.2.12",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-FgqvXcZygYkJjjOtXAeu9xi6AtYqkchPnJKcS0OeHm8lynhd9r4RfdpoT7P7j7/l",
       "fingerprinted": "css/admin.afd7b964c1f6fe1b.css"
     },
     "css/main.css": {
-      "integrity": "sha384-989Th+84GsswrtPWc4g7DImIYKE/nUSgpZcQMeYxhPN1tg3lrgBhjQNKHNqwz7kb",
-      "fingerprinted": "css/main.4504ec0c542c3225.css"
+      "integrity": "sha384-4n7LcnY4MZQmhe0dlnwm50HaOyzJ0QMqtb7b70N9qO20B4LJ858lMOxXuua7aFYz",
+      "fingerprinted": "css/main.666c51fd74364739.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/storefront.js

@@ -145,6 +145,7 @@ var LAYOUT =
   "  <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n" +
   "  <title>{{title}} — {{shop_name}}</title>\n" +
   "  <meta name=\"description\" content=\"{{og_description}}\">\n" +
+  "  <link rel=\"canonical\" href=\"{{canonical_url}}\">\n" +
   "  <link rel=\"icon\" type=\"image/svg+xml\" href=\"/assets/brand/favicon.svg\">\n" +
   "  <link rel=\"icon\" type=\"image/png\" href=\"/assets/brand/favicon.png\">\n" +
   "  <link rel=\"apple-touch-icon\" href=\"/assets/brand/favicon.png\">\n" +
@@ -186,7 +187,7 @@ var LAYOUT =
   "      </form>\n" +
   "      <nav class=\"site-nav\" aria-label=\"Primary\">\n" +
   "        <a class=\"site-nav__link\" href=\"/\">{{nav_shop}}</a>\n" +
-  "        <a class=\"site-nav__link\" href=\"#framework\">{{nav_framework}}</a>\n" +
+  "        <a class=\"site-nav__link\" href=\"/#framework\">{{nav_framework}}</a>\n" +
   "        <a class=\"site-nav__icon\" href=\"/account\" aria-label=\"{{nav_account}}\"><svg viewBox=\"0 0 24 24\" width=\"20\" height=\"20\" aria-hidden=\"true\"><path d=\"M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm-7 9a7 7 0 0 1 14 0\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.75\" stroke-linecap=\"round\"/></svg></a>\n" +
   "        <a class=\"cart-pill\" href=\"/cart\" aria-label=\"{{nav_cart_aria}}\"><svg viewBox=\"0 0 24 24\" width=\"18\" height=\"18\" aria-hidden=\"true\"><path d=\"M3 4h2l2.4 12.1a2 2 0 0 0 2 1.6h7.6a2 2 0 0 0 1.95-1.55L21 8H6\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.75\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><circle cx=\"10\" cy=\"21\" r=\"1.4\" fill=\"currentColor\"/><circle cx=\"17\" cy=\"21\" r=\"1.4\" fill=\"currentColor\"/></svg><span class=\"cart-pill__count\">{{cart_count}}</span></a>\n" +
   "      </nav>\n" +
@@ -231,6 +232,7 @@ var LAYOUT =
   "          <li><a href=\"/?sort=sale\">{{footer_shop_sale}}</a></li>\n" +
   "          <li><a href=\"/compare\">{{footer_shop_compare}}</a></li>\n" +
   "          <li><a href=\"/cart\">{{footer_shop_cart}}</a></li>\n" +
+  "          <li><a href=\"/terms\">{{footer_shop_shipping}}</a></li>\n" +
   "        </ul>\n" +
   "      </div>\n" +
   "      <div class=\"site-footer__col\">\n" +
@@ -247,7 +249,6 @@ var LAYOUT =
   "        <ul>\n" +
   "          <li><a href=\"/account\">{{footer_operators_account}}</a></li>\n" +
   "          <li><a href=\"/orders\">{{footer_operators_orders}}</a></li>\n" +
-  "          <li><a href=\"/admin\">{{footer_operators_admin}}</a></li>\n" +
   "          <li><a href=\"mailto:hello@blamejs.shop\">{{footer_operators_contact}}</a></li>\n" +
   "        </ul>\n" +
   "      </div>\n" +
@@ -530,6 +531,37 @@ var _DEFAULT_LOCALE_CTX = {
   switcher_html: "",
 };
 
+// Derive the absolute canonical + og:url for a request. Origin comes from
+// the `Host` header the same way robots.txt/sitemap.xml resolve it (https
+// is the only scheme the storefront serves on); the path is the request
+// path. `canonical_url` strips the query (the canonical names the page,
+// not a filtered/sorted view); `og_url` keeps the full URL so a share of
+// a filtered listing unfurls to that exact view. A request with no Host
+// header yields empty strings — the renderer then omits the absolute URLs
+// rather than emit a host-less one. Defensive request-shape reader:
+// returns defaults on any malformed input.
+function _requestUrls(req) {
+  var host = (req && req.headers && (req.headers.host || req.headers.Host)) || "";
+  if (!host) return { canonical_url: "", og_url: "" };
+  var origin = "https://" + host;
+  var rawUrl = (req && typeof req.url === "string" && req.url.length) ? req.url : "/";
+  // req.url may be path-only ("/products/x?y=1") or absolute; normalise
+  // through URL with the derived origin as the base so either shape works.
+  var path = "/";
+  var search = "";
+  try {
+    var parsed = new URL(rawUrl, origin);
+    path = parsed.pathname || "/";
+    search = parsed.search || "";
+  } catch (_e) {
+    var qIdx = rawUrl.indexOf("?");
+    path = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
+    search = qIdx === -1 ? "" : rawUrl.slice(qIdx);
+    if (path.charCodeAt(0) !== 47 /* "/" */) path = "/";
+  }
+  return { canonical_url: origin + path, og_url: origin + path + search };
+}
+
 function _wrap(opts) {
   var themeCss = (opts && typeof opts.theme_css === "string" && opts.theme_css.length)
     ? opts.theme_css
@@ -547,7 +579,14 @@ function _wrap(opts) {
   var ogTitle       = opts.og_title       || (opts.title ? opts.title + " — " + shopName : shopName);
   var ogDescription = opts.og_description || "Open-source ecommerce framework built on blamejs. Server-rendered HTML, post-quantum crypto, zero npm runtime dependencies.";
   var ogImage       = opts.og_image       || "/assets/brand/logo.png";
-  var ogUrl         = opts.og_url         || "";
+  // Absolute request URL drives both `og:url` (full URL incl. query) and
+  // the canonical link (query stripped — the canonical names the page,
+  // not the filtered/sorted view). Renderers thread `opts.canonical_url`
+  // + `opts.og_url` (built by `_requestUrls` in the route handler); absent
+  // them (a unit test calling the renderer directly), both stay empty
+  // rather than emit a bogus host-less URL.
+  var canonicalUrl = opts.canonical_url || "";
+  var ogUrl         = opts.og_url       || canonicalUrl;
   // Multi-currency display switcher — populated only when the operator
   // configured >1 display currency (opts.currency_options). The block is
   // empty otherwise, so a single-currency store renders unchanged.
@@ -600,6 +639,7 @@ function _wrap(opts) {
     og_description: ogDescription,
     og_image:       ogImage,
     og_url:         ogUrl,
+    canonical_url:  canonicalUrl,
     lang:           localeCtx.lang || "en",
     dir:            localeCtx.dir  || "ltr",
     nav_cart_aria:  cartAria,
@@ -966,16 +1006,71 @@ function renderHome(opts) {
   // The hero + value band + catalog section give the home page a
   // designed surface even when no products are loaded yet —
   // visitors land on the storefront shell, not a tech demo.
-  var body = hero + catalog;
+  // Organization + WebSite JSON-LD — surfaces the storefront in Google's
+  // knowledge-panel (logo + social) and registers the sitelinks search
+  // box pointing at `/search?q=`. Mirrors the edge renderer
+  // (`worker/render/home.js`) byte-for-byte so the structured data is
+  // identical whichever substrate serves the home page. `_orgWebsiteJsonLd`
+  // resolves the absolute base from the shop name (a bare host or a full
+  // URL both normalise to `https://<host>`).
+  var homeJsonLd = _orgWebsiteJsonLd(shopName);
+  var body = hero + catalog + homeJsonLd;
   return _wrap(Object.assign({
     title:      title,
     shop_name:  shopName,
     cart_count: cartCount,
     theme_css: opts.theme_css,
+    canonical_url: opts.canonical_url,
+    og_url:        opts.og_url,
+    og_description: "Shop the blamejs.shop catalog — an open-source, server-rendered storefront with post-quantum crypto and zero npm runtime dependencies.",
     body:       body,
   }, _currencyWrapOpts(opts)));
 }
 
+// Absolute origin (scheme + host, no trailing slash) for building
+// fully-qualified structured-data URLs. Prefers the request-derived
+// canonical URL's origin (matches the host the visitor reached); falls
+// back to the shop-name host when the renderer is called without one (a
+// unit test, or a theme path). A bare host shop name and a full `https://`
+// value both normalise to `https://<host>`.
+function _absoluteBase(canonicalUrl, shopName) {
+  if (typeof canonicalUrl === "string" && canonicalUrl.length) {
+    try {
+      var parsed = new URL(canonicalUrl);
+      return parsed.origin;
+    } catch (_e) { /* fall through to the shop-name base */ }
+  }
+  return "https://" + String(shopName || "blamejs.shop").replace(/^https?:\/\//, "");
+}
+
+// Schema.org Organization + WebSite JSON-LD for the home page. Shared by
+// the container `renderHome` and mirrored by the edge
+// `worker/render/home.js` — keep the two byte-identical. The base URL is
+// derived from the shop name (operators set SHOP_NAME to their host); a
+// bare host and a full `https://` value both normalise to `https://<host>`.
+function _orgWebsiteJsonLd(shopName) {
+  var base = "https://" + String(shopName).replace(/^https?:\/\//, "");
+  return _jsonLdScript({
+    "@context": "https://schema.org",
+    "@type":    "Organization",
+    "name":     shopName,
+    "url":      base,
+    "logo":     base + "/assets/brand/logo.png",
+    "sameAs":   ["https://github.com/blamejs/blamejs.shop"],
+  }) +
+  _jsonLdScript({
+    "@context": "https://schema.org",
+    "@type":    "WebSite",
+    "name":     shopName,
+    "url":      base,
+    "potentialAction": {
+      "@type":       "SearchAction",
+      "target":      base + "/search?q={search_term_string}",
+      "query-input": "required name=search_term_string",
+    },
+  });
+}
+
 // ---- search results -----------------------------------------------------
 
 var SEARCH_HEADER =
@@ -1218,12 +1313,20 @@ function renderSearch(opts) {
   } else {
     body = header + correctionHtml + chipsHtml + resultsInner;
   }
+  var searchShopName = opts.shop_name || "blamejs.shop";
+  // Per-page meta description — mirrors the edge renderer.
+  var searchMetaDescription = qTrim.length > 0
+    ? ("Results for “" + qTrim + "” in the " + searchShopName + " catalog.")
+    : ("Search the " + searchShopName + " catalog by title, SKU, or description.");
   return _wrap(Object.assign({
     title:      "Search",
-    shop_name:  opts.shop_name || "blamejs.shop",
+    shop_name:  searchShopName,
     cart_count: opts.cart_count,
     search_q:   opts.q,
     theme_css: opts.theme_css,
+    og_description: searchMetaDescription,
+    canonical_url: opts.canonical_url,
+    og_url:        opts.og_url,
     body:       body,
   }, _currencyWrapOpts(opts)));
 }
@@ -1335,6 +1438,78 @@ function _buildBuyBox(variants, escAttr) {
          "      " + trustLine;
 }
 
+// Resolve a product's availability + shipping shape from the variant
+// list + (optional) inventory map the route loads. `in_stock` is true if
+// ANY variant is buyable; a SKU with no inventory row counts as available
+// (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.
+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;
+  for (var i = 0; i < variants.length; i += 1) {
+    var v = variants[i] || {};
+    // requires_shipping defaults to physical (true) unless the column is
+    // explicitly 0/false — matches the catalog default for tangible goods.
+    if (v.requires_shipping === undefined || v.requires_shipping === null ||
+        Number(v.requires_shipping) !== 0) {
+      requiresShipping = true;
+    }
+    if (inv && Object.prototype.hasOwnProperty.call(inv, v.sku)) {
+      anyTracked = true;
+      var row = inv[v.sku];
+      var available = row ? (Number(row.stock_on_hand) - Number(row.stock_held)) : 0;
+      if (available > 0) anyInStock = true;
+    }
+  }
+  return {
+    // No tracked variant → the operator hasn't opted into stock tracking,
+    // so the product reads as in stock (never-block stance).
+    in_stock:          anyTracked ? anyInStock : true,
+    requires_shipping: variants.length === 0 ? true : requiresShipping,
+  };
+}
+
+// PDP availability badges, driven by the resolved availability shape so
+// the displayed state matches the JSON-LD `availability`. Mirrored byte-
+// 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>";
+  // 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
+    ? "<span class=\"pdp__badge\">Ships in 1–2 business days</span>"
+    : "<span class=\"pdp__badge\">Digital — delivered on purchase</span>";
+  return "<div class=\"pdp__meta\">\n" +
+         "        " + stockBadge + "\n" +
+         "        " + shipBadge + "\n" +
+         "        <span class=\"pdp__badge\">Stripe-secured checkout</span>\n" +
+         "      </div>";
+}
+
+// Short shipping/returns line under the buy box pointing shoppers at the
+// public policy page. Physical goods get a shipping-and-returns line; a
+// digital-only product drops the shipping half (no parcel to return).
+// Mirrored byte-for-byte by worker/render/product.js#_pdpShippingNote.
+function _pdpShippingNote(availability) {
+  var a = availability || { in_stock: true, requires_shipping: true };
+  var copy = a.requires_shipping
+    ? "Free returns within 30 days. "
+    : "";
+  return "<p class=\"pdp__shipping-note\">" + copy +
+         "See our <a href=\"/terms\">shipping &amp; returns policy</a>.</p>";
+}
+
 var PRODUCT_PAGE =
   "<section class=\"pdp\">\n" +
   "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
@@ -1349,12 +1524,9 @@ var PRODUCT_PAGE =
   "      <p class=\"eyebrow\">Catalog product</p>\n" +
   "      <h1 class=\"pdp__title\">{{title}}</h1>\n" +
   "      <p class=\"pdp__description\">{{description}}</p>\n" +
-  "      <div class=\"pdp__meta\">\n" +
-  "        <span class=\"pdp__badge pdp__badge--ok\"><span class=\"dot dot--live\" aria-hidden=\"true\"></span> In stock</span>\n" +
-  "        <span class=\"pdp__badge\">Ships in 1–2 business days</span>\n" +
-  "        <span class=\"pdp__badge\">Stripe-secured checkout</span>\n" +
-  "      </div>\n" +
+  "      RAW_AVAILABILITY_PLACEHOLDER\n" +
   "      RAW_BUYBOX_PLACEHOLDER\n" +
+  "      RAW_SHIPPING_NOTE_PLACEHOLDER\n" +
   "      RAW_QTYBREAK_PLACEHOLDER\n" +
   "      RAW_WISHLIST_PLACEHOLDER\n" +
   "      RAW_COMPARE_PLACEHOLDER\n" +
@@ -2150,7 +2322,9 @@ function _addrField(name, labelText, value, opts) {
   if (opts.maxlength) attrs += " maxlength=\"" + opts.maxlength + "\"";
   if (opts.pattern) attrs += " pattern=\"" + esc(opts.pattern) + "\"";
   if (opts.autocomplete) attrs += " autocomplete=\"" + esc(opts.autocomplete) + "\"";
-  var req = opts.required ? " <span class=\"form-field__req\" aria-hidden=\"true\">*</span>" : "";
+  // The `*` is a color-only visual cue; pair it with a visually-hidden
+  // "(required)" so a screen reader announces the field's requiredness.
+  var req = opts.required ? " <span class=\"form-field__req\" aria-hidden=\"true\">*</span><span class=\"sr-only\">(required)</span>" : "";
   return "<label class=\"form-field\">" +
            "<span class=\"form-field__label\">" + esc(labelText) + req + "</span>" +
            "<input type=\"text\" name=\"" + esc(name) + "\" value=\"" + esc(value == null ? "" : String(value)) + "\"" + attrs + ">" +
@@ -2396,7 +2570,10 @@ function renderCategoryIndex(opts) {
     "</section>";
   return _wrap({
     title: "Categories", shop_name: opts.shop_name || "blamejs.shop",
-    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css, body: body,
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css,
+    og_description: "Browse every product category in the " + (opts.shop_name || "blamejs.shop") + " catalog.",
+    canonical_url: opts.canonical_url, og_url: opts.og_url,
+    body: body,
   });
 }
 
@@ -2461,9 +2638,17 @@ function renderCategory(opts) {
       hero +
       grid +
     "</section>";
+  // Per-page meta description: the category's own description when set,
+  // otherwise a "Shop {category}…" pitch.
+  var catMetaDescription = (cat.description && String(cat.description).trim().length)
+    ? String(cat.description)
+    : ("Shop " + cat.title + " at " + (opts.shop_name || "blamejs.shop") + ".");
   return _wrap({
     title: cat.title, shop_name: opts.shop_name || "blamejs.shop",
-    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css, body: body,
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css,
+    og_description: catMetaDescription,
+    canonical_url: opts.canonical_url, og_url: opts.og_url,
+    body: body,
   });
 }
 
@@ -3216,7 +3401,15 @@ function renderProduct(opts) {
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
+  // Truthful availability + shipping shape — drives the on-page badges
+  // AND the JSON-LD `availability` from the same resolved values so the
+  // two never disagree. `opts.inventory` is the per-SKU map the route
+  // 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 availabilityHtml = _buildAvailability(availability);
+  var shippingNoteHtml = _pdpShippingNote(availability);
   var galleryHtml = _buildPdpGallery(opts.product, opts.media || [], opts.asset_prefix || "/assets/");
   var reviewsHtml = _buildReviews(opts.review_summary, opts.reviews, opts.review_cta);
   var qaHtml = _buildProductQa(opts.qa_questions, opts.qa_cta);
@@ -3229,7 +3422,9 @@ function renderProduct(opts) {
     description:  description,
   })
     .replace("RAW_GALLERY_PLACEHOLDER", galleryHtml)
+    .replace("RAW_AVAILABILITY_PLACEHOLDER", availabilityHtml)
     .replace("RAW_BUYBOX_PLACEHOLDER", buyboxHtml)
+    .replace("RAW_SHIPPING_NOTE_PLACEHOLDER", shippingNoteHtml)
     .replace("RAW_QTYBREAK_PLACEHOLDER", qtyBreaksHtml)
     .replace("RAW_WISHLIST_PLACEHOLDER", wishlistHtml)
     .replace("RAW_COMPARE_PLACEHOLDER", compareHtml)
@@ -3241,6 +3436,11 @@ function renderProduct(opts) {
   // the default shop-level description + brand logo.
   var heroMedia = (opts.media && opts.media[0]) || null;
   var ogImage   = heroMedia ? ((opts.asset_prefix || "/assets/") + heroMedia.r2_key) : "/assets/brand/logo.png";
+  // Absolute base for the BreadcrumbList `item` URLs — derived from the
+  // PDP's own canonical (origin stripped of the /products/slug path) so
+  // the structured-data trail carries fully-qualified URLs. Falls back to
+  // the shop-name host when the renderer is called without a request URL.
+  var absoluteBase = _absoluteBase(opts.canonical_url, shopName);
 
   // Product + AggregateOffer JSON-LD, with AggregateRating folded in
   // when published reviews exist. Kept byte-compatible with the edge
@@ -3280,7 +3480,9 @@ function renderProduct(opts) {
         "lowPrice":      (lowMinor / divisor).toFixed(divisor === 1 ? 0 : 2),
         "highPrice":     (hiMinor  / divisor).toFixed(divisor === 1 ? 0 : 2),
         "offerCount":    variants.length,
-        "availability":  "https://schema.org/InStock",
+        "availability":  availability.in_stock
+          ? "https://schema.org/InStock"
+          : "https://schema.org/OutOfStock",
       },
     });
   }
@@ -3288,8 +3490,8 @@ function renderProduct(opts) {
     "@context":        "https://schema.org",
     "@type":           "BreadcrumbList",
     "itemListElement": [
-      { "@type": "ListItem", "position": 1, "name": "Shop", "item": "/" },
-      { "@type": "ListItem", "position": 2, "name": opts.product.title, "item": "/products/" + opts.product.slug },
+      { "@type": "ListItem", "position": 1, "name": "Shop", "item": absoluteBase + "/" },
+      { "@type": "ListItem", "position": 2, "name": opts.product.title, "item": absoluteBase + "/products/" + opts.product.slug },
     ],
   });
   jsonLd = (jsonLd || "") + breadcrumbJsonLd;
@@ -3303,6 +3505,8 @@ function renderProduct(opts) {
     og_title:       opts.product.title + " — " + shopName,
     og_description: description || ("Browse " + opts.product.title + " on " + shopName + "."),
     og_image:       ogImage,
+    canonical_url:  opts.canonical_url,
+    og_url:         opts.og_url,
     body:           body + jsonLd,
   }, _currencyWrapOpts(opts)));
 }
@@ -3382,7 +3586,7 @@ function _checkoutShippingFields(p) {
   var esc = b.template.escapeHtml;
   var email =
     "<label class=\"form-field\">" +
-      "<span class=\"form-field__label\">Email <span class=\"form-field__req\" aria-hidden=\"true\">*</span></span>" +
+      "<span class=\"form-field__label\">Email <span class=\"form-field__req\" aria-hidden=\"true\">*</span><span class=\"sr-only\">(required)</span></span>" +
       "<input type=\"email\" name=\"email\" value=\"" + esc(p.email == null ? "" : String(p.email)) + "\" required autocomplete=\"email\">" +
     "</label>";
   return email +
@@ -3417,6 +3621,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.
 var CHECKOUT_PAGE =
   "<section class=\"checkout-page\">\n" +
   "  <header class=\"section-head\">\n" +
@@ -3424,20 +3634,54 @@ var CHECKOUT_PAGE =
   "    <h1 class=\"section-head__title\">Shipping details</h1>\n" +
   "    <p class=\"section-head__lede\">Enter where the order should ship. Payment runs through Stripe on the next step.</p>\n" +
   "  </header>\n" +
-  "  <form method=\"post\" action=\"/checkout\" class=\"form-stack\">\n" +
-  "    RAW_SHIPPING_FIELDS" +
-  "    <div class=\"form-row\"><label class=\"form-field\"><span class=\"form-field__label\">Gift card code <span class=\"small\">(optional)</span></span><input type=\"text\" name=\"gift_card_code\" autocomplete=\"off\" placeholder=\"XXXX-XXXX-XXXX-XXXX\" maxlength=\"24\"></label></div>\n" +
-  "    <div class=\"checkout-summary\">\n" +
-  "      <h3>Order summary</h3>\n" +
-  "      <dl>\n" +
-  "        <div><dt>Subtotal</dt><dd>{{subtotal}}</dd></div>\n" +
-  "        <div class=\"checkout-summary__total\"><dt>Total <span class=\"small\">(plus tax + shipping)</span></dt><dd>{{subtotal}}</dd></div>\n" +
-  "      </dl>\n" +
+  "  <div class=\"cart-page__grid\">\n" +
+  "    <div class=\"checkout-page__form-col\">\n" +
+  "      <form method=\"post\" action=\"/checkout\" class=\"form-stack\">\n" +
+  "        RAW_INLINE_ERROR" +
+  "        RAW_SHIPPING_FIELDS" +
+  "        <div class=\"form-row\"><label class=\"form-field\"><span class=\"form-field__label\">Gift card code <span class=\"small\">(optional)</span></span><input type=\"text\" name=\"gift_card_code\" autocomplete=\"off\" placeholder=\"XXXX-XXXX-XXXX-XXXX\" maxlength=\"24\"></label></div>\n" +
+  "        <div class=\"form-actions\"><button type=\"submit\" class=\"btn-primary\">Continue to payment <span aria-hidden=\"true\">→</span></button></div>\n" +
+  "      </form>\n" +
   "    </div>\n" +
-  "    <div class=\"form-actions\"><button type=\"submit\" class=\"btn-primary\">Continue to payment <span aria-hidden=\"true\">→</span></button></div>\n" +
-  "  </form>\n" +
+  "    <aside class=\"cart-page__summary\">\n" +
+  "      <div class=\"checkout-page__summary-head\">\n" +
+  "        <h2 class=\"pdp__variants-title\">Order summary</h2>\n" +
+  "        <a href=\"/cart\" class=\"checkout-page__edit-cart\">Edit cart</a>\n" +
+  "      </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" +
+  "      </dl>\n" +
+  "      <p class=\"cart-page__note\">Tax and shipping are calculated on the next step. Payment runs through Stripe.</p>\n" +
+  "    </aside>\n" +
+  "  </div>\n" +
   "</section>\n";
 
+// One order-summary line item in the checkout rail: thumbnail + title +
+// qty + line total, mirroring the cart row but compact. `l` is the raw
+// cart line; `lookup` is the variant_id → { product, hero_media } map the
+// route passes (same shape renderCart uses). Missing lookup entries fall
+// back to the SKU title + a dashed placeholder tile.
+function _checkoutSummaryLine(l, lookup, assetPrefix, fmt) {
+  var esc = b.template.escapeHtml;
+  var match = lookup[l.variant_id] || null;
+  var prod  = match && match.product;
+  var hero  = match && match.hero_media;
+  var title = (prod && prod.title) || l.sku;
+  var lineTotal = fmt(l.line_total_minor || (l.qty * l.unit_amount_minor), l.unit_currency);
+  var thumb = (hero && hero.r2_key)
+    ? "<span class=\"checkout-line__thumb\"><img src=\"" + esc(assetPrefix + hero.r2_key) + "\" alt=\"" + esc(hero.alt_text || title) + "\" loading=\"lazy\"></span>"
+    : "<span class=\"checkout-line__thumb checkout-line__thumb--empty\" aria-hidden=\"true\"></span>";
+  return "<li class=\"checkout-line\">" +
+    thumb +
+    "<span class=\"checkout-line__meta\">" +
+      "<span class=\"checkout-line__title\">" + esc(title) + "</span>" +
+      "<span class=\"checkout-line__qty\">Qty " + esc(String(l.qty)) + "</span>" +
+    "</span>" +
+    "<span class=\"checkout-line__total price\">" + esc(lineTotal) + "</span>" +
+  "</li>";
+}
+
 // Redeem-points-at-checkout field — appended to the checkout form for a
 // signed-in customer with a spendable balance. The customer types how
 // many points to spend; the server caps the credit at the order total
@@ -3465,6 +3709,8 @@ function renderCheckoutForm(opts) {
   var lines  = opts.lines  || [];
   var totals = opts.totals || { subtotal_minor: 0, currency: "USD" };
   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);
   if (opts.theme) {
     return opts.theme.render("checkout", {
@@ -3475,8 +3721,23 @@ function renderCheckoutForm(opts) {
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
+  // Order-summary line items in the sticky rail — same thumbnail + title
+  // pattern as the cart, compact. Formatted in the order's own currency
+  // (the checkout total is computed server-side; no display-currency
+  // conversion happens at this step).
+  var summaryLines = lines.map(function (l) {
+    return _checkoutSummaryLine(l, lookup, assetPrefix, pricing.format);
+  }).join("");
+  // 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 })
-    .replace("RAW_SHIPPING_FIELDS", _checkoutShippingFields(opts.prefill));
+    .replace("RAW_INLINE_ERROR", inlineError)
+    .replace("RAW_SHIPPING_FIELDS", _checkoutShippingFields(opts.prefill))
+    .replace("RAW_SUMMARY_LINES", summaryLines);
   // Signed-in customer with a spendable points balance — surface a
   // redeem-at-checkout field. The block is appended as raw HTML (the
   // balance + value are numbers we control, the conversion ratio is the
@@ -3839,6 +4100,7 @@ var CART_PAGE =
   "      <li aria-current=\"page\">Cart</li>\n" +
   "    </ol>\n" +
   "  </nav>\n" +
+  "RAW_CART_NOTICE" +
   "  <header class=\"section-head\">\n" +
   "    <p class=\"eyebrow\">Your cart</p>\n" +
   "    <h1 class=\"section-head__title\">Review your items</h1>\n" +
@@ -3851,6 +4113,7 @@ var CART_PAGE =
   "          <tbody>{{line_rows}}</tbody>\n" +
   "        </table>\n" +
   "      </div>\n" +
+  "      <a href=\"/\" class=\"btn-ghost cart-page__continue\">← Continue shopping</a>\n" +
   "    </div>\n" +
   "    <aside class=\"cart-page__summary\">\n" +
   "      <h2 class=\"pdp__variants-title\">Order summary</h2>\n" +
@@ -3863,6 +4126,16 @@ var CART_PAGE =
   "  </div>\n" +
   "</section>\n";
 
+// The "added to cart" status banner shown after a POST /cart/lines
+// redirect (`?added=1`). role="status" so a screen reader announces it
+// without stealing focus; the dismiss link drops the query param so a
+// refresh doesn't re-announce. Container-only — the edge serves the
+// cookie-less empty-cart view, never a post-add render.
+var CART_ADDED_NOTICE =
+  "  <p class=\"cart-page__added\" role=\"status\">\n" +
+  "    <span>Added to cart.</span> <a href=\"/cart\">Dismiss</a>\n" +
+  "  </p>\n";
+
 var CART_EMPTY_PAGE =
   "<section class=\"cart-page cart-page--empty\">\n" +
   "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
@@ -3885,6 +4158,40 @@ var CART_EMPTY_PAGE =
   "  </div>\n" +
   "</section>\n";
 
+// Styled, recoverable error page for a cart/checkout dead-end (a bad add,
+// a session that vanished, a non-coded checkout failure). Reuses the
+// cart-empty card so the failure reads as a designed state, not raw text —
+// with the human-readable reason + a recovery link. `opts.reason` is the
+// message, `opts.back_href`/`opts.back_label` the recovery action (default
+// "Back to cart"), and `opts.eyebrow` the kicker (default "Cart").
+function renderCheckoutError(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var shopName  = opts.shop_name || "blamejs.shop";
+  var eyebrow   = opts.eyebrow   || "Cart";
+  var title     = opts.title_text || "Something went wrong";
+  var reason    = opts.reason    || "We couldn't process that request. Your cart is saved — please try again.";
+  var backHref  = opts.back_href  || "/cart";
+  var backLabel = opts.back_label || "Back to cart";
+  var secondary = opts.secondary_href
+    ? " <a href=\"" + esc(opts.secondary_href) + "\" class=\"btn-ghost\">" + esc(opts.secondary_label || "Keep browsing") + "</a>"
+    : " <a href=\"/\" class=\"btn-ghost\">Keep browsing</a>";
+  var body =
+    "<section class=\"cart-page cart-page--empty\"><div class=\"cart-empty\"><div class=\"cart-empty__card\">" +
+      "<p class=\"eyebrow cart-empty__eyebrow\">" + esc(eyebrow) + "</p>" +
+      "<h1 class=\"cart-empty__title\">" + esc(title) + "</h1>" +
+      "<p class=\"cart-empty__lede\">" + esc(reason) + "</p>" +
+      "<div class=\"cart-empty__cta\"><a class=\"btn-primary\" href=\"" + esc(backHref) + "\">" + esc(backLabel) + "</a>" + secondary + "</div>" +
+    "</div></div></section>";
+  return _wrap({
+    title:      opts.title || "Checkout",
+    shop_name:  shopName,
+    theme_css:  opts.theme_css,
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    body:       body,
+  });
+}
+
 function renderCart(opts) {
   if (!opts) throw new TypeError("storefront.renderCart: opts required");
   var lines  = opts.lines  || [];
@@ -3965,11 +4272,15 @@ function renderCart(opts) {
         "      <p class=\"cart-page__note\">Tax and shipping are calculated on the next step. Payment runs through Stripe.</p>\n"
       : "      <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 : "";
     body = _render(CART_PAGE, {
       line_rows: "RAW_LINES",
       subtotal:  subtotal,
       total:     total,
-    }).replace("RAW_LINES", rows).replace("RAW_CHECKOUT_CTA", checkoutCta);
+    }).replace("RAW_LINES", rows).replace("RAW_CHECKOUT_CTA", checkoutCta).replace("RAW_CART_NOTICE", notice);
   }
   return _wrap(Object.assign({
     title:      "Cart",
@@ -5729,7 +6040,7 @@ function mount(router, deps) {
       }));
     }
     var ccy = await _currencyForReq(req);
-    var html = renderHome(Object.assign({ products: products, shop_name: shopName, theme: theme }, ccy));
+    var html = renderHome(Object.assign({ products: products, shop_name: shopName, theme: theme }, _requestUrls(req), ccy));
     _send(res, 200, html);
   });
 
@@ -5860,7 +6171,7 @@ function mount(router, deps) {
       corrected_query: correctedQ,
       shop_name:       shopName,
       cart_count:      cartCount,
-    }, ccy)));
+    }, _requestUrls(req), ccy)));
   });
 
   router.get("/products/:slug", async function (req, res) {
@@ -5870,9 +6181,22 @@ function mount(router, deps) {
     if (!product) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
     var variants = await deps.catalog.variants.listForProduct(product.id);
     var prices = {};
+    // Per-SKU inventory map driving the truthful availability badge +
+    // JSON-LD. Best-effort: a SKU with no inventory row (or a read
+    // failure) is omitted from the map, which the renderer treats as
+    // available — the never-block-on-missing-inventory stance the
+    // cart-hold path already takes. Only populated when the operator has
+    // wired the inventory primitive.
+    var inventory = {};
     for (var i = 0; i < variants.length; i += 1) {
       var p = await deps.catalog.prices.current(variants[i].id, "USD");
       if (p) prices[variants[i].id] = p;
+      if (deps.catalog.inventory && typeof deps.catalog.inventory.get === "function") {
+        try {
+          var invRow = await deps.catalog.inventory.get(variants[i].sku);
+          if (invRow) inventory[variants[i].sku] = invRow;
+        } catch (_e) { /* drop-silent — missing inventory reads as available */ }
+      }
     }
     // Media — first row drives the hero image, the next three feed
     // the thumbnail strip. `listForProduct` is product-level only;
@@ -5959,6 +6283,7 @@ function mount(router, deps) {
       variants:       variants,
       prices:         prices,
       media:          media,
+      inventory:      inventory,
       review_summary: reviewSummary,
       reviews:        reviewRows,
       review_cta:     reviewCta,
@@ -5970,7 +6295,7 @@ function mount(router, deps) {
       shop_name:      shopName,
       cart_count:     cartCount,
       theme:          theme,
-    }, ccy));
+    }, _requestUrls(req), ccy));
     _send(res, 200, html);
   });
 
@@ -6245,9 +6570,9 @@ function mount(router, deps) {
         if (cats[i].active) active.push(cats[i]);
       }
       var cartCount = await _cartCountForReq(req);
-      _send(res, 200, renderCategoryIndex({
+      _send(res, 200, renderCategoryIndex(Object.assign({
         categories: active, shop_name: shopName, cart_count: cartCount, asset_prefix: _cardAssetPrefix,
-      }));
+      }, _requestUrls(req))));
     });
 
     router.get("/categories/:slug", async function (req, res) {
@@ -6277,10 +6602,10 @@ function mount(router, deps) {
         if (children[i].active) activeChildren.push(children[i]);
       }
       var cartCount = await _cartCountForReq(req);
-      _send(res, 200, renderCategory({
+      _send(res, 200, renderCategory(Object.assign({
         category: cat, breadcrumbs: crumbs, children: activeChildren,
         shop_name: shopName, cart_count: cartCount, asset_prefix: _cardAssetPrefix,
-      }));
+      }, _requestUrls(req))));
     });
   }
 
@@ -6302,6 +6627,12 @@ function mount(router, deps) {
   router.get("/cart", async function (req, res) {
     var ccy = await _currencyForReq(req);
     var sid = _readSidCookie(req);
+    // `?added=1` after a POST /cart/lines redirect — drives the
+    // "Added to cart" status banner. Read from the parsed query when the
+    // router populated it, else from the raw URL.
+    var cartUrl = req.url ? new URL(req.url, "http://localhost") : null;
+    var added = (req.query && req.query.added === "1") ||
+      (cartUrl && cartUrl.searchParams.get("added") === "1") || false;
     if (!sid) {
       return _send(res, 200, renderCart(Object.assign({
         lines: [], totals: { subtotal_minor: 0, grand_total_minor: 0, currency: "USD" },
@@ -6346,6 +6677,7 @@ function mount(router, deps) {
       product_lookup:  productLookup,
       can_save:        !!(deps.saveForLater && deps.customers),
       checkout_available: !!(deps.checkout && deps.order),
+      added:           added,
       shop_name:       shopName,
       theme:           theme,
     }, ccy)));
@@ -6387,20 +6719,26 @@ function mount(router, deps) {
   }
 
   if (deps.checkout && deps.order) {
-    router.get("/checkout", async function (req, res) {
-      var sid = _readSidCookie(req);
-      if (!sid) return _send(res, 303, "<a href=\"/cart\">Cart is empty</a>"), res.setHeader && res.setHeader("location", "/cart");
-      var c = await deps.cart.bySession(sid);
-      if (!c) {
-        res.status(303); res.setHeader && res.setHeader("location", "/cart");
-        return res.end ? res.end() : res.send("");
-      }
-      var lines = await deps.cart.listLines(c.id);
-      if (!lines.length) {
-        res.status(303); res.setHeader && res.setHeader("location", "/cart");
-        return res.end ? res.end() : res.send("");
-      }
+    // Build the renderCheckoutForm() opts for an active cart `c`: repriced
+    // lines, totals, the thumbnail lookup, and the signed-in customer's
+    // loyalty balance + prefill. Shared by the GET handler and the POST
+    // 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, {});
+      // variant_id → { product, hero_media } lookup for the summary
+      // thumbnails + titles — same shape (and caching) the cart route uses.
+      var checkoutLookup = {};
+      for (var li = 0; li < lines.length; li += 1) {
+        var lvId = lines[li].variant_id;
+        if (checkoutLookup[lvId]) continue;
+        var lv = await deps.catalog.variants.get(lvId);
+        if (!lv) { checkoutLookup[lvId] = null; continue; }
+        var lprod = await deps.catalog.products.get(lv.product_id);
+        var lmedia = await deps.catalog.media.listForProduct(lv.product_id);
+        checkoutLookup[lvId] = { product: lprod, hero_media: lmedia.length ? lmedia[0] : null };
+      }
       // A signed-in customer drives two best-effort lookups, both keyed
       // off the same auth env: the loyalty balance (for the redeem field)
       // and the default shipping address (to pre-fill the form). Either
@@ -6438,24 +6776,54 @@ function mount(router, deps) {
           }
         } catch (_e) { prefill = null; }
       }
-      _send(res, 200, renderCheckoutForm({
+      return {
         lines: lines, totals: totals, shop_name: shopName, theme: theme,
+        product_lookup: checkoutLookup,
         paypal_client_id: deps.paypal ? deps.paypal_client_id : null,
         loyalty_balance: loyaltyBalance,
         loyalty_points_per_usd: deps.loyalty ? deps.loyalty.REDEMPTION_POINTS_PER_USD : null,
         prefill: prefill,
-      }));
+        inline_error: inlineError || null,
+      };
+    }
+
+    router.get("/checkout", async function (req, res) {
+      var sid = _readSidCookie(req);
+      if (!sid) return _send(res, 303, "<a href=\"/cart\">Cart is empty</a>"), res.setHeader && res.setHeader("location", "/cart");
+      var c = await deps.cart.bySession(sid);
+      if (!c) {
+        res.status(303); res.setHeader && res.setHeader("location", "/cart");
+        return res.end ? res.end() : res.send("");
+      }
+      var rawLines = await deps.cart.listLines(c.id);
+      if (!rawLines.length) {
+        res.status(303); res.setHeader && res.setHeader("location", "/cart");
+        return res.end ? res.end() : res.send("");
+      }
+      // Reprice the lines through the active quantity-break (same as the
+      // cart page) so the summary's per-line totals + subtotal match what
+      // the shopper saw on /cart.
+      var lines = await _repriceCartLines(rawLines);
+      _send(res, 200, renderCheckoutForm(await _checkoutRenderOpts(req, c, lines, null)));
     });
 
     router.post("/checkout", async function (req, res) {
       var body = req.body || {};
       var sid = _readSidCookie(req);
       if (!sid) {
-        res.status(400); return res.end ? res.end("No session") : res.send("No session");
+        return _send(res, 400, renderCheckoutError({
+          shop_name: shopName, theme: theme, eyebrow: "Checkout",
+          title_text: "Your session expired",
+          reason: "We couldn't find an active cart session. Open your cart and continue from there.",
+        }));
       }
       var c = await deps.cart.bySession(sid);
       if (!c) {
-        res.status(400); return res.end ? res.end("No cart") : res.send("No cart");
+        return _send(res, 400, renderCheckoutError({
+          shop_name: shopName, theme: theme, eyebrow: "Checkout",
+          title_text: "Your cart couldn't be found",
+          reason: "We couldn't find an active cart for this session. Open your cart and continue from there.",
+        }));
       }
       // Defensive cart-state guard — if the cart has already been
       // converted (e.g. duplicate-submit on POST refresh), redirect
@@ -6509,10 +6877,33 @@ function mount(router, deps) {
         // GIFTCARD_* code and the loyalty errors a LOYALTY_* code so a
         // fat-fingered value re-prompts rather than 500-ing checkout.
         var code = (e && typeof e.code === "string") ? e.code : "";
-        var clientErr = (e instanceof TypeError) || code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0;
-        res.status(clientErr ? 400 : 500);
         var msg = (e && e.message) || "checkout failed";
-        return res.end ? res.end(msg) : res.send(msg);
+        // A coded gift-card / loyalty error is something the shopper can
+        // fix in place — re-render the checkout form with the message
+        // inline (preserving the cart + their prefilled fields where
+        // possible) rather than dead-ending on a separate page.
+        if (code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0) {
+          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)));
+            }
+          } catch (_re) { /* fall through to the styled error page */ }
+        }
+        // A malformed address shape (TypeError) is still the shopper's to
+        // fix; anything else is a server-side failure. Either way, render a
+        // styled, recoverable page rather than raw text — back to the cart,
+        // or back to the shipping form to re-enter the address.
+        var clientErr = (e instanceof TypeError);
+        return _send(res, clientErr ? 400 : 500, renderCheckoutError({
+          shop_name: shopName, theme: theme, eyebrow: "Checkout",
+          title_text: clientErr ? "We couldn't process your shipping details" : "Checkout didn't go through",
+          reason: clientErr
+            ? "Some shipping details couldn't be read: " + msg + " Go back and check the address fields."
+            : "Something went wrong completing your order. Your cart is saved — please try again. (" + msg + ")",
+          back_href: "/checkout", back_label: "Edit shipping",
+          secondary_href: "/cart", secondary_label: "Back to cart",
+        }));
       }
     });
 
@@ -8510,18 +8901,32 @@ function mount(router, deps) {
     var qtyRaw    = body.qty;
     var qty       = parseInt(qtyRaw, 10);
     if (!variantId || !Number.isFinite(qty) || qty < 1 || qty > 99) {
-      res.status(400);
-      return res.end ? res.end("Invalid request") : res.send("Invalid request");
+      return _send(res, 400, renderCheckoutError({
+        shop_name: shopName, theme: theme,
+        title_text: "We couldn't add that item",
+        reason: "The product or quantity in that request wasn't valid. Pick the item again from its page.",
+        back_href: "/cart", back_label: "Back to cart",
+      }));
     }
     var resolved = await _getOrCreateCart(req, res, "USD");
     try {
       await deps.cart.addLine(resolved.cart.id, { variant_id: variantId, qty: qty });
     } catch (e) {
-      res.status(e instanceof TypeError ? 400 : 500);
-      return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+      var addMsg = (e && e.message) || "Error";
+      return _send(res, e instanceof TypeError ? 400 : 500, renderCheckoutError({
+        shop_name: shopName, theme: theme,
+        title_text: "We couldn't add that item",
+        reason: (e instanceof TypeError)
+          ? "That item couldn't be added: " + addMsg
+          : "Something went wrong adding that item to your cart. Please try again.",
+        back_href: "/cart", back_label: "Back to cart",
+      }));
     }
+    // `?added=1` so the cart page can confirm the item landed (the page
+    // surfaces an "Added to cart" status banner). Still a 303 so a refresh
+    // re-issues the GET, not the POST.
     res.status(303);
-    res.setHeader && res.setHeader("location", "/cart");
+    res.setHeader && res.setHeader("location", "/cart?added=1");
     res.end ? res.end() : res.send("");
   });
 
@@ -8914,8 +9319,12 @@ function mount(router, deps) {
     var hostHeader = req.headers && (req.headers.host || req.headers.Host) || "";
     var origin = hostHeader ? ("https://" + hostHeader) : "";
     var urls = [];
-    urls.push({ loc: origin + "/",      changefreq: "daily",   priority: "1.0" });
-    urls.push({ loc: origin + "/admin", changefreq: "monthly", priority: "0.3" });
+    // The home page + the public legal pages. `/admin` is intentionally
+    // omitted — robots.txt disallows it, so listing it in the sitemap
+    // would contradict the crawl policy.
+    urls.push({ loc: origin + "/",        changefreq: "daily",   priority: "1.0" });
+    urls.push({ loc: origin + "/privacy", changefreq: "yearly",  priority: "0.3" });
+    urls.push({ loc: origin + "/terms",   changefreq: "yearly",  priority: "0.3" });
     try {
       var page = await deps.catalog.products.list({ status: "active", limit: 1000 });
       for (var i = 0; i < page.rows.length; i += 1) {
@@ -8929,6 +9338,38 @@ function mount(router, deps) {
         });
       }
     } catch (_e) { /* drop-silent — catalog unreachable means sitemap drops product rows */ }
+    // Active category browse pages, when the categoryNavigation primitive
+    // is wired. `tree({})` returns the full nested active tree (archived
+    // rows already dropped); we flatten it to one URL per category. Best-
+    // effort — a read failure drops the category rows rather than 500-ing
+    // the sitemap.
+    if (deps.categoryNavigation && typeof deps.categoryNavigation.tree === "function") {
+      try {
+        var catTree = await deps.categoryNavigation.tree({});
+        var stack = Array.isArray(catTree) ? catTree.slice() : [];
+        while (stack.length) {
+          var node = stack.pop();
+          if (node && node.active && node.slug) {
+            urls.push({ loc: origin + "/categories/" + node.slug, changefreq: "weekly", priority: "0.6" });
+          }
+          if (node && Array.isArray(node.children)) {
+            for (var cj = 0; cj < node.children.length; cj += 1) stack.push(node.children[cj]);
+          }
+        }
+      } catch (_e) { /* drop-silent — categories unreachable drops those rows */ }
+    }
+    // Active collection browse pages, when the collections primitive is
+    // wired. Same best-effort discipline.
+    if (deps.collections && typeof deps.collections.list === "function") {
+      try {
+        var cols = await deps.collections.list({ active_only: true });
+        for (var coi = 0; coi < cols.length; coi += 1) {
+          if (cols[coi] && cols[coi].slug) {
+            urls.push({ loc: origin + "/collections/" + cols[coi].slug, changefreq: "weekly", priority: "0.6" });
+          }
+        }
+      } catch (_e) { /* drop-silent — collections unreachable drops those rows */ }
+    }
     var body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
                "<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n";
     for (var u = 0; u < urls.length; u += 1) {
@@ -8985,6 +9426,7 @@ module.exports = {
   renderProduct:         renderProduct,
   renderCart:            renderCart,
   renderCheckoutForm:    renderCheckoutForm,
+  renderCheckoutError:   renderCheckoutError,
   renderGiftCardBalance: renderGiftCardBalance,
   renderPayPage:         renderPayPage,
   renderOrder:           renderOrder,

package/lib/translations.js

@@ -593,6 +593,7 @@ var CHROME_DEFAULTS = Object.freeze({
   footer_shop_sale:       "On sale",
   footer_shop_compare:    "Compare",
   footer_shop_cart:       "Cart",
+  footer_shop_shipping:   "Shipping & returns",
 
   footer_framework_heading: "Framework",
   footer_framework_source:  "Source on GitHub",
@@ -600,10 +601,9 @@ var CHROME_DEFAULTS = Object.freeze({
   footer_framework_security: "Security policy",
   footer_framework_changelog: "Changelog",
 
-  footer_operators_heading: "Operators",
+  footer_operators_heading: "Your account",
   footer_operators_account: "Account",
   footer_operators_orders:  "Orders",
-  footer_operators_admin:   "Admin",
   footer_operators_contact: "Contact",
 
   footer_copy_suffix:  "built on blamejs · Apache 2.0 licensed.",

package/package.json

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