@blamejs/blamejs-shop 0.0.126 → 0.0.128

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.128 (2026-05-25) — **Collections — browse curated and smart product lists at /collections.** The storefront now has real collection pages. `/collections` lists the shop's active collections, and `/collections/:slug` shows a collection's products as a grid — resolving both operator-curated manual collections (hand-picked members) and smart collections (rule-matched against the catalog). The footer links to it from every page, so collections are a first-class browse entry point rather than a search query. Unknown or malformed collection slugs return 404, never a 500. **Added:** *Collection browse pages* — `GET /collections` renders the active collections as cards (title, description, hero); `GET /collections/:slug` renders the collection's product grid, reusing the standard product card (image, title, price, link to the PDP). Public pages — no sign-in. · *Manual + smart resolution* — Manual collections list their hand-picked members; smart collections evaluate their stored rules against the active catalog and apply the collection's sort strategy. The page resolves each product fresh, so archived products drop out of the grid. · *Footer entry point* — The footer's Shop column links to `/collections` on every storefront page (edge- and container-rendered alike), making collections a real browse path. A bad or unknown slug is a 404.
+
+- v0.0.127 (2026-05-24) — **Self-serve returns — customers request RMAs on their orders, operators approve and refund.** Signed-in customers can request a return against one of their own orders — pick the items and a reason at the order, then track status at /account/returns. Operators work the queue at /admin/returns: approve (with a refund amount), mark received, refund, or reject with a reason, following the pending → approved → received → refunded lifecycle. The customer request route loads the order and confirms it belongs to the signed-in customer before showing it, and builds the return lines from the order's own records, so a foreign or guessed order id returns 404 and a client can't return items it never bought. **Added:** *Customer return requests + status* — `/account/orders/:order_id/return` shows the order's items with a reason picker; `/account/returns` lists the customer's RMAs with status (pending / approved / received / refunded / rejected) and any rejection reason. The account dashboard links to it. Empty selection or a bad reason re-renders the form with the message. · *Operator return queue* — `GET /admin/returns?status=pending` lists the queue across all orders; `GET /admin/returns/:id` reads one; `POST /admin/returns/:id/approve` (with refund amount), `/received`, `/refund`, and `/reject` (with reason) walk the lifecycle. Bearer-token-gated; an illegal transition is a 409 and a bad id a 404, never a 500. · *`returns.listByStatus(status, opts)`* — Lists return authorizations across all orders by status, newest first, with the same opaque cursor as `listForCustomer`. Backs the operator queue.
+
 - v0.0.126 (2026-05-24) — **Address book — saved shipping and billing addresses on the account page.** Signed-in customers can now keep a book of addresses at /account/addresses: add, edit, set a default shipping or billing address, and remove. Addresses are per-customer; every action that targets a specific address first confirms it belongs to the signed-in customer, so a guessed id can't read or change someone else's address. **Added:** *Address book at `/account/addresses`* — List, add, and edit saved addresses (recipient, company, two street lines, city, region, postal code, ISO country, phone). The account dashboard links to it. A blank product catalog isn't required — this is account surface only. · *Default shipping / billing* — Mark one address as the default shipping and one as the default billing; promoting a new default clears the previous one. Surfaced as badges on each card. · *Ownership-checked mutations* — Edit, update, set-default, and remove all resolve the address by id and verify it belongs to the signed-in customer before acting — a foreign or guessed id returns 404, never another customer's data. Add/edit re-render the form with the validation message on bad input.
 
 - v0.0.124 (2026-05-24) — **Save for later — move cart items into a holding list and back.** Each cart line now has a "Save for later" control that moves the item out of the cart into a per-customer holding list without losing it. Saved items live on a new account page where they can be moved back to the cart or removed. Moving an item back reprices it to the current catalog price and checks stock first, so a saved item that sold out (and isn't backorderable) can't silently re-enter the cart. Login-required, since the list is scoped to one customer. **Added:** *Save-for-later control on cart lines* — Each editable cart line gets a Save-for-later control. `POST /cart/lines/:line_id/save` moves the line out of the cart into the customer's saved list (`moveFromCart`). Login-gated — a signed-out shopper is redirected to sign in. · *`/account/saved` — the holding list* — A new account page lists saved items with a thumbnail, the saved price for reference, and Move-to-cart / Remove controls. Items whose product was archived render as "no longer available" rather than breaking the list. The account dashboard links to it (alongside Wishlist). · *Move back to cart, repriced + stock-checked* — `POST /saved/:save_id/move-to-cart` returns the item to the session cart at the current catalog price (not the stale snapshot) and refuses if the SKU is out of stock and not backorderable. `POST /saved/:save_id/remove` drops a saved row.

package/README.md

@@ -67,9 +67,11 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/wishlist.js`** | Per-customer saved products. The PDP renders a login-gated "Save to wishlist" toggle and a "N shoppers saved this" social-proof count; `/account/wishlist` lists saved items (remove + reopen, orphan-tolerant when a product is archived). `POST /wishlist/toggle` is idempotent (`INSERT OR IGNORE`) and redirects to the canonical product slug or a safe same-origin `return_to`. UUID-shape-validated ids, `b.pagination` HMAC cursors. |
 | **`lib/save-for-later.js`** | Per-customer cart holding list. Each cart line gets a login-gated "Save for later" control (`POST /cart/lines/:id/save` → `moveFromCart`); `/account/saved` lists items with Move-to-cart / Remove. `moveToCart` reprices to the current catalog price and stock-gates (out-of-stock + non-backorderable is refused). Composes `catalog.inventory` + `catalog.prices` + `catalog.variants`. |
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
+| **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
+| **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 
@@ -88,6 +90,8 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0012_wishlist.sql` — per-customer saved products (unique customer + product + variant)
 - `migrations-d1/0041_save_for_later.sql` — per-customer cart holding list (price snapshot + source line)
 - `migrations-d1/0026_customer_addresses.sql` — per-customer address book (default shipping/billing flags)
+- `migrations-d1/0023_returns.sql` — return authorizations + lines (RMA lifecycle FSM)
+- `migrations-d1/0043_collections.sql` — manual + smart product collections (members + rules + sort strategy)
 
 ### Demo seed
 

package/lib/admin.js

@@ -163,6 +163,7 @@ function mount(router, deps) {
   var assetPrefix   = typeof deps.asset_prefix === "string" ? deps.asset_prefix : "/assets/";
   var catalogImport = deps.catalogImport || null;   // bulk-import route disabled when absent
   var reviews       = deps.reviews       || null;   // moderation endpoints disabled when absent
+  var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
 
   try { _b().audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -580,6 +581,118 @@ function mount(router, deps) {
     }));
   }
 
