@blamejs/blamejs-shop 0.3.35 → 0.3.37

package/lib/storefront.js

@@ -30,6 +30,12 @@ var pricing      = require("./pricing");
 var currencyDisplayModule = require("./currency-display");
 var translationsModule = require("./translations");
 var securityMiddleware = require("./security-middleware");
+var giftRegistryModule = require("./gift-registry");
+
+// Registry occasion values, sourced from the gift-registry primitive so the
+// storefront's <select> options never drift from the column CHECK enum the
+// migration enforces. The primitive is the single source of truth.
+var REGISTRY_OCCASIONS = giftRegistryModule.OCCASIONS;
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
 var b = require("./vendor/blamejs");
@@ -2644,6 +2650,391 @@ function renderSharedWishlist(opts) {
   });
 }
 
+// ---- gift registry -------------------------------------------------------
+//
+// Owner side (renderRegistryList / renderRegistryManage) is gated on the
+// session customer; the public giver view (renderRegistryPublic) takes no
+// auth — the slug (resolved through the privacy gate) is the access.
+
+// Human label for an occasion enum value. Unknown values fall back to the
+// raw token (never throws) so a future migration that adds an occasion the
+// renderer hasn't been taught still shows something readable.
+var REGISTRY_OCCASION_LABELS = {
+  wedding:      "Wedding",
+  baby:         "Baby",
+  housewarming: "Housewarming",
+  birthday:     "Birthday",
+  graduation:   "Graduation",
+  anniversary:  "Anniversary",
+  other:        "Other",
+};
+function _registryOccasionLabel(occasion) {
+  return REGISTRY_OCCASION_LABELS[occasion] || (occasion || "Registry");
+}
+
+// Build a <select> of occasion options. `selected` highlights the current
+// value (the edit form); absent it the first option is the browser default.
+function _registryOccasionSelect(name, selected, esc) {
+  var opts = "";
+  for (var i = 0; i < REGISTRY_OCCASIONS.length; i += 1) {
+    var v = REGISTRY_OCCASIONS[i];
+    var sel = v === selected ? " selected" : "";
+    opts += "<option value=\"" + esc(v) + "\"" + sel + ">" + esc(_registryOccasionLabel(v)) + "</option>";
+  }
+  return "<select name=\"" + esc(name) + "\" required>" + opts + "</select>";
+}
+
+// Build a <select> of privacy options with inline help text.
+var REGISTRY_PRIVACY_LABELS = {
+  private:  "Private — only you can see it",
+  unlisted: "Unlisted — anyone with the link can see it",
+  public:   "Public — discoverable in the shop",
+};
+function _registryPrivacySelect(name, selected, esc) {
+  var order = ["unlisted", "public", "private"];
+  var opts = "";
+  for (var i = 0; i < order.length; i += 1) {
+    var v = order[i];
+    var sel = v === selected ? " selected" : "";
+    opts += "<option value=\"" + esc(v) + "\"" + sel + ">" + esc(REGISTRY_PRIVACY_LABELS[v] || v) + "</option>";
+  }
+  return "<select name=\"" + esc(name) + "\" required>" + opts + "</select>";
+}
+
+// Owner-facing list of registries (`GET /account/registry`). `opts.rows` is
+// each registry decoded by `listForOwner`, decorated with its `progress`
+// rollup ({ overall_percent, total_desired, total_purchased }). The create
+// form posts to /account/registry. `opts.notice` surfaces a created/closed/
+// updated confirmation. A per-customer page — noindex.
+var REGISTRY_LIST_NOTICES = {
+  created: "Registry created. Add the items you're hoping for below.",
+  closed:  "Registry closed. It's still viewable so you can send thank-you notes.",
+  updated: "Registry updated.",
+  removed: "Item removed from your registry.",
+  added:   "Item added to your registry.",
+};
+function renderRegistryList(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var rows = opts.rows || [];
+  var rowsHtml = "";
+  for (var i = 0; i < rows.length; i += 1) {
+    var r = rows[i];
+    var reg = r.registry;
+    var prog = r.progress || { overall_percent: 0, total_purchased: 0, total_desired: 0 };
+    var statusBadge = reg.status === "closed"
+      ? "<span class=\"registry-card__status registry-card__status--closed\">Closed</span>"
+      : "<span class=\"registry-card__status registry-card__status--active\">Active</span>";
+    rowsHtml +=
+      "<li class=\"registry-card\">" +
+        "<div class=\"registry-card__head\">" +
+          "<a class=\"registry-card__title\" href=\"/account/registry/" + esc(reg.slug) + "\">" + esc(reg.title) + "</a>" +
+          statusBadge +
+        "</div>" +
+        "<p class=\"registry-card__meta\">" + esc(_registryOccasionLabel(reg.occasion)) + " · " +
+          esc(REGISTRY_PRIVACY_LABELS[reg.privacy] || reg.privacy) + "</p>" +
+        "<p class=\"registry-card__progress\">" + esc(String(prog.overall_percent)) + "% fulfilled" +
+          " (" + esc(String(prog.total_purchased)) + " of " + esc(String(prog.total_desired)) + ")</p>" +
+        "<a class=\"card-link\" href=\"/account/registry/" + esc(reg.slug) + "\">Manage registry →</a>" +
+      "</li>";
+  }
+  var list = rowsHtml
+    ? "<ul class=\"registry-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\">" +
+        "<p class=\"account-empty__lede\">You haven't created a registry yet. Start one below for a wedding, a baby, a housewarming, or any occasion — then share the link with friends and family.</p>" +
+      "</div>";
+  var noticeMsg = REGISTRY_LIST_NOTICES[opts.notice];
+  var notice = noticeMsg
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">" + esc(noticeMsg) + "</p>"
+    : "";
+  var errMsg = (typeof opts.error === "string" && opts.error.length) ? opts.error : "";
+  var errBlock = errMsg
+    ? "<p class=\"form-notice form-notice--err\" role=\"alert\">" + esc(errMsg) + "</p>"
+    : "";
+  // The slug field is operator-authored (lowercase alnum + dash) — the
+  // backend validates it; the form pattern is a UX hint only (backend
+  // remains authoritative, never the client).
+  var createForm =
+    "<section class=\"registry-create\" aria-labelledby=\"registry-create-heading\">" +
+      "<h2 id=\"registry-create-heading\" class=\"registry-create__title\">Create a registry</h2>" +
+      errBlock +
+      "<form class=\"registry-create__form\" method=\"post\" action=\"/account/registry\">" +
+        "<label class=\"field\"><span class=\"field__label\">Title</span>" +
+          "<input type=\"text\" name=\"title\" required maxlength=\"200\" placeholder=\"Alice &amp; Bob's Wedding\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Registry link (lowercase letters, numbers, dashes)</span>" +
+          "<input type=\"text\" name=\"slug\" required maxlength=\"200\" pattern=\"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\" placeholder=\"alice-and-bob-2026\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Recipient name</span>" +
+          "<input type=\"text\" name=\"recipient_name\" required maxlength=\"200\" placeholder=\"Alice &amp; Bob\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Occasion</span>" +
+          _registryOccasionSelect("occasion", "wedding", esc) + "</label>" +
+        "<label class=\"field\"><span class=\"field__label\">Event date (optional)</span>" +
+          "<input type=\"date\" name=\"event_date\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Who can see it</span>" +
+          _registryPrivacySelect("privacy", "unlisted", esc) + "</label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Create registry</button>" +
+      "</form>" +
+    "</section>";
+  var body =
+    "<section class=\"account-registry\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Gift registry</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-registry__title\">Your gift registries</h1>" +
+      notice +
+      list +
+      createForm +
+    "</section>";
+  return _wrap({
+    title:      "Gift registry",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    // Per-customer management surface — keep it out of the index.
+    robots:     "noindex",
+    body:       body,
+  });
+}
+
+// Owner-facing manage page for one registry (`GET /account/registry/:slug`).
+// `opts.registry` is the decoded row; `opts.items` is each item decorated
+// with { product, hero_media, purchased, remaining, desired }; `opts.share_url`
+// is the absolute public URL (built from the request origin by the route).
+// Carries the add-item / edit / close forms. Per-customer — noindex.
+function renderRegistryManage(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var prefix = opts.asset_prefix || "/assets/";
+  var reg = opts.registry || {};
+  var items = opts.items || [];
+  var closed = reg.status === "closed";
+  var rowsHtml = "";
+  for (var i = 0; i < items.length; i += 1) {
+    var it = items[i];
+    var media = it.hero_media
+      ? "<img src=\"" + esc(prefix + it.hero_media.r2_key) + "\" alt=\"" + esc(it.hero_media.alt_text || (it.product && it.product.title) || it.sku) + "\" loading=\"lazy\">"
+      : "<span class=\"registry-item__mark\" aria-hidden=\"true\">" + esc(((it.product && it.product.title) || it.sku || "?").trim().charAt(0).toUpperCase() || "?") + "</span>";
+    var titleHtml = it.product
+      ? "<a class=\"registry-item__title\" href=\"/products/" + esc(it.product.slug) + "\">" + esc(it.product.title) + "</a>"
+      : "<span class=\"registry-item__title\">" + esc(it.sku) + " (no longer in the catalog)</span>";
+    var removeForm = closed ? "" :
+      "<form class=\"registry-item__remove\" method=\"post\" action=\"/account/registry/" + esc(reg.slug) + "/items/" + esc(it.item_id) + "/remove\">" +
+        "<button type=\"submit\" class=\"btn-ghost\">Remove</button>" +
+      "</form>";
+    rowsHtml +=
+      "<li class=\"registry-item\">" +
+        "<span class=\"registry-item__media\">" + media + "</span>" +
+        "<div class=\"registry-item__body\">" +
+          titleHtml +
+          "<p class=\"registry-item__progress\">" + esc(String(it.purchased)) + " of " + esc(String(it.desired)) +
+            " purchased · " + esc(String(it.remaining)) + " still needed</p>" +
+        "</div>" +
+        removeForm +
+      "</li>";
+  }
+  var list = rowsHtml
+    ? "<ul class=\"registry-item-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\"><p class=\"account-empty__lede\">No items yet. Add the products you're hoping for below.</p></div>";
+
+  var addForm = closed ? "" :
+    "<section class=\"registry-add\" aria-labelledby=\"registry-add-heading\">" +
+      "<h2 id=\"registry-add-heading\" class=\"registry-add__title\">Add an item</h2>" +
+      "<form class=\"registry-add__form\" method=\"post\" action=\"/account/registry/" + esc(reg.slug) + "/items\">" +
+        "<label class=\"field\"><span class=\"field__label\">Product SKU</span>" +
+          "<input type=\"text\" name=\"sku\" required maxlength=\"200\" placeholder=\"BLENDER-12CUP\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Quantity wanted</span>" +
+          "<input type=\"number\" name=\"quantity_desired\" required min=\"1\" max=\"999\" value=\"1\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Priority (1 = most wanted)</span>" +
+          "<input type=\"number\" name=\"priority\" min=\"1\" max=\"5\" value=\"3\"></label>" +
+        "<button type=\"submit\" class=\"btn-secondary\">Add to registry</button>" +
+      "</form>" +
+    "</section>";
+
+  var eventDateValue = (typeof reg.event_date === "number")
+    ? new Date(reg.event_date).toISOString().slice(0, 10)
+    : "";
+  var editForm = closed ? "" :
+    "<section class=\"registry-edit\" aria-labelledby=\"registry-edit-heading\">" +
+      "<h2 id=\"registry-edit-heading\" class=\"registry-edit__title\">Registry details</h2>" +
+      "<form class=\"registry-edit__form\" method=\"post\" action=\"/account/registry/" + esc(reg.slug) + "/edit\">" +
+        "<label class=\"field\"><span class=\"field__label\">Title</span>" +
+          "<input type=\"text\" name=\"title\" required maxlength=\"200\" value=\"" + esc(reg.title || "") + "\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Recipient name</span>" +
+          "<input type=\"text\" name=\"recipient_name\" required maxlength=\"200\" value=\"" + esc(reg.recipient_name || "") + "\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Event date</span>" +
+          "<input type=\"date\" name=\"event_date\" value=\"" + esc(eventDateValue) + "\"></label>" +
+        "<label class=\"field\"><span class=\"field__label\">Who can see it</span>" +
+          _registryPrivacySelect("privacy", reg.privacy, esc) + "</label>" +
+        "<button type=\"submit\" class=\"btn-secondary\">Save details</button>" +
+      "</form>" +
+    "</section>";
+
+  var closeForm = closed
+    ? "<p class=\"registry-manage__closed-note\">This registry is closed. It stays viewable so you can review what arrived.</p>"
+    : "<form class=\"registry-close__form\" method=\"post\" action=\"/account/registry/" + esc(reg.slug) + "/close\">" +
+        "<button type=\"submit\" class=\"btn-ghost registry-close__btn\">Close this registry</button>" +
+      "</form>";
+
+  // The shareable public URL — shown only for a non-private registry (a
+  // private registry isn't publicly viewable, so there's no link to share).
+  var shareBlock = "";
+  if (reg.privacy !== "private" && opts.share_url) {
+    shareBlock =
+      "<section class=\"registry-share\" aria-labelledby=\"registry-share-heading\">" +
+        "<h2 id=\"registry-share-heading\" class=\"registry-share__title\">Share this registry</h2>" +
+        "<p class=\"registry-share__lede\">Send this link to friends and family. They can see what you're hoping for and mark items as purchased — buyers stay anonymous unless they choose otherwise.</p>" +
+        "<label class=\"registry-share__label\" for=\"registry-share-url\">Public link</label>" +
+        "<input id=\"registry-share-url\" class=\"registry-share__url\" type=\"text\" readonly value=\"" + esc(opts.share_url) + "\" " +
+          "aria-label=\"Public registry link\" onfocus=\"this.select()\">" +
+      "</section>";
+  } else if (reg.privacy === "private") {
+    shareBlock = "<p class=\"registry-share__private-note\">This registry is private — no public link. Change it to unlisted or public above to share it.</p>";
+  }
+
+  var noticeMsg = REGISTRY_LIST_NOTICES[opts.notice];
+  var notice = noticeMsg
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">" + esc(noticeMsg) + "</p>"
+    : "";
+  var errMsg = (typeof opts.error === "string" && opts.error.length) ? opts.error : "";
+  var errBlock = errMsg
+    ? "<p class=\"form-notice form-notice--err\" role=\"alert\">" + esc(errMsg) + "</p>"
+    : "";
+
+  var body =
+    "<section class=\"account-registry-manage\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/registry\">Gift registry</a></li>" +
+        "<li aria-current=\"page\">" + esc(reg.title || "Registry") + "</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-registry-manage__title\">" + esc(reg.title || "Registry") + "</h1>" +
+      "<p class=\"account-registry-manage__meta\">" + esc(_registryOccasionLabel(reg.occasion)) + " · " +
+        esc(REGISTRY_PRIVACY_LABELS[reg.privacy] || reg.privacy) + (closed ? " · Closed" : "") + "</p>" +
+      notice +
+      errBlock +
+      shareBlock +
+      list +
+      addForm +
+      editForm +
+      closeForm +
+    "</section>";
+  return _wrap({
+    title:      reg.title || "Registry",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    robots:     "noindex",
+    body:       body,
+  });
+}
+
+// Confirmation copy after a public giver action. Unknown keys render nothing
+// so a forged ?ok= query can't inject arbitrary copy onto the page.
+var REGISTRY_PUBLIC_NOTICES = {
+  gifted: "Thank you! We've marked that item as purchased.",
+};
+
+// Public, no-auth giver view of a registry (`GET /registry/:slug`). The route
+// resolves the registry ONLY through getBySlug (which honors the privacy
+// gate — a private registry returns null and the route 404s); the owner's
+// customer id + shipping address + buyer identities are NEVER carried into
+// this shape (the route passes title/occasion/event_date + per-item desired /
+// purchased / remaining counts + product cards only). Each not-yet-fulfilled
+// item carries a "mark purchased" form (records a gift via purchaseItem —
+// buyer anonymous by default) and an "add to cart" link so the giver can buy
+// it normally through the regular cart/checkout. Carries a noindex robots
+// directive — a personal registry is not search-index material.
+function renderRegistryPublic(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var prefix = opts.asset_prefix || "/assets/";
+  var reg = opts.registry || {};
+  var items = opts.items || [];
+  var heading = (reg.title && String(reg.title).length) ? reg.title : "A gift registry";
+  var occasionLine = esc(_registryOccasionLabel(reg.occasion));
+  if (typeof reg.event_date === "number") {
+    var dt = new Date(reg.event_date);
+    if (!isNaN(dt.getTime())) {
+      occasionLine += " · " + esc(dt.toISOString().slice(0, 10));
+    }
+  }
+  var rowsHtml = "";
+  for (var i = 0; i < items.length; i += 1) {
+    var it = items[i];
+    var media = it.hero_media
+      ? "<img src=\"" + esc(prefix + it.hero_media.r2_key) + "\" alt=\"" + esc(it.hero_media.alt_text || (it.product && it.product.title) || it.sku) + "\" loading=\"lazy\">"
+      : "<span class=\"registry-item__mark\" aria-hidden=\"true\">" + esc(((it.product && it.product.title) || it.sku || "?").trim().charAt(0).toUpperCase() || "?") + "</span>";
+    var titleHtml = it.product
+      ? "<a class=\"registry-item__title\" href=\"/products/" + esc(it.product.slug) + "\">" + esc(it.product.title) + "</a>"
+      : "<span class=\"registry-item__title\">" + esc(it.sku) + "</span>";
+    // Progress line — desired vs already purchased. A fully-purchased item
+    // shows a "fully gifted" badge and offers no purchase control.
+    var fulfilled = it.remaining <= 0;
+    var progressHtml = fulfilled
+      ? "<p class=\"registry-item__progress registry-item__progress--done\">Fully gifted — thank you!</p>"
+      : "<p class=\"registry-item__progress\">" + esc(String(it.purchased)) + " of " + esc(String(it.desired)) +
+          " purchased · " + esc(String(it.remaining)) + " still needed</p>";
+    // Giver controls: only for an item that's both buyable (resolves to a
+    // catalog variant) and not yet fully gifted, and only while the registry
+    // is active (a closed registry refuses purchaseItem).
+    var controls = "";
+    if (!fulfilled && reg.status === "active") {
+      var markForm =
+        "<form class=\"registry-item__gift\" method=\"post\" action=\"/registry/" + esc(reg.slug) + "/items/" + esc(it.item_id) + "/purchase\">" +
+          "<input type=\"hidden\" name=\"quantity\" value=\"1\">" +
+          "<label class=\"registry-item__reveal\"><input type=\"checkbox\" name=\"reveal\" value=\"1\"> Let the recipient see it was from me (requires sign-in)</label>" +
+          "<button type=\"submit\" class=\"btn-secondary\">Mark as purchased</button>" +
+        "</form>";
+      var cartForm = it.variant_id
+        ? "<form class=\"registry-item__cart\" method=\"post\" action=\"/cart/lines\">" +
+            "<input type=\"hidden\" name=\"variant_id\" value=\"" + esc(it.variant_id) + "\">" +
+            "<input type=\"hidden\" name=\"qty\" value=\"1\">" +
+            "<button type=\"submit\" class=\"btn-ghost\">Add to cart</button>" +
+          "</form>"
+        : "";
+      controls = "<div class=\"registry-item__actions\">" + cartForm + markForm + "</div>";
+    }
+    rowsHtml +=
+      "<li class=\"registry-item\">" +
+        "<span class=\"registry-item__media\">" + media + "</span>" +
+        "<div class=\"registry-item__body\">" +
+          titleHtml +
+          progressHtml +
+          controls +
+        "</div>" +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"registry-item-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\"><p class=\"account-empty__lede\">This registry doesn't have any items yet — check back soon.</p>" +
+        "<a class=\"btn-secondary\" href=\"/\">Browse the shop →</a></div>";
+  var noticeMsg = REGISTRY_PUBLIC_NOTICES[opts.notice];
+  var notice = noticeMsg
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">" + esc(noticeMsg) + "</p>"
+    : "";
+  var messageBlock = (reg.message && String(reg.message).length)
+    ? "<p class=\"registry-public__message\">" + esc(reg.message) + "</p>"
+    : "";
+  var body =
+    "<section class=\"registry-public\">" +
+      "<p class=\"eyebrow\">Gift registry</p>" +
+      "<h1 class=\"registry-public__title\">" + esc(heading) + "</h1>" +
+      "<p class=\"registry-public__meta\">" + occasionLine + "</p>" +
+      messageBlock +
+      notice +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      heading,
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    // A personal registry is not search-index material.
+    robots:     "noindex",
+    body:       body,
+  });
+}
+
 // Compare page notice banner — surfaced after a toggle / a full-basket
 // refusal. The route passes a short message key; unknown keys render
 // nothing so a forged `?notice=` query can't inject arbitrary copy.