+  // ---- returns (moderation) -------------------------------------------
+
+  // Operator-side RMA moderation. The queue lists return
+  // authorizations across all orders in one status (defaults to
+  // `pending`); approve / received / refund / reject walk the same FSM
+  // the customer-facing request path leaves in `pending`. A bad state
+  // transition (e.g. refund-from-pending) and a malformed :id both
+  // surface as client errors (4xx), never a 500. Endpoints are omitted
+  // entirely when no returns primitive is wired.
+  if (returns) {
+    function _returnsClientError(e) {
+      // A transition refused by the FSM or a not-found row is the
+      // caller's problem, not the server's. `_currentStatus` raises a
+      // not-found TypeError; `_assertTransition` raises an Error tagged
+      // RMA_TRANSITION_REFUSED. Map both to 4xx. (Bad-shape input is a
+      // plain TypeError, which the wrapper already maps to 400.)
+      if (!e) return null;
+      if (e.code === "RMA_NOT_FOUND") return { status: 404, slug: "return-not-found" };
+      if (e.code === "RMA_TRANSITION_REFUSED") return { status: 409, slug: "return-transition-refused" };
+      return null;
+    }
+
+    router.get("/admin/returns", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var status = (url && url.searchParams.get("status")) || "pending";
+      var cursor = url && url.searchParams.get("cursor");
+      var limitS = url && url.searchParams.get("limit");
+      var limit  = limitS == null ? undefined : parseInt(limitS, 10);
+      var page = await returns.listByStatus(status, { cursor: cursor || undefined, limit: limit });
+      _json(res, 200, page);
+    }));
+
+    router.get("/admin/returns/:id", R(async function (req, res) {
+      var rma;
+      try {
+        rma = await returns.get(req.params.id);
+      } catch (e) {
+        // A non-UUID :id raises a guardUuid TypeError — surface it as a
+        // 404 (the route is a defensive request-shape reader, never a
+        // 500). Re-raise anything that isn't the bad-id shape so the
+        // wrapper's generic handling applies.
+        if (e instanceof TypeError) return _problem(res, 404, "return-not-found");
+        throw e;
+      }
+      if (!rma) return _problem(res, 404, "return-not-found");
+      _json(res, 200, rma);
+    }));
+
+    router.post("/admin/returns/:id/approve", W("return.approve", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.approve(req.params.id, {
+          refund_amount_minor: body.refund_amount_minor,
+          refund_currency:     body.refund_currency,
+          operator_notes:      body.operator_notes,
+        });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/received", W("return.received", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.markReceived(req.params.id, { operator_notes: body.operator_notes });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/refund", W("return.refund", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.refund(req.params.id, { operator_notes: body.operator_notes });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/reject", W("return.reject", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.reject(req.params.id, {
+          rejected_reason: body.rejected_reason,
+          operator_notes:  body.operator_notes,
+        });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+  }
+
   // ---- config ---------------------------------------------------------
 
   var config = deps.config || null;

package/lib/returns.js

@@ -516,6 +516,57 @@ function create(opts) {
       return { rows: rows, next_cursor: next };
     },
 
+    listByStatus: async function (status, listOpts) {
+      var statusFilter = _status(status);
+      listOpts = listOpts || {};
+      var limit = listOpts.limit == null ? DEFAULT_LIST_LIMIT : listOpts.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIST_LIMIT) {
+        throw new TypeError("returns.listByStatus: limit must be 1..." + MAX_LIST_LIMIT);
+      }
+      var cursorVals = null;
+      if (listOpts.cursor != null) {
+        if (typeof listOpts.cursor !== "string") {
+          throw new TypeError("returns.listByStatus: cursor must be an opaque string or null");
+        }
+        try {
+          var state = _b().pagination.decodeCursor(listOpts.cursor, cursorSecret);
+          if (JSON.stringify(state.orderKey) !== JSON.stringify(RMA_ORDER_KEY)) {
+            throw new TypeError("returns.listByStatus: cursor orderKey mismatch");
+          }
+          cursorVals = state.vals;
+        } catch (e) {
+          if (e instanceof TypeError) throw e;
+          throw new TypeError("returns.listByStatus: cursor — " + (e && e.message || "malformed"));
+        }
+      }
+
+      var sql, params;
+      if (cursorVals) {
+        sql = "SELECT * FROM return_authorizations WHERE status = ?1 AND " +
+              "(created_at < ?2 OR (created_at = ?2 AND id < ?3)) " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?4";
+        params = [statusFilter, cursorVals[0], cursorVals[1], limit];
+      } else {
+        sql = "SELECT * FROM return_authorizations WHERE status = ?1 " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?2";
+        params = [statusFilter, limit];
+      }
+      var rows = (await query(sql, params)).rows;
+      for (var i = 0; i < rows.length; i += 1) {
+        await _hydrate(rows[i]);
+      }
+      var last = rows[rows.length - 1];
+      var next = null;
+      if (last && rows.length === limit) {
+        next = _b().pagination.encodeCursor({
+          orderKey: RMA_ORDER_KEY,
+          vals:     [last.created_at, last.id],
+          forward:  true,
+        }, cursorSecret);
+      }
+      return { rows: rows, next_cursor: next };
+    },
+
     summaryForOperator: async function (input) {
       input = input || {};
       var from = _epochOrNull(input.from, "from");

package/lib/storefront.js

@@ -137,6 +137,7 @@ var LAYOUT =
   "        <h4>Shop</h4>\n" +
   "        <ul>\n" +
   "          <li><a href=\"/\">All products</a></li>\n" +
+  "          <li><a href=\"/collections\">Collections</a></li>\n" +
   "          <li><a href=\"/?sort=new\">New arrivals</a></li>\n" +
   "          <li><a href=\"/?sort=sale\">On sale</a></li>\n" +
   "          <li><a href=\"/cart\">Cart</a></li>\n" +
@@ -1134,6 +1135,184 @@ function renderAddresses(opts) {
   });
 }
 