@@ -3462,6 +3853,206 @@ function renderReturns(opts) {
   });
 }
 
+// Customer-facing reasons for an exchange. The values mirror the
+// order-exchanges module's REASONS allow-list; the backend validates the
+// submitted value against its own list, so a forged value is refused
+// there. (No-longer-needed isn't an exchange reason — that's a return.)
+var EXCHANGE_REASONS = [
+  ["defective", "Defective / doesn't work"],
+  ["wrong-item", "Wrong item received"],
+  ["wrong-size", "Wrong size"],
+  ["wrong-colour", "Wrong colour"],
+  ["damaged-in-transit", "Damaged in transit"],
+  ["not-as-described", "Not as described"],
+  ["other", "Other"],
+];
+
+// Customer-facing phrasing for an exchange's FSM status. The module's
+// enum (pending / approved / shipped / delivered / received / closed /
+// rejected) is operator vocabulary; these read for the shopper.
+var EXCHANGE_STATUS_LABELS = {
+  pending:   "Requested",
+  approved:  "Approved",
+  shipped:   "Replacement shipped",
+  delivered: "Replacement delivered",
+  received:  "Return received",
+  closed:    "Completed",
+  rejected:  "Declined",
+};
+
+function _exchangeStatusBadge(status) {
+  var esc = b.template.escapeHtml;
+  var label = EXCHANGE_STATUS_LABELS[status] || status;
+  return "<span class=\"return-status return-status--" + esc(String(status)) + "\">" +
+    esc(String(label)) + "</span>";
+}
+
+// Customer-facing exchange-request form for one owned order. `opts.lines`
+// is the order's order_lines, each decorated with `replacement_options`
+// (the sibling variants of that line's product the shopper can swap to).
+// `opts.notice` is an optional error bounced back from a failed POST.
+// Reuses the returns-form layout classes — no new CSS.
+function renderExchangeForm(opts) {
+  var esc = b.template.escapeHtml;
+  var order = opts.order;
+  var lines = opts.lines || [];
+  var lineRows = "";
+  for (var i = 0; i < lines.length; i += 1) {
+    var l = lines[i];
+    var maxQty = Number(l.qty) || 1;
+    var replOpts = (l.replacement_options || []).map(function (o) {
+      return "<option value=\"" + esc(String(o.id)) + "\">" + esc(String(o.label)) + "</option>";
+    }).join("");
+    // A line with no resolvable sibling variants can't be exchanged for a
+    // different option — offer a same-SKU swap (replace a defective unit)
+    // so the line is never silently undisplayable.
+    var replaceField = replOpts
+      ? "<label class=\"return-line__qty\">Swap for " +
+          "<select name=\"replacement_" + esc(l.id) + "\">" + replOpts + "</select>" +
+        "</label>"
+      : "<p class=\"return-line__of\">Same item, replacement unit.</p>";
+    lineRows +=
+      "<li class=\"return-line\">" +
+        "<label class=\"return-line__pick\">" +
+          "<input type=\"radio\" name=\"line_id\" value=\"" + esc(l.id) + "\"" + (i === 0 ? " checked" : "") + ">" +
+          "<span class=\"return-line__sku\"><code>" + esc(l.sku) + "</code></span>" +
+        "</label>" +
+        "<label class=\"return-line__qty\">Qty to exchange " +
+          "<input type=\"number\" name=\"qty_" + esc(l.id) + "\" value=\"1\" min=\"1\" max=\"" + maxQty + "\">" +
+          " <span class=\"return-line__of\">of " + maxQty + "</span>" +
+        "</label>" +
+        replaceField +
+      "</li>";
+  }
+  var reasonOpts = EXCHANGE_REASONS.map(function (r) {
+    return "<option value=\"" + esc(r[0]) + "\">" + esc(r[1]) + "</option>";
+  }).join("");
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body =
+    "<section class=\"return-form-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">Request an exchange</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"return-form-page__title\">Request an exchange</h1>" +
+      "<p class=\"return-form-page__order\">Order <code>" + esc(order.id) + "</code></p>" +
+      notice +
+      "<form class=\"return-form form-stack\" method=\"post\" action=\"/account/orders/" + esc(order.id) + "/exchange\">" +
+        "<fieldset class=\"return-form__lines\"><legend>Which item?</legend>" +
+          "<ul class=\"return-line-list\">" + lineRows + "</ul>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Reason</span>" +
+          "<select name=\"reason\" required>" + reasonOpts + "</select></label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Request exchange</button>" +
+      "</form>" +
+    "</section>";
+  return _wrap({
+    title:      "Request an exchange",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// The signed-in customer's exchange list. `opts.exchanges` is the
+// ownership-scoped set (already filtered to this customer's orders); each
+// links to its status detail.
+function renderExchanges(opts) {
+  var esc = b.template.escapeHtml;
+  var exchanges = opts.exchanges || [];
+  var rowsHtml = "";
+  for (var i = 0; i < exchanges.length; i += 1) {
+    var x = exchanges[i];
+    var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+    rowsHtml +=
+      "<li class=\"return-card\">" +
+        "<div class=\"return-card__head\">" +
+          "<a class=\"return-card__rma\" href=\"/account/exchanges/" + esc(String(x.id)) + "\"><code>" + esc(String(x.id).slice(0, 8)) + "</code></a>" +
+          _exchangeStatusBadge(x.status) +
+        "</div>" +
+        "<p class=\"return-card__meta\">" +
+          esc(String(x.return_sku || "")) + " &rarr; " + esc(String(x.replacement_sku || "")) +
+          (date ? " &middot; <time datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+        "</p>" +
+        (x.status === "rejected" && x.reject_reason ? "<p class=\"return-card__reject\">" + esc(String(x.reject_reason)) + "</p>" : "") +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"return-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\">" +
+        "<p class=\"account-empty__lede\">No exchanges yet. Start one from an order in your account.</p>" +
+        "<a class=\"btn-secondary\" href=\"/account/orders\">View your orders &rarr;</a>" +
+      "</div>";
+  var notice = opts.requested
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">Exchange request received — we'll review it and email you next steps.</p>"
+    : "";
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Exchanges</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Exchanges</h1>" +
+      notice +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      "Exchanges",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// One exchange's status detail. Ownership-scoped (the route only renders
+// this for an exchange whose parent order belongs to the session
+// customer). Surfaces the swap, the reason, the live status, the
+// rejection reason (if declined), and the outbound tracking number once
+// the replacement has shipped.
+function renderExchangeDetail(opts) {
+  var esc = b.template.escapeHtml;
+  var x = opts.exchange;
+  var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+  var rows = "";
+  function _row(label, value) {
+    return "<p class=\"return-card__meta\"><span class=\"form-field__label\">" + esc(label) + "</span> " +
+      (value ? esc(String(value)) : "&mdash;") + "</p>";
+  }
+  rows += _row("Item returned", x.return_sku + " ×" + x.return_qty);
+  rows += _row("Replacement", x.replacement_sku + " ×" + x.replacement_qty);
+  rows += _row("Reason", x.reason);
+  if (date) rows += _row("Requested", date);
+  if (x.status === "rejected" && x.reject_reason) rows += _row("Why it was declined", x.reject_reason);
+  if (x.tracking_number) {
+    rows += _row("Replacement tracking", x.carrier ? (x.carrier + " · " + x.tracking_number) : x.tracking_number);
+  }
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">" + esc(String(x.id).slice(0, 8)) + "</li>" +
+      "</ol></nav>" +
+      "<div class=\"return-card__head\">" +
+        "<h1 class=\"account-returns__title\">Exchange <code>" + esc(String(x.id).slice(0, 8)) + "</code></h1>" +
+        _exchangeStatusBadge(x.status) +
+      "</div>" +
+      "<div class=\"return-card\">" + rows + "</div>" +
+    "</section>";
+  return _wrap({
+    title:      "Exchange " + String(x.id).slice(0, 8),
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Support ticket — the categories a shopper can pick when raising one,
 // and the human label for each. The values mirror the support-tickets
 // module's ALLOWED_CATEGORIES; the backend validates the submitted value
@@ -5255,6 +5846,17 @@ function _orderEligibleForReturn(status) {
     status === "shipped" || status === "delivered";
 }
 
+// An exchange (swap the item for a different size / colour / unit at the
+// same value) is offered on the same window as a return: a paid (or
+// further-along) order, never a still-pending (unpaid) one nor the
+// terminal off-ramps (cancelled / refunded). The customer ships the
+// original back AND receives a replacement — no refund — so the window
+// matches the goods being in the customer's hands.
+function _orderEligibleForExchange(status) {
+  return status === "paid" || status === "fulfilling" ||
+    status === "shipped" || status === "delivered";
+}
+
 // Reorder is offered for any order that represents a real purchase the
 // customer might want to repeat — paid through delivered, plus the
 // terminal refunded/cancelled states (a cancelled or refunded order is a
@@ -5378,6 +5980,10 @@ function _orderActionsBlock(o) {
     btns.push(
       "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/return\">Request a return</a>");
   }
+  if (_orderEligibleForExchange(o.status)) {
+    btns.push(
+      "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/exchange\">Request an exchange</a>");
+  }
   if (_orderEligibleForCancel(o.status)) {
     btns.push(
       "<form class=\"order-action\" method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/cancel\">" +
@@ -6641,6 +7247,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/recently-viewed\">Recently viewed</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/addresses\">Addresses</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/exchanges\">Exchanges</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/support\">Support</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/loyalty\">Rewards</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/credit\">Store credit</a>\n" +
@@ -11050,25 +11657,554 @@ function mount(router, deps) {
       });
     }
 
-    // Save for later — move a cart line into a per-customer holding
-    // list and back. Login required (the list is per-customer).
-    if (deps.saveForLater) {
-      function _savedAuth(req, res) {
+    // ---- gift registry --------------------------------------------------
+    //
+    // Owner side (gated on the session customer, CSRF-protected by the
+    // container form chokepoint): list the customer's registries with
+    // progress, create one, then a per-registry manage page (add / remove
+    // items, edit details, close) plus the shareable public URL. Every owner
+    // route is scoped to the session customer — a registry whose
+    // `owner_customer_id` isn't the signed-in customer resolves to a clean
+    // 404 (no IDOR), because the gift-registry primitive moves a registry by
+    // slug alone and has no notion of the requesting customer.
+    //
+    // Public side (NO auth): `GET /registry/:slug` resolves the registry ONLY
+    // through `getBySlug(slug)` — never a guessable owner/registry id from the
+    // path or query — and the route honors the privacy gate: a `private`
+    // registry (and an unknown slug) 404s identically, with no existence
+    // oracle. The view renders the title / occasion /
+    // event date + per-item desired-vs-purchased counts + product links, and
+    // NEVER carries the owner's customer id / shipping address or any buyer
+    // identity into the page (the primitive's getBySlug surfaces items +
+    // aggregate counts only; the per-buyer purchase rows stay owner-internal).
+    // A giver marks an item purchased (records a gift via purchaseItem,
+    // anonymous by default) or adds it to their own cart to buy normally.
+    // noindex (a personal registry isn't index material).
+    if (deps.giftRegistry) {
+      // Load a registry the SESSION customer owns, or null. The primitive's
+      // getRegistry moves by slug alone, so the route owns the ownership
+      // decision: a registry whose owner_customer_id isn't the session
+      // customer is treated identically to a missing one (clean 404, no
+      // oracle on existence). A malformed slug throws inside the primitive's
+      // slug validator — caught by the caller and mapped to a 404.
+      async function _ownedRegistry(slug, customerId) {
+        var reg;
+        try { reg = await deps.giftRegistry.getRegistry(slug); }
+        catch (_e) { return null; }   // malformed slug → not found
+        if (!reg || reg.owner_customer_id !== customerId) return null;
+        return reg;
+      }
+
+      // Resolve a registry item's sku to its catalog product + hero image +
+      // buyable variant id. Returns { product, hero_media, variant_id } —
+      // any field null when the sku no longer resolves (the item still shows,
+      // with no buy control). Best-effort: a catalog read failure degrades to
+      // an undecorated item rather than throwing.
+      async function _decorateRegistryItem(item) {
+        var out = {
+          item_id:    item.id,
+          sku:        item.sku,
+          variant_id: null,
+          product:    null,
+          hero_media: null,
+        };
+        try {
+          var variant = await deps.catalog.variants.bySku(item.sku);
+          if (variant) {
+            out.variant_id = variant.id;
+            var product = await deps.catalog.products.get(variant.product_id);
+            if (product && product.status === "active") {
+              out.product = product;
+              var media = await deps.catalog.media.listForProduct(product.id);
+              out.hero_media = media.length ? media[0] : null;
+            }
+          }
+        } catch (_e) { /* drop-silent — an undecorated item still renders */ }
+        return out;
+      }
+
+      // GET /account/registry — the session customer's registries, each with
+      // its progress rollup, plus the create form.
+      router.get("/account/registry", async function (req, res) {
         var auth;
         try { auth = _currentCustomer(req); }
         catch (e) {
-          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
           throw e;
         }
         if (!auth) {
           res.status(303); res.setHeader && res.setHeader("location", "/account/login");
-          res.end ? res.end() : res.send("");
-          return null;
+          return res.end ? res.end() : res.send("");
         }
-        return auth;
-      }
-
-      // POST /cart/lines/:line_id/save — move the line out of the cart
+        var regs = [];
+        try { regs = await deps.giftRegistry.listForOwner(auth.customer_id); }
+        catch (_e) { regs = []; }
+        var rows = [];
+        for (var i = 0; i < regs.length; i += 1) {
+          var prog = null;
+          try { prog = await deps.giftRegistry.progressFor(regs[i].slug); }
+          catch (_e) { prog = null; }
+          rows.push({ registry: regs[i], progress: prog });
+        }
+        var listUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        _send(res, 200, renderRegistryList({
+          rows:         rows,
+          notice:       listUrl ? listUrl.searchParams.get("ok") : null,
+          shop_name:    shopName,
+          cart_count:   await _cartCountForReq(req),
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      });
+
+      // POST /account/registry — create a registry owned by the session
+      // customer. The owner id comes from the session, never the body, so a
+      // shopper can only ever create a registry under their own id.
+      router.post("/account/registry", async function (req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var body = req.body || {};
+        // event_date arrives as a yyyy-mm-dd string from <input type=date>;
+        // convert to epoch-ms (midnight UTC) or null. A malformed value
+        // becomes null rather than 400-ing — the date is optional.
+        var eventDate = null;
+        if (typeof body.event_date === "string" && body.event_date.length) {
+          var parsed = Date.parse(body.event_date + "T00:00:00Z");
+          if (!isNaN(parsed)) eventDate = parsed;
+        }
+        try {
+          await deps.giftRegistry.createRegistry({
+            owner_customer_id: auth.customer_id,
+            slug:              String(body.slug || ""),
+            title:             String(body.title || ""),
+            recipient_name:    String(body.recipient_name || ""),
+            occasion:          String(body.occasion || ""),
+            privacy:           String(body.privacy || ""),
+            event_date:        eventDate,
+          });
+        } catch (e) {
+          // A bad slug / title / occasion / duplicate slug is operator error
+          // (TypeError) — re-render the list with the message; anything else
+          // is a 500.
+          if (e instanceof TypeError) {
+            var regs = [];
+            try { regs = await deps.giftRegistry.listForOwner(auth.customer_id); }
+            catch (_e2) { regs = []; }
+            var rows = [];
+            for (var i = 0; i < regs.length; i += 1) rows.push({ registry: regs[i], progress: null });
+            return _send(res, 400, renderRegistryList({
+              rows:         rows,
+              error:        (e && e.message) || "We couldn't create that registry.",
+              shop_name:    shopName,
+              cart_count:   await _cartCountForReq(req),
+              asset_prefix: deps.asset_prefix || "/assets/",
+            }));
+          }
+          res.status(500);
+          return res.end ? res.end("Error") : res.send("Error");
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/registry/" + encodeURIComponent(String(body.slug || "")) + "?ok=created");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // GET /account/registry/:slug — manage one registry the session
+      // customer owns. A registry the customer doesn't own (or an unknown
+      // slug) 404s.
+      router.get("/account/registry/:slug", async function (req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var slug = (req.params && req.params.slug) || "";
+        var reg = await _ownedRegistry(slug, auth.customer_id);
+        if (!reg) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        // Items + their progress. getBySlug returns items with their
+        // purchased-aggregate; progressFor gives the remaining count.
+        var view = null;
+        try { view = await deps.giftRegistry.getBySlug(slug); }
+        catch (_e) { view = null; }
+        var prog = null;
+        try { prog = await deps.giftRegistry.progressFor(slug); }
+        catch (_e) { prog = null; }
+        var remainingById = Object.create(null);
+        var purchasedById = Object.create(null);
+        var desiredById   = Object.create(null);
+        if (prog && prog.items) {
+          for (var p = 0; p < prog.items.length; p += 1) {
+            remainingById[prog.items[p].item_id] = prog.items[p].remaining;
+            purchasedById[prog.items[p].item_id] = prog.items[p].purchased;
+            desiredById[prog.items[p].item_id]   = prog.items[p].quantity_desired;
+          }
+        }
+        var items = [];
+        var rawItems = (view && view.items) || [];
+        for (var i = 0; i < rawItems.length; i += 1) {
+          var dec = await _decorateRegistryItem(rawItems[i]);
+          dec.desired   = desiredById[rawItems[i].id] != null ? desiredById[rawItems[i].id] : rawItems[i].quantity_desired;
+          dec.purchased = purchasedById[rawItems[i].id] || 0;
+          dec.remaining = remainingById[rawItems[i].id] != null ? remainingById[rawItems[i].id] : dec.desired;
+          items.push(dec);
+        }
+        // The shareable public URL — built from this request's ORIGIN (scheme
+        // + host), never by trimming a path off the canonical (this GET lands
+        // on /account/registry/:slug, so a trim would mangle the link).
+        var shareUrl = "";
+        if (reg.privacy !== "private") {
+          var origin = "";
+          try { origin = new URL(_requestUrls(req).canonical_url).origin; }
+          catch (_e) { origin = ""; }
+          shareUrl = origin + "/registry/" + encodeURIComponent(reg.slug);
+        }
+        var manageUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        _send(res, 200, renderRegistryManage({
+          registry:     reg,
+          items:        items,
+          share_url:    shareUrl,
+          notice:       manageUrl ? manageUrl.searchParams.get("ok") : null,
+          shop_name:    shopName,
+          cart_count:   await _cartCountForReq(req),
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      });
+
+      // POST /account/registry/:slug/items — add an item to a registry the
+      // session customer owns. Ownership-scoped (404 on a foreign / unknown
+      // registry).
+      router.post("/account/registry/:slug/items", async function (req, res) {
+        var auth = _registryAuthOrRedirect(req, res);
+        if (!auth) return;
+        var slug = (req.params && req.params.slug) || "";
+        var reg = await _ownedRegistry(slug, auth.customer_id);
+        if (!reg) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        var body = req.body || {};
+        var qty = parseInt(body.quantity_desired, 10);
+        var priorityRaw = parseInt(body.priority, 10);
+        try {
+          await deps.giftRegistry.addItem({
+            registry_slug:    slug,
+            sku:              String(body.sku || ""),
+            quantity_desired: Number.isFinite(qty) ? qty : 0,
+            priority:         Number.isFinite(priorityRaw) ? priorityRaw : 3,
+          });
+        } catch (e) {
+          return _registryManageError(req, res, reg, e);
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/registry/" + encodeURIComponent(slug) + "?ok=added");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // POST /account/registry/:slug/items/:item_id/remove — archive an item
+      // on a registry the session customer owns.
+      router.post("/account/registry/:slug/items/:item_id/remove", async function (req, res) {
+        var auth = _registryAuthOrRedirect(req, res);
+        if (!auth) return;
+        var slug = (req.params && req.params.slug) || "";
+        var reg = await _ownedRegistry(slug, auth.customer_id);
+        if (!reg) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        try {
+          await deps.giftRegistry.removeItem({
+            registry_slug: slug,
+            item_id:       (req.params && req.params.item_id) || "",
+          });
+        } catch (e) {
+          return _registryManageError(req, res, reg, e);
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/registry/" + encodeURIComponent(slug) + "?ok=removed");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // POST /account/registry/:slug/edit — update registry details
+      // (title / recipient_name / event_date / privacy) on a registry the
+      // session customer owns.
+      router.post("/account/registry/:slug/edit", async function (req, res) {
+        var auth = _registryAuthOrRedirect(req, res);
+        if (!auth) return;
+        var slug = (req.params && req.params.slug) || "";
+        var reg = await _ownedRegistry(slug, auth.customer_id);
+        if (!reg) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        var body = req.body || {};
+        var patch = {
+          title:          String(body.title || ""),
+          recipient_name: String(body.recipient_name || ""),
+          privacy:        String(body.privacy || ""),
+        };
+        if (typeof body.event_date === "string" && body.event_date.length) {
+          var parsed = Date.parse(body.event_date + "T00:00:00Z");
+          patch.event_date = isNaN(parsed) ? null : parsed;
+        } else {
+          patch.event_date = null;
+        }
+        try {
+          await deps.giftRegistry.update(slug, patch);
+        } catch (e) {
+          return _registryManageError(req, res, reg, e);
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/registry/" + encodeURIComponent(slug) + "?ok=updated");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // POST /account/registry/:slug/close — close a registry the session
+      // customer owns (the only FSM transition; refuses further mutation).
+      router.post("/account/registry/:slug/close", async function (req, res) {
+        var auth = _registryAuthOrRedirect(req, res);
+        if (!auth) return;
+        var slug = (req.params && req.params.slug) || "";
+        var reg = await _ownedRegistry(slug, auth.customer_id);
+        if (!reg) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        try {
+          await deps.giftRegistry.closeRegistry(slug);
+        } catch (e) {
+          return _registryManageError(req, res, reg, e);
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/registry/" + encodeURIComponent(slug) + "?ok=closed");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // GET /registry/:slug — the public, no-auth giver view. Resolves the
+      // registry ONLY through getBySlug (never a guessable owner/registry id),
+      // then enforces the privacy gate in the route: a `private` registry
+      // 404s exactly like an unknown slug — no existence oracle. The owner's
+      // identity / shipping address / per-buyer purchase rows are NEVER
+      // carried into this shape. noindex.
+      router.get("/registry/:slug", async function (req, res) {
+        var slug = (req.params && req.params.slug) || "";
+        var view = null;
+        try {
+          view = await deps.giftRegistry.getBySlug(slug);
+        } catch (_e) {
+          // A malformed slug (TypeError) renders the same 404 as an unknown
+          // one — no oracle on why.
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        // Honor the privacy gate: a missing registry AND a `private` one are
+        // not publicly viewable — both 404 identically (no existence oracle).
+        // `private` resolves only through the owner's /account/registry surface
+        // (scoped to the session customer); `unlisted` + `public` are reachable
+        // by anyone who knows the slug.
+        if (!view || !view.registry || view.registry.privacy === "private") {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        var prog = null;
+        try { prog = await deps.giftRegistry.progressFor(slug); }
+        catch (_e) { prog = null; }
+        var remainingById = Object.create(null);
+        var purchasedById = Object.create(null);
+        var desiredById   = Object.create(null);
+        if (prog && prog.items) {
+          for (var p = 0; p < prog.items.length; p += 1) {
+            remainingById[prog.items[p].item_id] = prog.items[p].remaining;
+            purchasedById[prog.items[p].item_id] = prog.items[p].purchased;
+            desiredById[prog.items[p].item_id]   = prog.items[p].quantity_desired;
+          }
+        }
+        var items = [];
+        var rawItems = view.items || [];
+        for (var i = 0; i < rawItems.length; i += 1) {
+          var dec = await _decorateRegistryItem(rawItems[i]);
+          dec.desired   = desiredById[rawItems[i].id] != null ? desiredById[rawItems[i].id] : rawItems[i].quantity_desired;
+          dec.purchased = purchasedById[rawItems[i].id] || 0;
+          dec.remaining = remainingById[rawItems[i].id] != null ? remainingById[rawItems[i].id] : dec.desired;
+          items.push(dec);
+        }
+        var pubUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        // Build a redacted, public-safe registry view — only the fields a
+        // giver may see (title / occasion / event_date / message / privacy /
+        // status). The owner_customer_id + shipping_address_id are dropped
+        // here so they can NEVER reach the rendered HTML.
+        var reg = view.registry;
+        var publicReg = {
+          slug:       reg.slug,
+          title:      reg.title,
+          occasion:   reg.occasion,
+          event_date: reg.event_date,
+          message:    reg.message,
+          privacy:    reg.privacy,
+          status:     reg.status,
+        };
+        _send(res, 200, renderRegistryPublic({
+          registry:     publicReg,
+          items:        items,
+          notice:       pubUrl ? pubUrl.searchParams.get("ok") : null,
+          shop_name:    shopName,
+          cart_count:   await _cartCountForReq(req),
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      });
+
+      // POST /registry/:slug/items/:item_id/purchase — a giver records a gift
+      // (marks the item purchased). This is the mark-purchased / record-a-gift
+      // action the primitive's purchaseItem implements: it decrements the
+      // remaining-needed qty and tracks who bought it (anonymous by default).
+      // It carries NO payment — a giver who wants to actually buy the item
+      // adds it to their cart (the per-item "Add to cart" form posts to
+      // /cart/lines) and pays through the regular Stripe-gated checkout. A
+      // dedicated registry-funds settlement (charge the giver, route the money
+      // to the owner) is intentionally not wired: the normal cart/checkout path
+      // already lets a giver buy a registry item end-to-end, so it only lands
+      // if an operator needs registry-scoped fulfillment (ship-to-owner +
+      // gift-message capture) the standard order flow doesn't cover. The action
+      // is slug+item gated to the registry, NOT customer-scoped (a giver need
+      // not be logged in); it is shape-safe — a closed registry, an
+      // over-purchase, an unknown item, or a malformed slug all resolve to a
+      // clean redirect
+      // / 404, never a 500.
+      router.post("/registry/:slug/items/:item_id/purchase", async function (req, res) {
+        var slug = (req.params && req.params.slug) || "";
+        var itemId = (req.params && req.params.item_id) || "";
+        // Resolve through getBySlug so a private / unknown registry is never
+        // purchasable (the same privacy gate the GET view uses) — a giver can
+        // only act on a registry they could legitimately reach by link.
+        var view = null;
+        try { view = await deps.giftRegistry.getBySlug(slug); }
+        catch (_e) { view = null; }
+        // Same privacy gate as the GET view — a private (or unknown) registry
+        // is never publicly purchasable.
+        if (!view || !view.registry || view.registry.privacy === "private") {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isFinite(qty) || qty < 1) qty = 1;
+        // `reveal` requires a signed-in giver — an anonymous reveal makes no
+        // sense (there's no identity to surface). When the box is ticked and
+        // the giver is logged in, attribute the gift to them; otherwise the
+        // purchase is anonymous.
+        var reveal = (body.reveal === "1" || body.reveal === "on" || body.reveal === true);
+        var buyerId = null;
+        if (reveal) {
+          var giverAuth = null;
+          try { giverAuth = _currentCustomer(req); } catch (_e) { giverAuth = null; }
+          if (giverAuth && giverAuth.customer_id) buyerId = giverAuth.customer_id;
+          else reveal = false;   // not signed in → fall back to anonymous
+        }
+        var purchaseInput = {
+          registry_slug: slug,
+          item_id:       itemId,
+          quantity:      qty,
+          reveal_buyer:  reveal,
+        };
+        if (buyerId) purchaseInput.buyer_customer_id = buyerId;
+        try {
+          await deps.giftRegistry.purchaseItem(purchaseInput);
+        } catch (_e) {
+          // A closed registry, an over-purchase, an archived / unknown item,
+          // or a malformed slug/item id are all giver-recoverable: bounce
+          // back to the public registry page (no item landed) rather than
+          // 500. A truly unexpected error (non-TypeError, uncoded) still
+          // surfaces as a redirect — the page re-render shows current state.
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/registry/" + encodeURIComponent(slug));
+          return res.end ? res.end() : res.send("");
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/registry/" + encodeURIComponent(slug) + "?ok=gifted");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // Shared owner-route auth gate: resolve the session customer or send the
+      // redirect / 503 and return null. Mirrors the wishlist `_savedAuth`
+      // shape so every owner registry write funnels through one check.
+      function _registryAuthOrRedirect(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+
+      // Re-render the manage page with an inline error after a refused owner
+      // mutation (a bad sku, a duplicate item, a closed-registry write). A
+      // TypeError / coded over-purchase is operator-recoverable → 400 with the
+      // message; anything else is a 500.
+      async function _registryManageError(req, res, reg, e) {
+        var status = (e instanceof TypeError || (e && e.code === "GIFT_REGISTRY_OVER_PURCHASE")) ? 400 : 500;
+        // Reload current items so the error page shows live state.
+        var items = [];
+        try {
+          var view = await deps.giftRegistry.getBySlug(reg.slug);
+          var prog = await deps.giftRegistry.progressFor(reg.slug);
+          var remById = Object.create(null), purById = Object.create(null), desById = Object.create(null);
+          if (prog && prog.items) {
+            for (var p = 0; p < prog.items.length; p += 1) {
+              remById[prog.items[p].item_id] = prog.items[p].remaining;
+              purById[prog.items[p].item_id] = prog.items[p].purchased;
+              desById[prog.items[p].item_id] = prog.items[p].quantity_desired;
+            }
+          }
+          var rawItems = (view && view.items) || [];
+          for (var i = 0; i < rawItems.length; i += 1) {
+            var dec = await _decorateRegistryItem(rawItems[i]);
+            dec.desired   = desById[rawItems[i].id] != null ? desById[rawItems[i].id] : rawItems[i].quantity_desired;
+            dec.purchased = purById[rawItems[i].id] || 0;
+            dec.remaining = remById[rawItems[i].id] != null ? remById[rawItems[i].id] : dec.desired;
+            items.push(dec);
+          }
+        } catch (_e) { items = []; }
+        return _send(res, status, renderRegistryManage({
+          registry:     reg,
+          items:        items,
+          error:        status === 400 ? ((e && e.message) || "We couldn't make that change.") : "Something went wrong. Please try again.",
+          shop_name:    shopName,
+          cart_count:   await _cartCountForReq(req),
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      }
+    }
+
+    // Save for later — move a cart line into a per-customer holding
+    // list and back. Login required (the list is per-customer).
+    if (deps.saveForLater) {
+      function _savedAuth(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+
+      // POST /cart/lines/:line_id/save — move the line out of the cart
       // into the customer's saved list. Redirects back to /cart.
       router.post("/cart/lines/:line_id/save", async function (req, res) {
         var auth = _savedAuth(req, res);
@@ -11769,6 +12905,240 @@ function mount(router, deps) {
       });
     }
 
+    // Self-serve exchanges — a customer requests a same-value item SWAP
+    // (different size / colour / unit) against one of their own orders and
+    // tracks its status; operators action it via the admin /admin/exchanges
+    // queue. Distinct from returns (which end in a refund): an exchange
+    // ships the original back AND a replacement out, no money refunded.
+    //
+    // Ownership / IDOR: an order_exchanges row carries `order_id` but NOT
+    // `customer_id` — the customer→order linkage lives on the order. So
+    // every per-exchange / per-order route here loads the parent order and
+    // refuses (clean 404) unless `order.customer_id === auth.customer_id`,
+    // exactly like the returns + support gates. The exchange primitive
+    // moves a row by id alone, so the route owns the ownership decision.
+    if (deps.orderExchanges && deps.order) {
+      function _exchangeAuth(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+
+      // Load the order named in :order_id and confirm it belongs to the
+      // signed-in customer. A malformed id (guardUuid TypeError), a missing
+      // order, or someone else's order all return 404 — never a 500, never
+      // a leak. This is the ownership gate the request form + POST funnel
+      // through.
+      async function _ownedOrderForExchange(req, res, auth) {
+        var order;
+        try { order = await deps.order.get(req.params && req.params.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return order;
+      }
+
+      // Load the exchange named in :id, then load its parent order and
+      // confirm THAT order belongs to the signed-in customer. The exchange
+      // row has no customer_id, so ownership is asserted transitively
+      // through the order. A malformed id (TypeError), an unknown exchange,
+      // an exchange whose order is gone, or an exchange owned by someone
+      // else ALL return 404 — never a 500, never a cross-customer reveal.
+      async function _ownedExchange(req, res, auth) {
+        var exchange;
+        try { exchange = await deps.orderExchanges.getExchange(req.params && req.params.id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!exchange) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+        var order;
+        try { order = await deps.order.get(exchange.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return exchange;
+      }
+
+      // Resolve the sibling variants a line's product can be swapped to:
+      // every active variant of the same product, labelled by its option
+      // values (falling back to the SKU). Best-effort — absent the catalog
+      // handle (or a read failure) the line offers a same-SKU swap.
+      async function _replacementOptions(line) {
+        if (!deps.catalog || !line || !line.variant_id) return [];
+        try {
+          var v = await deps.catalog.variants.get(line.variant_id);
+          if (!v) return [];
+          var siblings = await deps.catalog.variants.listForProduct(v.product_id);
+          return (siblings || []).map(function (s) {
+            var optLabel = s.options
+              ? Object.keys(s.options).map(function (k) { return s.options[k]; }).join(" / ")
+              : "";
+            var label = (optLabel ? optLabel + " — " : "") + s.sku;
+            return { id: s.id, sku: s.sku, label: label };
+          });
+        } catch (_e) { return []; }
+      }
+
+      // The customer's own exchange list, scoped to their orders. The
+      // primitive resolves the customer→order linkage through the injected
+      // order handle, so a foreign order's exchange never appears here.
+      router.get("/account/exchanges", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchanges = [];
+        try { exchanges = await deps.orderExchanges.exchangesForCustomer(auth.customer_id, { limit: 100 }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; exchanges = []; }
+        var cartCount = await _cartCountForReq(req);
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _send(res, 200, renderExchanges({
+          exchanges:  exchanges,
+          requested:  url && url.searchParams.get("ok") === "1",
+          shop_name:  shopName,
+          cart_count: cartCount,
+        }));
+      });
+
+      // One exchange's status detail. Ownership-scoped through the parent
+      // order (foreign / unknown → 404).
+      router.get("/account/exchanges/:id", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchange = await _ownedExchange(req, res, auth); if (!exchange) return;
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderExchangeDetail({ exchange: exchange, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      // The exchange-request form for one of the customer's own orders,
+      // gated on the same eligibility window as a return.
+      router.get("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var cartCount = await _cartCountForReq(req);
+        if (!_orderEligibleForExchange(order.status)) {
+          return _send(res, 400, renderExchangeForm({
+            order: order, lines: [], notice: "This order isn't eligible for an exchange.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
+        var lines = [];
+        var orderLines = order.lines || [];
+        for (var i = 0; i < orderLines.length; i += 1) {
+          var ol = orderLines[i];
+          lines.push(Object.assign({}, ol, { replacement_options: await _replacementOptions(ol) }));
+        }
+        _send(res, 200, renderExchangeForm({ order: order, lines: lines, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.post("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var body = req.body || {};
+        var cartCount = await _cartCountForReq(req);
+
+        // Re-decorate the lines so a failed POST re-renders the same form
+        // (with the replacement pickers intact) rather than a bare page.
+        async function _decoratedLines() {
+          var out = [];
+          var ols = order.lines || [];
+          for (var i = 0; i < ols.length; i += 1) {
+            out.push(Object.assign({}, ols[i], { replacement_options: await _replacementOptions(ols[i]) }));
+          }
+          return out;
+        }
+        function _badForm(notice, status) {
+          return _decoratedLines().then(function (lines) {
+            return _send(res, status || 400, renderExchangeForm({
+              order: order, lines: lines, notice: notice,
+              shop_name: shopName, cart_count: cartCount,
+            }));
+          });
+        }
+
+        if (!_orderEligibleForExchange(order.status)) {
+          return _badForm("This order isn't eligible for an exchange.");
+        }
+
+        // Resolve the picked line from the order's OWN lines (authoritative
+        // sku/qty) — never trust a client-supplied sku. The radio carries
+        // the order_line id.
+        var orderLines = order.lines || [];
+        var picked = null;
+        for (var i = 0; i < orderLines.length; i += 1) {
+          if (orderLines[i].id === body.line_id) { picked = orderLines[i]; break; }
+        }
+        if (!picked) return _badForm("Pick the item you'd like to exchange.");
+
+        var wantedQty = parseInt(body["qty_" + picked.id], 10);
+        var maxQty = Number(picked.qty) || 1;
+        var qty = Number.isFinite(wantedQty) && wantedQty >= 1 && wantedQty <= maxQty ? wantedQty : maxQty;
+
+        // The replacement variant: the chosen sibling variant of the same
+        // product. The select carries the variant id; resolve it back to a
+        // sku through the catalog (never trust a client sku). Absent a
+        // selection (a same-SKU swap — replace a defective unit) the
+        // replacement defaults to the line's own sku/variant.
+        var replacementSku = picked.sku;
+        var replacementVariantId = picked.variant_id;
+        var chosen = body["replacement_" + picked.id];
+        if (chosen && deps.catalog) {
+          // The replacement MUST be one of the sibling variants offered for
+          // the purchased line's product. Validate the chosen id against the
+          // same option set the form was built from (_replacementOptions) —
+          // resolving it through a bare variants.get would accept ANY catalog
+          // variant, letting a forged replacement_<id> swap a cheap item for
+          // any variant in the catalog. The option carries the catalog-
+          // resolved sku/id, so a client sku is never trusted.
+          var options = await _replacementOptions(picked);
+          var match = null;
+          for (var oi = 0; oi < options.length; oi += 1) {
+            if (options[oi].id === chosen) { match = options[oi]; break; }
+          }
+          if (!match) return _badForm("That replacement variant isn't available — pick another.");
+          replacementSku = match.sku;
+          replacementVariantId = match.id;
+        }
+
+        try {
+          await deps.orderExchanges.requestExchange({
+            order_id:               order.id,
+            line_id:                picked.id,
+            return_sku:             picked.sku,
+            return_qty:             qty,
+            replacement_sku:        replacementSku,
+            replacement_variant_id: replacementVariantId,
+            replacement_qty:        qty,
+            reason:                 body.reason,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) {
+            return _badForm((e && e.message || "").replace(/^order-exchanges[.:]\s*/, "") || "Please check your exchange request.");
+          }
+          throw e;
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/exchanges?ok=1");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Support tickets — the signed-in customer raises a ticket, lists
     // their own, reads a thread, and replies. EVERY route is login-gated
     // AND scoped to the session customer's id: the support primitive