+// Storefront collection index — operator-curated + smart product lists.
+function renderCollectionList(opts) {
+  var esc = _b().template.escapeHtml;
+  var cols = opts.collections || [];
+  var cardsHtml = "";
+  for (var i = 0; i < cols.length; i += 1) {
+    var c = cols[i];
+    var media = c.hero_image_url
+      ? "<figure class=\"collection-index-card__media\"><img src=\"" + esc((opts.asset_prefix || "/assets/") + c.hero_image_url) + "\" alt=\"" + esc(c.title) + "\" loading=\"lazy\"></figure>"
+      : "<figure class=\"collection-index-card__media collection-index-card__media--empty\" aria-hidden=\"true\"></figure>";
+    cardsHtml +=
+      "<a class=\"collection-index-card\" href=\"/collections/" + esc(c.slug) + "\">" +
+        media +
+        "<div class=\"collection-index-card__meta\">" +
+          "<h2 class=\"collection-index-card__title\">" + esc(c.title) + "</h2>" +
+          (c.description ? "<p class=\"collection-index-card__desc\">" + esc(c.description) + "</p>" : "") +
+        "</div>" +
+      "</a>";
+  }
+  var inner = cardsHtml
+    ? "<div class=\"collection-index-grid\">" + cardsHtml + "</div>"
+    : "<p class=\"collection-empty\">No collections yet.</p>";
+  var body =
+    "<section class=\"collection-index\">" +
+      "<header class=\"section-head\"><p class=\"eyebrow\">Browse</p>" +
+        "<h1 class=\"section-head__title\">Collections</h1></header>" +
+      inner +
+    "</section>";
+  return _wrap({
+    title: "Collections", shop_name: opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css, body: body,
+  });
+}
+
+// A single collection's page — title + description + product grid. The
+// route resolves each member product into the { slug, title, price,
+// image_url } shape `_buildProductCard` expects.
+function renderCollection(opts) {
+  var esc = _b().template.escapeHtml;
+  var col = opts.collection;
+  var products = opts.products || [];
+  var cards = products.map(function (p) { return _buildProductCard(p); }).join("");
+  var grid = cards
+    ? "<div class=\"catalog-grid collection-grid\">" + cards + "</div>"
+    : "<p class=\"collection-empty\">No products in this collection yet.</p>";
+  var body =
+    "<section class=\"collection-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/\">Shop</a></li>" +
+        "<li><a href=\"/collections\">Collections</a></li>" +
+        "<li aria-current=\"page\">" + esc(col.title) + "</li>" +
+      "</ol></nav>" +
+      "<header class=\"collection-page__head\">" +
+        "<h1 class=\"collection-page__title\">" + esc(col.title) + "</h1>" +
+        (col.description ? "<p class=\"collection-page__desc\">" + esc(col.description) + "</p>" : "") +
+      "</header>" +
+      grid +
+    "</section>";
+  return _wrap({
+    title: col.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,
+  });
+}
+
+var RETURN_REASONS = [
+  ["defective", "Defective / doesn't work"],
+  ["wrong-item", "Wrong item received"],
+  ["not-as-described", "Not as described"],
+  ["no-longer-needed", "No longer needed"],
+  ["damaged-in-transit", "Damaged in transit"],
+  ["other", "Other"],
+];
+
+function _returnStatusBadge(status) {
+  return "<span class=\"return-status return-status--" + _b().template.escapeHtml(String(status)) + "\">" +
+    _b().template.escapeHtml(String(status)) + "</span>";
+}
+
+// Customer-facing return-request form for one order. `opts.order` is the
+// order row, `opts.lines` its order_lines. `opts.notice` is an optional
+// error bounced back from a failed POST.
+function renderReturnForm(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];
+    lineRows +=
+      "<li class=\"return-line\">" +
+        "<label class=\"return-line__pick\">" +
+          "<input type=\"checkbox\" name=\"return_" + esc(l.id) + "\" value=\"1\">" +
+          "<span class=\"return-line__sku\"><code>" + esc(l.sku) + "</code></span>" +
+        "</label>" +
+        "<label class=\"return-line__qty\">Qty to return " +
+          "<input type=\"number\" name=\"qty_" + esc(l.id) + "\" value=\"" + (Number(l.qty) || 1) + "\" min=\"1\" max=\"" + (Number(l.qty) || 1) + "\">" +
+          " <span class=\"return-line__of\">of " + (Number(l.qty) || 1) + "</span>" +
+        "</label>" +
+      "</li>";
+  }
+  var reasonOpts = RETURN_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/returns\">Returns</a></li>" +
+        "<li aria-current=\"page\">Request a return</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"return-form-page__title\">Request a return</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) + "/return\">" +
+        "<fieldset class=\"return-form__lines\"><legend>Which items?</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>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Notes (optional)</span>" +
+          "<textarea name=\"customer_notes\" maxlength=\"2000\" rows=\"4\"></textarea></label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Request return</button>" +
+      "</form>" +
+    "</section>";
+  return _wrap({
+    title:      "Request a return",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// Customer's return-authorization list.
+function renderReturns(opts) {
+  var esc = _b().template.escapeHtml;
+  var rmas = opts.rmas || [];
+  var rowsHtml = "";
+  for (var i = 0; i < rmas.length; i += 1) {
+    var r = rmas[i];
+    var date = r.created_at ? new Date(Number(r.created_at)).toISOString().slice(0, 10) : "";
+    rowsHtml +=
+      "<li class=\"return-card\">" +
+        "<div class=\"return-card__head\">" +
+          "<code class=\"return-card__rma\">" + esc(r.rma_code) + "</code>" +
+          _returnStatusBadge(r.status) +
+        "</div>" +
+        "<p class=\"return-card__meta\">" + esc(String(r.reason || "")) +
+          (date ? " &middot; <time datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+          (Number(r.refund_amount_minor) > 0 ? " &middot; refund " + esc(pricing.format(Number(r.refund_amount_minor), r.refund_currency || "USD")) : "") +
+        "</p>" +
+        (r.status === "rejected" && r.rejected_reason ? "<p class=\"return-card__reject\">" + esc(String(r.rejected_reason)) + "</p>" : "") +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"return-list\">" + rowsHtml + "</ul>"
+    : "<p class=\"return-empty\">No returns yet. Start one from an order in your account.</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\">Returns</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Returns</h1>" +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      "Returns",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Product-level "Save to wishlist" control + social-proof count.
 // Byte-compatible with the edge renderer (`worker/render/product.js`)
 // so both paths emit identical markup. Action-only label — the toggle
@@ -2066,6 +2245,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/wishlist\">Wishlist</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/saved\">Saved for later</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/addresses\">Addresses</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
   "      <form method=\"post\" action=\"/account/logout\"><button type=\"submit\" class=\"btn-ghost\">Sign out</button></form>\n" +
   "    </div>\n" +
   "  </header>\n" +
@@ -2356,6 +2536,69 @@ function mount(router, deps) {
     _send(res, 200, html);
   });
 
+  // Collections — operator-curated + smart product lists. Public browse
+  // pages; mounted when the collections primitive is wired.
+  if (deps.collections) {
+    var _collAssetPrefix = deps.asset_prefix || "/assets/";
+
+    // Decorate a product id into the { slug, title, price, image_url }
+    // shape _buildProductCard expects. Returns null for an archived /
+    // missing product so it drops out of the grid.
+    async function _decorateCollectionProduct(pid) {
+      var product = await deps.catalog.products.get(pid);
+      if (!product || product.status !== "active") return null;
+      var priceStr = "—";
+      var variants = await deps.catalog.variants.listForProduct(pid);
+      if (variants.length) {
+        var pr = await deps.catalog.prices.current(variants[0].id, "USD");
+        if (pr) priceStr = pricing.format(pr.amount_minor, pr.currency);
+      }
+      var media = await deps.catalog.media.listForProduct(pid);
+      var hero = media.length ? media[0] : null;
+      return {
+        slug:      product.slug,
+        title:     product.title,
+        price:     priceStr,
+        image_url: hero ? (_collAssetPrefix + hero.r2_key) : null,
+        image_alt: hero ? (hero.alt_text || product.title) : null,
+      };
+    }
+
+    router.get("/collections", async function (req, res) {
+      var cols = await deps.collections.list({ active_only: true });
+      var cartCount = await _cartCountForReq(req);
+      _send(res, 200, renderCollectionList({
+        collections: cols, shop_name: shopName, cart_count: cartCount, asset_prefix: _collAssetPrefix,
+      }));
+    });
+
+    router.get("/collections/:slug", async function (req, res) {
+      var slug = req.params && req.params.slug;
+      // get() and productsIn() both throw on a malformed slug (the
+      // primitive validates shape). A bad path segment is a 404, not a
+      // 500 — the route is a defensive request-shape reader.
+      var col, result;
+      try {
+        col = slug ? await deps.collections.get(slug) : null;
+        if (!col || col.archived_at != null) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        result = await deps.collections.productsIn({ slug: slug, limit: 24 });
+      } catch (e) {
+        if (e instanceof TypeError) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        throw e;
+      }
+      var products = [];
+      for (var i = 0; i < result.rows.length; i += 1) {
+        var pid = result.rows[i].product_id || result.rows[i].id;
+        var card = await _decorateCollectionProduct(pid);
+        if (card) products.push(card);
+      }
+      var cartCount = await _cartCountForReq(req);
+      _send(res, 200, renderCollection({
+        collection: col, products: products, shop_name: shopName, cart_count: cartCount,
+      }));
+    });
+  }
+
   router.get("/cart", async function (req, res) {
     var sid = _readSidCookie(req);
     if (!sid) {
@@ -3214,6 +3457,102 @@ function mount(router, deps) {
       _addrAction("archive",          function (id) { return deps.addresses.archive(id); });
     }
 
+    // Self-serve returns — a customer requests an RMA against one of
+    // their own orders and tracks its status. Operators action it via
+    // the admin /admin/returns queue. Needs the returns primitive + an
+    // order handle (to load + ownership-check the order being returned).
+    if (deps.returns && deps.order) {
+      function _returnsAuth(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 of another customer's order.
+      async function _ownedOrder(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;
+      }
+
+      router.get("/account/returns", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var page = await deps.returns.listForCustomer(auth.customer_id, { limit: 50 });
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderReturns({ rmas: page.rows, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.get("/account/orders/:order_id/return", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var order = await _ownedOrder(req, res, auth); if (!order) return;
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderReturnForm({ order: order, lines: order.lines || [], shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.post("/account/orders/:order_id/return", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var order = await _ownedOrder(req, res, auth); if (!order) return;
+        var body = req.body || {};
+        var cartCount = await _cartCountForReq(req);
+        // Build the return lines from the order's own lines (authoritative
+        // sku/qty), keyed by the checkboxes the customer ticked — never
+        // trust a client-supplied sku.
+        var orderLines = order.lines || [];
+        var picked = [];
+        for (var i = 0; i < orderLines.length; i += 1) {
+          var ol = orderLines[i];
+          if (body["return_" + ol.id] !== "1") continue;
+          var wanted = parseInt(body["qty_" + ol.id], 10);
+          var qty = Number.isFinite(wanted) && wanted >= 1 && wanted <= ol.qty ? wanted : ol.qty;
+          picked.push({ order_line_id: ol.id, sku: ol.sku, qty: qty });
+        }
+        if (picked.length === 0) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: orderLines, notice: "Select at least one item to return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
+        try {
+          await deps.returns.request({
+            order_id:       order.id,
+            customer_id:    auth.customer_id,
+            reason:         body.reason,
+            customer_notes: body.customer_notes,
+            lines:          picked,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) {
+            return _send(res, 400, renderReturnForm({
+              order: order, lines: orderLines, notice: (e && e.message) || "Please check your return request.",
+              shop_name: shopName, cart_count: cartCount,
+            }));
+          }
+          throw e;
+        }
+        res.status(303); res.setHeader && res.setHeader("location", "/account/returns");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Product reviews — submission requires a logged-in customer AND a
     // verified purchase of the product (the gate, not just a badge).
     // Only mounts when both the reviews primitive and an order handle

package/lib/vendor/MANIFEST.json

@@ -3,8 +3,8 @@
   "_about": "blamejs.shop vendors a single framework — blamejs — which itself bundles every server-side crypto/identity dependency. The transitive packages blamejs ships are surfaced in its own MANIFEST.json at lib/vendor/blamejs/lib/vendor/MANIFEST.json — Trivy / Grype rely on that nested data for CVE attribution.",
   "packages": {
     "blamejs": {
-      "version": "0.12.32",
-      "tag": "v0.12.32",
+      "version": "0.12.39",
+      "tag": "v0.12.39",
       "license": "Apache-2.0",
       "author": "blamejs contributors",
       "source": "https://github.com/blamejs/blamejs",
@@ -13,7 +13,7 @@
         "server": "lib/vendor/blamejs/"
       },
       "bundler": "shallow git clone of release tag from github.com/blamejs/blamejs",
-      "bundledAt": "2026-05-24"
+      "bundledAt": "2026-05-25"
     }
   }
 }