@blamejs/blamejs-shop 0.2.20 → 0.2.22

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.2.x
 
+- v0.2.22 (2026-05-29) — **See your full order history, track shipments, reorder, and request returns.** The customer order surface is now complete end-to-end. A new order-history list shows every order (cursor-paginated), and each order page gains a status timeline, a carrier tracking panel (tracking number + the carrier's public tracking link), a one-click Reorder that rebuilds a cart from the order, and a Request-a-return button for eligible orders — the same Reorder/Return actions also appear per row on the account dashboard and the history list. On the operator side, the admin order screen gets a shipment panel to attach a carrier + tracking number and record shipment events, and the returns console's Refund now issues the payment-provider refund first (then records the RMA) whenever the order has a captured charge, so a return can't be marked refunded while the customer is left un-refunded; manual/guest orders with no charge fall back to an explicit record-only step. **Added:** *Order history + tracking + reorder + returns (customer)* — `/account/orders` lists all your orders with pagination; each order page shows a status timeline and carrier tracking, plus Reorder (`POST /orders/:id/reorder` rebuilds a cart from the order's lines at current prices) and Request-a-return for eligible orders. The dashboard and history rows carry the same actions. · *Shipment + tracking panel (admin)* — The admin order detail screen can attach a shipment (carrier + tracking number) and record shipment events; marking delivered advances the order's lifecycle. Tracking the order surfaces the carrier's public tracking link to the customer. **Changed:** *Return refunds move the money* — The returns console Refund action now issues the payment-provider refund first and records the RMA only on success when the order has a captured charge, so an approved return is never marked refunded without the customer actually being refunded. Orders with no captured charge use an explicit record-only step that points to the order.
+
+- v0.2.21 (2026-05-29) — **Related products ("You may also like") on the product page.** Product pages now show a related-products rail. The picks are the other products in the product's primary collection, ordered deterministically and capped at four, rendered with the same product-card markup the home and search grids use — identical on the edge and origin paths. The rail is hidden when a product has no related items. This surfaces existing catalog relationships to shoppers without any new data or configuration. **Added:** *Related-products rail on the PDP* — A "You may also like" section on each product page lists other active products from the same primary collection (deterministic order, up to four), using the standard product-card markup byte-identically across the edge and origin renders. Hidden when there are no related products.
+
 - v0.2.20 (2026-05-29) — **Manage a subscription yourself — pause, skip, change, or reactivate.** The subscriptions account screen previously only let a customer cancel. It now exposes the full self-service set: pause and resume, skip the next shipment, change the quantity, change the delivery frequency, and reactivate a recently-cancelled subscription within its grace window. Each action is state-gated (only the controls that apply to a subscription's current state are shown), confirm-aware where it changes billing, and reports back with a status notice. No more cancelling just to make a change. **Added:** *Subscription self-management* — `/account/subscriptions` gains Pause / Resume, Skip next shipment, Change quantity, Change frequency, and Reactivate (within the grace window) alongside Cancel. Controls are shown only when valid for the subscription's state; quantity and frequency are validated server-side; pause and cancel go through a confirmation step.
 
 - v0.2.19 (2026-05-29) — **Search results render the same product cards as the rest of the store.** A product with no image showed an outdated, text-only card on the search-results page when that page was served from the edge, while the home and category grids (and the origin-rendered search page) used the current placeholder-illustration card. The edge search page now emits the same card markup as every other grid, so a no-image product looks identical wherever it appears. A render-level parity check now pins the search page's markup byte-for-byte across the edge and origin paths so this kind of drift is caught automatically. **Fixed:** *Consistent no-image product card on search* — The edge-rendered search results page used a stale text-only card for products without a hero image; it now renders the placeholder-illustration card used across the rest of the storefront, byte-identical to the origin render.

package/README.md

@@ -87,7 +87,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/giftcards.js`** | Prepaid bearer gift cards. `issue({ amount_minor, currency })` generates a 16-char code (32-glyph alphabet, no ambiguous letters) via `b.crypto.generateBytes`, stores only its `namespaceHash` digest + a 4-char hint, and returns the plaintext code once. `balance(code)` / `lookup(code)` resolve a code to its live balance (constant-time hash compare); `redeem({ code, order_id, amount_minor })` decrements the balance with an atomic `balance >= amount` SQL guard so concurrent spends can't overdraw. Redeemed at checkout as a credit against the order grand total: the amount due drops by the applied balance (never below zero), the order still records the full total it owed, and the debit is recorded once per order — a card that fully covers the order is marked paid with no Stripe charge. Customers check a balance at `GET /gift-cards`; the page is not a code-existence oracle (unknown / malformed / expired all return the same generic not-found). |
 | **`lib/gift-card-ledger.js`** | Append-only credit / debit / expire history per gift card, with a denormalized `balance_after_minor` snapshot for O(1) balance reads. `credit` / `debit` / `expire` write one row each; `history(id)` paginates a card's transactions; `transactionsForOrder(id)` lists a card's movements for one order. The audit trail behind the admin gift-card ledger console; overdraft is refused at the primitive layer. |
 | **`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 + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules + coupon-stacking policies — create / edit / archive each. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, and Discounts links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
+| **`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. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules + coupon-stacking policies — create / edit / archive each. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, and Discounts links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
 | **`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. |
 

package/lib/admin.js

@@ -315,6 +315,7 @@ function mount(router, deps) {
   var productQa     = deps.productQa     || null;   // Q&A moderation endpoints disabled when absent
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
   var customers     = deps.customers     || null;   // read-only customers console disabled when absent
+  var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
 
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
@@ -1175,6 +1176,21 @@ function mount(router, deps) {
         shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
       }));
       var url = req.url ? new URL(req.url, "http://localhost") : null;
+      // Shipment + carrier-event ledger for the tracking panel. Best-effort:
+      // the shipments table may be unmigrated on a given deploy, so a read
+      // failure degrades to "no shipments yet" rather than 500-ing the
+      // detail. Each shipment is hydrated via getShipment so the panel can
+      // list its carrier events.
+      var shipments = [];
+      if (orderTracking) {
+        try {
+          var shipRows = await orderTracking.listForOrder(o.id);
+          for (var si = 0; si < shipRows.length; si += 1) {
+            var full = await orderTracking.getShipment(shipRows[si].id);
+            shipments.push(full || shipRows[si]);
+          }
+        } catch (_e) { shipments = []; }
+      }
       _sendHtml(res, 200, renderAdminOrder({
         shop_name:   deps.shop_name,
         nav_available: navAvailable,
@@ -1183,12 +1199,106 @@ function mount(router, deps) {
         // Refund moves money, so the console only offers it when a payment
         // provider is wired AND the order has a captured intent to refund.
         can_refund:  !!(payment && o.payment_intent_id),
+        // Shipment/tracking panel only renders when the tracking primitive
+        // is wired; the carrier + status enums drive its form selects.
+        can_track:   !!orderTracking,
+        shipments:   shipments,
+        carriers:    orderTracking ? orderTracking.CARRIERS : null,
+        statuses:    orderTracking ? orderTracking.STATUSES : null,
         moved:       url && url.searchParams.get("moved"),
+        ship_done:   url && url.searchParams.get("ship"),
         notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this order." : null,
       }));
     },
   ));
 
+  // ---- shipment tracking (operator-managed) ---------------------------
+  //
+  // Attach a shipment to an order (carrier + optional tracking number) and
+  // record carrier events against it. Composes order-tracking; mounted
+  // only when that primitive is wired. Both the JSON API and the browser
+  // console funnel through `W()` so writes carry the CSRF + audit
+  // discipline of the rest of the console. The browser side redirects back
+  // to the order detail (PRG); a bad shape (TypeError) surfaces as a
+  // notice, never a 500.
+  if (orderTracking) {
+    router.post("/admin/orders/:id/shipments", _pageOrApi(false,
+      W("order.shipment.create", async function (req, res) {
+        var body = req.body || {};
+        var ship;
+        try {
+          ship = await orderTracking.createShipment({
+            order_id:           req.params.id,
+            carrier:            body.carrier,
+            carrier_other_name: body.carrier_other_name || undefined,
+            tracking_number:    body.tracking_number || undefined,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        _json(res, 201, ship);
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var body = req.body || {};
+        try {
+          await orderTracking.createShipment({
+            order_id:           id,
+            carrier:            body.carrier,
+            carrier_other_name: (body.carrier_other_name && body.carrier_other_name.length) ? body.carrier_other_name : undefined,
+            tracking_number:    (body.tracking_number && body.tracking_number.length) ? body.tracking_number : undefined,
+          });
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _redirect(res, "/admin/orders/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.shipment.create", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/orders/" + enc + "?ship=1");
+      },
+    ));
+
+    router.post("/admin/orders/:id/shipments/:shipmentId/events", _pageOrApi(false,
+      W("order.shipment.event", async function (req, res) {
+        var body = req.body || {};
+        var ev;
+        try {
+          ev = await orderTracking.recordEvent({
+            shipment_id: req.params.shipmentId,
+            status:      body.status,
+            location:    body.location || undefined,
+            detail:      body.detail || undefined,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        _json(res, 200, ev);
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var body = req.body || {};
+        try {
+          await orderTracking.recordEvent({
+            shipment_id: req.params.shipmentId,
+            status:      body.status,
+            location:    (body.location && body.location.length) ? body.location : undefined,
+            detail:      (body.detail && body.detail.length) ? body.detail : undefined,
+          });
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _redirect(res, "/admin/orders/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.shipment.event", outcome: "success", metadata: { id: id, shipment_id: req.params.shipmentId } });
+        _redirect(res, "/admin/orders/" + enc + "?ship=1");
+      },
+    ));
+  }
+
   router.post("/admin/orders/:id/transition", _pageOrApi(false,
     W("order.transition", async function (req, res) {
       var body = req.body || {};
@@ -1720,17 +1830,37 @@ function mount(router, deps) {
           shop_name: deps.shop_name, nav_available: navAvailable, returns: [], status: "pending", notice: "Return not found.",
         }));
         var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var rmaCtx = await _rmaProviderContext(rma);
         _sendHtml(res, 200, renderAdminReturn({
           shop_name:   deps.shop_name,
           nav_available: navAvailable,
           rma:         rma,
           transitions: returns.transitionsFrom(rma.status),
+          // When a payment provider is wired AND the linked order has a
+          // captured intent, the Refund action moves money through the
+          // provider via a confirm interstitial. Absent either, it stays
+          // record-only with a pointer to the order page for the money side.
+          can_provider_refund: rmaCtx.canProviderRefund,
           moved:       url && url.searchParams.get("moved"),
           notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this return." : null,
         }));
       },
     ));
 
+    // Resolve whether an RMA can be refunded through the payment provider:
+    // the provider must be wired AND the linked order must carry a captured
+    // payment intent. Returns the linked order too so the caller can issue
+    // the refund without a second fetch. Best-effort — a bad/legacy order id
+    // degrades to "record-only" rather than throwing.
+    async function _rmaProviderContext(rma) {
+      var ctx = { order: null, canProviderRefund: false };
+      if (!payment || !rma || !rma.order_id) return ctx;
+      try { ctx.order = await order.get(rma.order_id); }
+      catch (_e) { ctx.order = null; }
+      ctx.canProviderRefund = !!(ctx.order && ctx.order.payment_intent_id);
+      return ctx;
+    }
+
     // The browser side of an RMA action: run `opFn(id, body)`, then PRG
     // back to the detail. A bad id / shape (TypeError) or an FSM refusal /
     // not-found (mapped by _returnsClientError) becomes a notice on the
@@ -1803,22 +1933,124 @@ function mount(router, deps) {
       function (id, body) { return returns.markReceived(id, { operator_notes: body.operator_notes || undefined }); },
     ));
 
-    router.post("/admin/returns/:id/refund", _returnAction(
+    // Issue the provider refund for an RMA (when a captured intent exists),
+    // then record the RMA refund. The provider call runs FIRST — only if it
+    // succeeds does the RMA move to refunded — so the queue never marks a
+    // return refunded with the customer never paid back. The refund amount
+    // is the RMA's approved refund_amount_minor (set at approve time);
+    // absent one, the provider issues a full refund of the intent.
+    async function _rmaProviderRefund(rma, order2, body) {
+      var idem = "rma-refund:" + rma.id + ":" + (body.idempotency_suffix || b.uuid.v7());
+      var refund = await payment.refund({
+        payment_intent: order2.payment_intent_id,
+        amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
+        reason:         "requested_by_customer",
+        metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
+      }, idem);
+      var updated = await returns.refund(rma.id, {
+        operator_notes: (body.operator_notes && body.operator_notes.length)
+          ? body.operator_notes
+          : ("provider refund " + refund.id),
+      });
+      return { refund: refund, rma: updated };
+    }
+
+    // Browser confirmation interstitial for a provider-backed RMA refund —
+    // it moves money + advances the RMA, so the console makes the operator
+    // confirm (the CSP forbids a client confirm() dialog). Only meaningful
+    // when a captured intent exists; otherwise it bounces to the detail.
+    router.post("/admin/returns/:id/refund/confirm", _pageOrApi(false,
+      R(async function (_req, res) {
+        return _problem(res, 405, "use-canonical-endpoint", "POST /admin/returns/:id/refund directly for the JSON API");
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var rma;
+        try { rma = await returns.get(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; rma = null; }
+        if (!rma) return _redirect(res, "/admin/returns/" + enc + "?err=1");
+        var rmaCtx = await _rmaProviderContext(rma);
+        if (!rmaCtx.canProviderRefund) {
+          // No captured intent — there's nothing to confirm; the detail's
+          // record-only form handles it.
+          return _redirect(res, "/admin/returns/" + enc + "?err=1");
+        }
+        var amount = (rma.refund_amount_minor != null && rma.refund_amount_minor > 0)
+          ? pricing.format(rma.refund_amount_minor, rma.refund_currency || "USD")
+          : pricing.format(rmaCtx.order.grand_total_minor, rmaCtx.order.currency);
+        _sendHtml(res, 200, renderAdminConfirm({
+          shop_name: deps.shop_name, nav_available: navAvailable, active: "returns",
+          heading: "Refund return " + _htmlEscape(rma.rma_code || rma.id.slice(0, 8)) + "?",
+          consequence: "This issues a refund of " + amount + " through the payment provider and cannot be undone.",
+          detail: "The provider refund runs first; only if it succeeds does the return move to a refunded state.",
+          action: "/admin/returns/" + _htmlEscape(rma.id) + "/refund",
+          confirm_label: "Refund " + amount,
+          cancel_href: "/admin/returns/" + enc,
+        }));
+      },
+    ));
+
+    router.post("/admin/returns/:id/refund", _pageOrApi(false,
       W("return.refund", async function (req, res) {
         var body = req.body || {};
         var rma;
+        try { rma = await returns.get(req.params.id); }
+        catch (e) {
+          if (e instanceof TypeError) return _problem(res, 404, "return-not-found", e.message);
+          throw e;
+        }
+        if (!rma) return _problem(res, 404, "return-not-found");
+        var rmaCtx = await _rmaProviderContext(rma);
+        // Provider-backed path: move money first, then record the RMA.
+        if (rmaCtx.canProviderRefund) {
+          var result;
+          try { result = await _rmaProviderRefund(rma, rmaCtx.order, body); }
+          catch (e) {
+            var ce = _returnsClientError(e);
+            if (ce) return _problem(res, ce.status, ce.slug, e.message);
+            return _problem(res, 502, "provider-refund-failed", (e && e.message) || String(e));
+          }
+          _json(res, 200, result.rma);
+          return result.rma;
+        }
+        // Record-only path (no captured intent / no provider wired).
+        var recorded;
         try {
-          rma = await returns.refund(req.params.id, { operator_notes: body.operator_notes });
+          recorded = 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);
+          var ce2 = _returnsClientError(e);
+          if (ce2) return _problem(res, ce2.status, ce2.slug, e.message);
           throw e;
         }
-        _json(res, 200, rma);
-        return rma;
+        _json(res, 200, recorded);
+        return recorded;
       }),
-      "return.refund",
-      function (id, body) { return returns.refund(id, { operator_notes: body.operator_notes || undefined }); },
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var rma;
+        try { rma = await returns.get(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; rma = null; }
+        if (!rma) return _redirect(res, "/admin/returns/" + enc + "?err=1");
+        var rmaCtx = await _rmaProviderContext(rma);
+        try {
+          if (rmaCtx.canProviderRefund) {
+            await _rmaProviderRefund(rma, rmaCtx.order, req.body || {});
+          } else {
+            await returns.refund(id, { operator_notes: (req.body || {}).operator_notes || undefined });
+          }
+        } catch (e) {
+          if (e instanceof TypeError || _returnsClientError(e)) {
+            return _redirect(res, "/admin/returns/" + enc + "?err=1");
+          }
+          // A provider-refund failure leaves the RMA untouched (the record
+          // step only runs after a successful refund) — surface as a notice.
+          return _redirect(res, "/admin/returns/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".return.refund", outcome: "success", metadata: { id: id, provider: rmaCtx.canProviderRefund } });
+        _redirect(res, "/admin/returns/" + enc + "?moved=1");
+      },
     ));
 
     router.post("/admin/returns/:id/reject", _returnAction(
@@ -4389,6 +4621,7 @@ function renderAdminOrder(opts) {
   var o = opts.order;
   var transitions = opts.transitions || [];
   var moved  = opts.moved  ? "<div class=\"banner banner--ok\">Order updated.</div>" : "";
+  var shipOk = opts.ship_done ? "<div class=\"banner banner--ok\">Shipment updated.</div>" : "";
   var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
 
   var lineRows = (o.lines || []).map(function (l) {
@@ -4444,6 +4677,72 @@ function renderAdminOrder(opts) {
   }).filter(Boolean).join(" ");
   var actions = actionForms || "<span class=\"meta\">This order is in a final state — no further changes.</span>";
 
+  // Shipment + tracking panel. Renders only when the tracking primitive is
+  // wired (`can_track`). For each existing shipment: the carrier, status,
+  // tracking number (linked to the carrier's public URL when known), and
+  // its carrier-event log, plus a single-select form to record the next
+  // event. A bottom form attaches a NEW shipment (carrier + optional
+  // tracking number). Carrier + status option lists come from the
+  // primitive's frozen enums (deps.carriers / deps.statuses).
+  var trackingPanel = "";
+  if (opts.can_track) {
+    var carriers = opts.carriers || [];
+    var statuses = opts.statuses || [];
+    var carrierOpts = carriers.map(function (c) {
+      return "<option value=\"" + _htmlEscape(c) + "\">" + _htmlEscape(c) + "</option>";
+    }).join("");
+    var shipments = opts.shipments || [];
+    var shipBlocks = shipments.map(function (s) {
+      var carrierLabel = s.carrier === "other" ? (s.carrier_other_name || "other") : s.carrier;
+      var trackingCell = s.tracking_number
+        ? (s.tracking_url
+            ? "<a class=\"order-id\" href=\"" + _htmlEscape(String(s.tracking_url)) + "\" rel=\"noopener nofollow\" target=\"_blank\">" + _htmlEscape(String(s.tracking_number)) + " ↗</a>"
+            : "<code class=\"order-id\">" + _htmlEscape(String(s.tracking_number)) + "</code>")
+        : "<span class=\"meta\">—</span>";
+      var eventRows = (s.events || []).map(function (e) {
+        return "<tr><td>" + _htmlEscape(String(e.status)) + "</td>" +
+          "<td>" + (e.location ? _htmlEscape(String(e.location)) : "<span class=\"meta\">—</span>") + "</td>" +
+          "<td>" + _htmlEscape(_fmtDate(e.occurred_at)) + "</td></tr>";
+      }).join("");
+      var eventsTable = (s.events && s.events.length)
+        ? "<table><thead><tr><th scope=\"col\">Status</th><th scope=\"col\">Location</th><th scope=\"col\">When</th></tr></thead><tbody>" + eventRows + "</tbody></table>"
+        : "<p class=\"empty\">No carrier events yet.</p>";
+      var statusOpts = statuses.map(function (st) {
+        return "<option value=\"" + _htmlEscape(st) + "\">" + _htmlEscape(st) + "</option>";
+      }).join("");
+      var eventForm =
+        "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(o.id) + "/shipments/" + _htmlEscape(s.id) + "/events\" class=\"return-action\">" +
+          "<h4>Record event</h4>" +
+          "<label class=\"form-field\"><span>Status</span><select name=\"status\" required>" + statusOpts + "</select></label>" +
+          _setupField("Location", "location", "", "text", "Carrier-reported, optional.", " maxlength=\"128\"") +
+          _setupField("Detail", "detail", "", "text", "Optional note.", " maxlength=\"512\"") +
+          "<button class=\"btn\" type=\"submit\">Record event</button>" +
+        "</form>";
+      return "<div class=\"panel mt\">" +
+        "<div class=\"order-shipment-head\">" +
+          "<strong>" + _htmlEscape(String(carrierLabel)) + "</strong> " +
+          "<span class=\"status-pill " + _htmlEscape(s.status) + "\">" + _htmlEscape(s.status) + "</span>" +
+        "</div>" +
+        "<p class=\"meta\">Tracking: " + trackingCell + "</p>" +
+        eventsTable +
+        eventForm +
+      "</div>";
+    }).join("");
+    var addShipmentForm =
+      "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(o.id) + "/shipments\" class=\"return-action\">" +
+        "<h4>Add a shipment</h4>" +
+        "<label class=\"form-field\"><span>Carrier</span><select name=\"carrier\" required>" + carrierOpts + "</select></label>" +
+        _setupField("Carrier name (if “other”)", "carrier_other_name", "", "text", "Required only when carrier is “other”.", " maxlength=\"64\"") +
+        _setupField("Tracking number", "tracking_number", "", "text", "Optional — links to the carrier's tracking page.", " maxlength=\"64\"") +
+        "<button class=\"btn\" type=\"submit\">Add shipment</button>" +
+      "</form>";
+    trackingPanel =
+      "<div class=\"panel mt\"><h3 class=\"subhead\">Shipments &amp; tracking</h3>" +
+        (shipments.length ? shipBlocks : "<p class=\"empty\">No shipments yet.</p>") +
+        addShipmentForm +
+      "</div>";
+  }
+
   var body =
     "<section class=\"mw-48\">" +
       "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/orders\">&larr; Orders</a></div>" +
@@ -4451,7 +4750,7 @@ function renderAdminOrder(opts) {
         "<span class=\"status-pill " + _htmlEscape(o.status) + "\">" + _htmlEscape(o.status) + "</span></h2>" +
       "<p class=\"meta\">Placed " + _htmlEscape(_fmtDate(o.created_at)) + " · last updated " + _htmlEscape(_fmtDate(o.updated_at)) +
         (o.payment_intent_id ? " · payment <code class=\"order-id\">" + _htmlEscape(o.payment_intent_id) + "</code>" : "") + "</p>" +
-      moved + notice +
+      moved + shipOk + notice +
       "<div class=\"two-col\">" +
         "<div class=\"panel\"><h3 class=\"subhead\">Items</h3>" + linesTable + "</div>" +
         "<div class=\"panel\"><h3 class=\"subhead\">Ship to</h3>" +
@@ -4462,6 +4761,7 @@ function renderAdminOrder(opts) {
       "<div class=\"panel mt\"><h3 class=\"subhead\">Actions</h3>" +
         "<div class=\"order-actions\">" + actions + "</div>" +
       "</div>" +
+      trackingPanel +
     "</section>";
   return _renderAdminShell(opts.shop_name, "Order " + o.id.slice(0, 8), body, "orders", opts.nav_available);
 }
@@ -4612,12 +4912,29 @@ function renderAdminReturn(opts) {
       "</form>");
   }
   if (has("refund")) {
-    actionBlocks.push(
-      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/refund\" class=\"return-action\">" +
-        "<h4>Refund</h4><p class=\"meta\">Record the refund" + (refundShown ? " of " + _htmlEscape(refundShown) : "") + " for this return.</p>" +
-        _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
-        "<button class=\"btn\" type=\"submit\">Refund</button>" +
-      "</form>");
+    if (opts.can_provider_refund) {
+      // A captured payment intent is linked — the Refund button moves money
+      // through the provider. It POSTs to the confirm interstitial (states
+      // the amount + warns it's irreversible), whose Confirm button issues
+      // the provider refund THEN records the RMA refund.
+      actionBlocks.push(
+        "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/refund/confirm\" class=\"return-action\">" +
+          "<h4>Refund</h4><p class=\"meta\">Issues the refund" + (refundShown ? " of " + _htmlEscape(refundShown) : "") + " through the payment provider, then marks this return refunded.</p>" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Refund through provider</button>" +
+        "</form>");
+    } else {
+      // No captured intent / no provider wired — the action records the RMA
+      // refund only. The money side is issued separately (manual provider
+      // refund, or the order page when the order carries an intent), made
+      // explicit so the operator never assumes this moved money.
+      actionBlocks.push(
+        "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/refund\" class=\"return-action\">" +
+          "<h4>Refund</h4><p class=\"meta\">Record-only: marks the refund" + (refundShown ? " of " + _htmlEscape(refundShown) : "") + " as issued. No money moves from here — issue the refund manually or from the " +
+          "<a href=\"/admin/orders/" + _htmlEscape(String(r.order_id)) + "\">linked order</a>.</p>" +
+          _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
+          "<button class=\"btn\" type=\"submit\">Mark refunded (record only)</button>" +
+        "</form>");
+    }
   }
   if (has("reject")) {
     actionBlocks.push(

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.20",
+  "version": "0.2.22",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/lib/storefront.js

@@ -725,6 +725,22 @@ function _buildProductCard(p) {
   });
 }
 
+// PDP "You may also like" rail. `related` is the pre-decorated card
+// list [{ slug, title, price, image_url, image_alt }] the PDP renderer
+// builds from the same-collection picks. Reuses the catalog grid +
+// product-card markup so it inherits the storefront's card styling.
+// Returns "" when there's nothing to show so the PDP renders no empty
+// rail. Mirrored byte-for-byte by worker/render/product.js#_buildRelatedProducts.
+function _buildRelatedProducts(related) {
+  related = related || [];
+  if (related.length === 0) return "";
+  var cards = related.map(function (p) { return _buildProductCard(p); }).join("");
+  return "<section class=\"catalog-section pdp-recommendations\" aria-labelledby=\"pdp-related-title\">" +
+           "<header class=\"section-head\"><h2 id=\"pdp-related-title\" class=\"section-head__title\">You may also like</h2></header>" +
+           "<div class=\"grid\">" + cards + "</div>" +
+         "</section>";
+}
+
 var HOME_HERO =
   "<section class=\"hero hero--dark\">\n" +
   "  <div class=\"hero__bg\" aria-hidden=\"true\">\n" +
@@ -1535,7 +1551,8 @@ var PRODUCT_PAGE =
   "  RAW_BUNDLES_PLACEHOLDER\n" +
   "  RAW_REVIEWS_PLACEHOLDER\n" +
   "  RAW_QA_PLACEHOLDER\n" +
-  "</section>\n";
+  "</section>\n" +
+  "RAW_RELATED_PLACEHOLDER";
 
 // PDP gallery markup — composed once per render call from the
 // product's media rows. When media is present, the first row drives
@@ -2796,7 +2813,7 @@ function renderReturns(opts) {
     : "<div class=\"account-empty\">" +
         "<p class=\"account-empty__icon\" aria-hidden=\"true\"><svg class=\"empty-illu\" viewBox=\"0 0 200 132\" fill=\"none\" stroke=\"#AD38DB\" stroke-width=\"2.6\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"M66 64 L100 50 L134 64 L100 78 Z\"/><path d=\"M66 64 V92 L100 106 L134 92 V64 M100 78 V106\"/><path d=\"M100 36 A20 20 0 0 1 120 56\" stroke=\"#732A8D\" stroke-width=\"2.4\"/><path d=\"M100 28 L100 40 L110 38\" stroke=\"#732A8D\" stroke-width=\"2.4\"/><path d=\"M88 70 H112\" stroke=\"currentColor\" stroke-opacity=\"0.45\" stroke-width=\"1.8\" stroke-dasharray=\"2 4\"/></svg></p>" +
         "<p class=\"account-empty__lede\">No returns yet. Start one from an order in your account.</p>" +
-        "<a class=\"btn-secondary\" href=\"/account/orders\">View your orders →</a>" +
+        "<a class=\"btn-secondary\" href=\"/account/orders\">View your orders &rarr;</a>" +
       "</div>";
   // Success confirmation after submitting a return request. The RMA code
   // round-trips on the ?ok=<code> redirect so the notice can echo it back
@@ -3565,6 +3582,27 @@ function renderProduct(opts) {
     var vTitle = v.title || (Object.keys(v.options || {}).map(function (k) { return v.options[k]; }).join(" / ") || "Default");
     return { id: v.id, sku: v.sku, title: vTitle, price: priceStr };
   });
+  // "You may also like" rail — same-collection picks the route decorated
+  // with each card's hero media + first-variant price (minor units). The
+  // price string is formatted here with the page's own `fmt` so it tracks
+  // the active currency context exactly as the buy-box prices do. Mirrors
+  // the edge renderer (`worker/render/product.js`) so the section is
+  // byte-identical across substrates. Built once, shared by the theme
+  // branch's raw slot and the inline-template branch's placeholder.
+  var relatedAssetPrefix = opts.asset_prefix || "/assets/";
+  var relatedCards = (opts.related || []).map(function (r) {
+    var priceStr = Number.isInteger(r.price_minor)
+      ? fmt(r.price_minor, r.price_currency || "USD")
+      : "—";
+    return {
+      slug:      r.slug,
+      title:     r.title,
+      price:     priceStr,
+      image_url: r.hero_r2_key ? (relatedAssetPrefix + r.hero_r2_key) : null,
+      image_alt: r.hero_r2_key ? (r.hero_alt_text || r.title) : null,
+    };
+  });
+  var relatedHtml = _buildRelatedProducts(relatedCards);
   if (opts.theme) {
     return opts.theme.render("product", {
       title:          opts.product.title,
@@ -3582,6 +3620,10 @@ function renderProduct(opts) {
       qty_breaks_html: _buildQtyBreaks(opts.qty_breaks),
       wishlist_html:  _buildWishlist(opts.product.id, opts.wishlist_count),
       compare_html:   _buildCompare(opts.product.id),
+      // Pre-rendered "You may also like" rail for the theme's
+      // `{{{ related_html }}}` raw slot. Empty string when the product
+      // has no same-collection siblings to show.
+      related_html:   relatedHtml,
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
@@ -3614,7 +3656,8 @@ function renderProduct(opts) {
     .replace("RAW_COMPARE_PLACEHOLDER", compareHtml)
     .replace("RAW_BUNDLES_PLACEHOLDER", bundlesHtml)
     .replace("RAW_REVIEWS_PLACEHOLDER", reviewsHtml)
-    .replace("RAW_QA_PLACEHOLDER", qaHtml);
+    .replace("RAW_QA_PLACEHOLDER", qaHtml)
+    .replace("RAW_RELATED_PLACEHOLDER", relatedHtml);
   // Product-specific OpenGraph + Twitter Card values so shares
   // unfurl as "Operator Tee — blamejs.shop" with the SVG hero, not
   // the default shop-level description + brand logo.
@@ -4136,6 +4179,7 @@ var ORDER_PAGE =
   "    <h1 class=\"section-head__title\">Order <code class=\"inline-code\">{{order_id}}</code></h1>\n" +
   "    <p class=\"section-head__lede\">Status: <span class=\"pdp__badge pdp__badge--ok\"><span class=\"dot dot--live\" aria-hidden=\"true\"></span> {{status}}</span></p>\n" +
   "  </header>\n" +
+  "  RAW_REORDER_NOTICE" +
   "  <div class=\"order-page__grid\">\n" +
   "    <div class=\"order-page__items\">\n" +
   "      <h2 class=\"pdp__variants-title\">Items</h2>\n" +
@@ -4145,8 +4189,11 @@ var ORDER_PAGE =
   "          <tbody>{{line_rows}}</tbody>\n" +
   "        </table>\n" +
   "      </div>\n" +
+  "      RAW_ORDER_ACTIONS" +
   "    </div>\n" +
   "    <aside class=\"order-page__totals\">\n" +
+  "      RAW_ORDER_TIMELINE" +
+  "      RAW_ORDER_TRACKING" +
   "      <h2 class=\"pdp__variants-title\">Totals</h2>\n" +
   "      <dl class=\"totals-list\">\n" +
   "        <div><dt>Subtotal</dt><dd>{{subtotal}}</dd></div>\n" +
@@ -4179,6 +4226,142 @@ function _shipToAddressBlock(s) {
     "</div>";
 }
 
+// The customer-facing order lifecycle, in display order. Mirrors the
+// happy-path edges of the order FSM (pending → paid → fulfilling →
+// shipped → delivered); the terminal off-ramps (refunded / cancelled)
+// are surfaced as a distinct final step rather than a position on the
+// rail. Kept as a small ordered list so the timeline highlights every
+// step up to and including the current status.
+var ORDER_TIMELINE_STEPS = [
+  { status: "pending",    label: "Order placed" },
+  { status: "paid",       label: "Payment confirmed" },
+  { status: "fulfilling", label: "Preparing your order" },
+  { status: "shipped",    label: "Shipped" },
+  { status: "delivered",  label: "Delivered" },
+];
+
+// A paid (or further-along) order is the customer's window to start a
+// return; pending (unpaid) and the terminal off-ramps (cancelled /
+// refunded) are not. Mirrors the operator-facing returns policy: you
+// can't return what you haven't paid for or what's already refunded.
+function _orderEligibleForReturn(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
+// perfectly good "buy this again" candidate). Only a still-pending
+// (never-paid) order is excluded, since its cart was never charged.
+function _orderEligibleForReorder(status) {
+  return status !== "pending";
+}
+
+// Render the lifecycle timeline. Every step up to and including the
+// current status is marked done; the current step is also marked
+// current. A terminal off-ramp (refunded / cancelled) collapses the rail
+// to a single explanatory step so we never imply a cancelled order is
+// "delivered". All labels are static framework copy (no operator input),
+// but escaped at the sink for consistency with the rest of the file.
+function _orderTimelineBlock(status) {
+  var esc = b.template.escapeHtml;
+  if (status === "cancelled" || status === "refunded") {
+    var finalLabel = status === "cancelled" ? "Order cancelled" : "Order refunded";
+    return "<div class=\"order-timeline order-timeline--terminal\">" +
+      "<h2 class=\"pdp__variants-title\">Status</h2>" +
+      "<ol class=\"order-timeline__steps\">" +
+        "<li class=\"order-timeline__step is-current is-terminal\">" +
+          "<span class=\"order-timeline__dot\" aria-hidden=\"true\"></span>" +
+          "<span class=\"order-timeline__label\">" + esc(finalLabel) + "</span>" +
+        "</li>" +
+      "</ol></div>";
+  }
+  var currentIdx = -1;
+  for (var i = 0; i < ORDER_TIMELINE_STEPS.length; i += 1) {
+    if (ORDER_TIMELINE_STEPS[i].status === status) { currentIdx = i; break; }
+  }
+  var steps = ORDER_TIMELINE_STEPS.map(function (step, idx) {
+    var done    = currentIdx >= 0 && idx <= currentIdx;
+    var current = idx === currentIdx;
+    var cls = "order-timeline__step" +
+      (done ? " is-done" : "") + (current ? " is-current" : "");
+    return "<li class=\"" + cls + "\">" +
+      "<span class=\"order-timeline__dot\" aria-hidden=\"true\"></span>" +
+      "<span class=\"order-timeline__label\">" + esc(step.label) + "</span>" +
+      "</li>";
+  }).join("");
+  return "<div class=\"order-timeline\">" +
+    "<h2 class=\"pdp__variants-title\">Status</h2>" +
+    "<ol class=\"order-timeline__steps\">" + steps + "</ol></div>";
+}
+
+// Render the shipment + carrier-tracking panel from order-tracking's
+// listForOrder() rows. Each shipment shows its carrier, status, the
+// tracking number (linked to the carrier's public tracking URL when one
+// is known), and the most-recent carrier event. Empty/absent shipments
+// render nothing so a digital or not-yet-shipped order shows no panel.
+function _orderTrackingBlock(shipments) {
+  if (!Array.isArray(shipments) || !shipments.length) return "";
+  var esc = b.template.escapeHtml;
+  var cards = shipments.map(function (s) {
+    var carrier = s.carrier === "other"
+      ? (s.carrier_other_name || "Carrier")
+      : s.carrier;
+    var trackingHtml = "";
+    if (s.tracking_number) {
+      trackingHtml = s.tracking_url
+        ? "<a class=\"order-shipment__track\" href=\"" + esc(String(s.tracking_url)) +
+            "\" rel=\"noopener nofollow\" target=\"_blank\">" + esc(String(s.tracking_number)) + " ↗</a>"
+        : "<span class=\"order-shipment__track\">" + esc(String(s.tracking_number)) + "</span>";
+    }
+    // Latest carrier event (events arrive oldest-first from listForOrder's
+    // getShipment ordering; the panel's per-shipment events array, when
+    // hydrated, is the same order — take the last).
+    var events = Array.isArray(s.events) ? s.events : [];
+    var latest = events.length ? events[events.length - 1] : null;
+    var latestHtml = latest
+      ? "<p class=\"order-shipment__event\">" +
+          esc(String(latest.status)) +
+          (latest.location ? " &middot; " + esc(String(latest.location)) : "") +
+        "</p>"
+      : "";
+    return "<li class=\"order-shipment\">" +
+      "<div class=\"order-shipment__head\">" +
+        "<span class=\"order-shipment__carrier\">" + esc(String(carrier)) + "</span>" +
+        "<span class=\"pdp__badge\">" + esc(String(s.status)) + "</span>" +
+      "</div>" +
+      (trackingHtml ? "<p class=\"order-shipment__tracking\">Tracking: " + trackingHtml + "</p>" : "") +
+      latestHtml +
+      "</li>";
+  }).join("");
+  return "<div class=\"order-tracking-panel\">" +
+    "<h2 class=\"pdp__variants-title\">Tracking</h2>" +
+    "<ul class=\"order-shipment-list\">" + cards + "</ul></div>";
+}
+
+// Request-a-return + Reorder affordances for an order, gated on its
+// status. Reorder is a POST (it mutates the cart) carrying the order id
+// in the path; Request-a-return links to the existing return form. The
+// same builder feeds the order page and (via _orderRowActions) the
+// dashboard rows so the eligibility rules live in one place.
+function _orderActionsBlock(o) {
+  var esc = b.template.escapeHtml;
+  var btns = [];
+  if (_orderEligibleForReorder(o.status)) {
+    btns.push(
+      "<form class=\"order-action\" method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/reorder\">" +
+        "<button type=\"submit\" class=\"btn-secondary\">Reorder</button>" +
+      "</form>");
+  }
+  if (_orderEligibleForReturn(o.status)) {
+    btns.push(
+      "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/return\">Request a return</a>");
+  }
+  if (!btns.length) return "";
+  return "<div class=\"order-page__actions\">" + btns.join("") + "</div>";
+}
+
 function renderOrder(opts) {
   if (!opts || !opts.order) throw new TypeError("storefront.renderOrder: opts.order required");
   var o = opts.order;
@@ -4212,6 +4395,14 @@ function renderOrder(opts) {
   var shipping = pricing.format(o.shipping_minor,    o.currency);
   var total    = pricing.format(o.grand_total_minor, o.currency);
   var recs = opts.recommendations || [];
+  // Post-handoff shipment + carrier tracking (order-tracking.listForOrder
+  // rows the route bundles in; absent / empty → no panel). The lifecycle
+  // timeline + the Request-a-return / Reorder affordances are derived from
+  // the order status alone, so they render even without tracking wired.
+  var shipments    = opts.shipments || [];
+  var timelineHtml = _orderTimelineBlock(o.status);
+  var trackingHtml = _orderTrackingBlock(shipments);
+  var actionsHtml  = _orderActionsBlock(o);
   if (opts.theme) {
     return opts.theme.render("order", {
       title:               "Order " + o.id,
@@ -4226,6 +4417,11 @@ function renderOrder(opts) {
       shipping:            shipping,
       total:               total,
       ship_to:             o.ship_to || null,
+      timeline_html:       timelineHtml,
+      tracking_html:       trackingHtml,
+      actions_html:        actionsHtml,
+      can_return:          _orderEligibleForReturn(o.status),
+      can_reorder:         _orderEligibleForReorder(o.status),
       recommendations:     recs,
       has_recommendations: recs.length > 0,
       asset_css_main:      opts.theme.assetUrl("css/main.css"),
@@ -4246,6 +4442,12 @@ function renderOrder(opts) {
     }).replace("RAW_ORDER_LINE_THUMB", thumb);
   }).join("");
   if (!rows) rows = "<tr><td colspan=\"4\" class=\"empty\">No items.</td></tr>";
+  // Confirmation banner after a successful reorder (the POST redirects to
+  // ?reordered=1). Static copy, no untrusted input — but the cart link
+  // gives the customer a one-click path to the rebuilt cart.
+  var reorderNotice = opts.reordered
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">Items from this order were added to your cart. <a href=\"/cart\">View cart →</a></p>"
+    : "";
   var body = _render(ORDER_PAGE, {
     order_id:  o.id,
     status:    o.status,
@@ -4254,7 +4456,12 @@ function renderOrder(opts) {
     tax:       tax,
     shipping:  shipping,
     total:     total,
-  }).replace("RAW_LINES", rows).replace("RAW_SHIP_TO", _shipToAddressBlock(o.ship_to));
+  }).replace("RAW_LINES", rows)
+    .replace("RAW_REORDER_NOTICE", reorderNotice)
+    .replace("RAW_ORDER_TIMELINE", timelineHtml)
+    .replace("RAW_ORDER_TRACKING", trackingHtml)
+    .replace("RAW_ORDER_ACTIONS", actionsHtml)
+    .replace("RAW_SHIP_TO", _shipToAddressBlock(o.ship_to));
   // Post-purchase cross-sell rail — reuses the catalog grid + product-card
   // markup (so it inherits the storefront's card styling), rendered only
   // when the picker returned something.
@@ -5143,10 +5350,11 @@ var ACCOUNT_DASH_PAGE =
   "    <h2 class=\"pdp__variants-title\">Recent orders</h2>\n" +
   "    <div class=\"table-scroll\">\n" +
   "      <table class=\"account-orders-table\">\n" +
-  "        <thead><tr><th>Order</th><th>Items</th><th>Status</th><th>Total</th></tr></thead>\n" +
+  "        <thead><tr><th>Order</th><th>Items</th><th>Status</th><th>Total</th><th>Actions</th></tr></thead>\n" +
   "        <tbody>{{order_rows}}</tbody>\n" +
   "      </table>\n" +
   "    </div>\n" +
+  "    <p class=\"account-dash__all-orders\"><a href=\"/account/orders\">View all orders &rarr;</a></p>\n" +
   "  </div>\n" +
   "</section>\n";
 
@@ -5156,6 +5364,7 @@ var ACCOUNT_DASH_ORDER_ROW =
   "  <td class=\"account-order__items\" data-label=\"Items\">RAW_ACCOUNT_ORDER_THUMBS</td>\n" +
   "  <td data-label=\"Status\"><span class=\"pdp__badge {{status_class}}\">{{status}}</span></td>\n" +
   "  <td class=\"price\" data-label=\"Total\">{{total}}</td>\n" +
+  "  <td data-label=\"Actions\">RAW_ACCOUNT_ORDER_ACTIONS</td>\n" +
   "</tr>\n";
 
 function renderAccount(opts) {
@@ -5208,15 +5417,19 @@ function renderAccount(opts) {
     }).join("");
     if (!thumbs) thumbs = "<span class=\"account-order__thumb account-order__thumb--empty\" aria-hidden=\"true\"></span>";
     var moreCount = products.length > 4 ? "<span class=\"account-order__more\">+" + (products.length - 4) + "</span>" : "";
+    // Per-row Reorder / Request-a-return affordances (status-gated, shared
+    // with the order page + order-history list). Localized to this cell —
+    // it does not touch the dashboard's header action nav.
     return _render(ACCOUNT_DASH_ORDER_ROW, {
       order_id:       o.id,
       order_id_short: o.id.slice(0, 8),
       status:         o.status,
       status_class:   _statusClass(o.status),
       total:          pricing.format(o.grand_total_minor, o.currency),
-    }).replace("RAW_ACCOUNT_ORDER_THUMBS", thumbs + moreCount);
+    }).replace("RAW_ACCOUNT_ORDER_THUMBS", thumbs + moreCount)
+      .replace("RAW_ACCOUNT_ORDER_ACTIONS", _orderRowActions(o));
   }).join("");
-  if (!rows) rows = "<tr><td colspan=\"4\" class=\"empty\">No orders yet. Browse the shop and your first order shows up here.</td></tr>";
+  if (!rows) rows = "<tr><td colspan=\"5\" class=\"empty\">No orders yet. Browse the shop and your first order shows up here.</td></tr>";
   var body = _render(ACCOUNT_DASH_PAGE, {
     display_name:    opts.customer.display_name,
     order_count:     String(orders.length),
@@ -5428,6 +5641,87 @@ function renderProfile(opts) {
   });
 }
 
+// Compact per-row Reorder / Request-a-return affordances for an order
+// table row (dashboard + order-history list). Shares the eligibility
+// rules with the order page's _orderActionsBlock so a status that offers
+// a return on the order page offers it in the row too. Reorder is a POST
+// (mutates the cart); Request-a-return is a link to the form.
+function _orderRowActions(o) {
+  var esc = b.template.escapeHtml;
+  var acts = [];
+  if (_orderEligibleForReorder(o.status)) {
+    acts.push(
+      "<form method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/reorder\" class=\"order-row-action\">" +
+        "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Reorder</button>" +
+      "</form>");
+  }
+  if (_orderEligibleForReturn(o.status)) {
+    acts.push(
+      "<a class=\"btn-ghost btn-ghost--sm order-row-action\" href=\"/account/orders/" + esc(String(o.id)) + "/return\">Return</a>");
+  }
+  if (!acts.length) return "<span class=\"meta\">—</span>";
+  return "<div class=\"order-row-actions\">" + acts.join("") + "</div>";
+}
+
+var ORDER_LIST_PAGE =
+  "<section class=\"account-orders\">\n" +
+  "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>\n" +
+  "    <li><a href=\"/account\">Account</a></li>\n" +
+  "    <li aria-current=\"page\">Orders</li>\n" +
+  "  </ol></nav>\n" +
+  "  <h1 class=\"account-orders__title\">Your orders</h1>\n" +
+  "  <div class=\"table-scroll\">\n" +
+  "    <table class=\"account-orders-table\">\n" +
+  "      <thead><tr><th>Order</th><th>Placed</th><th>Status</th><th>Total</th><th>Actions</th></tr></thead>\n" +
+  "      <tbody>{{order_rows}}</tbody>\n" +
+  "    </table>\n" +
+  "  </div>\n" +
+  "  RAW_ORDER_LIST_PAGER" +
+  "</section>\n";
+
+// Full order-history list for the signed-in customer, backed by
+// order.listForCustomer (cursor-paginated). Each row links to the order
+// page and carries the per-row Reorder / Request-a-return affordances.
+// An opaque next-cursor (when the page filled) renders a "Load more"
+// link that threads ?cursor=. Empty history shows a designed empty state
+// rather than a bare table.
+function renderOrderList(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var orders = opts.orders || [];
+  var rows = orders.map(function (o) {
+    var placed = o.created_at ? new Date(Number(o.created_at)).toISOString().slice(0, 10) : "";
+    var statusClass = (o.status === "completed" || o.status === "shipped" || o.status === "delivered")
+      ? "pdp__badge--ok" : "";
+    return "<tr>" +
+      "<td data-label=\"Order\"><a class=\"account-order__id\" href=\"/orders/" + esc(String(o.id)) +
+        "\"><code>" + esc(String(o.id).slice(0, 8)) + "</code></a></td>" +
+      "<td data-label=\"Placed\">" + (placed ? "<time datetime=\"" + esc(placed) + "\">" + esc(placed) + "</time>" : "—") + "</td>" +
+      "<td data-label=\"Status\"><span class=\"pdp__badge " + statusClass + "\">" + esc(String(o.status)) + "</span></td>" +
+      "<td class=\"price\" data-label=\"Total\">" + esc(pricing.format(o.grand_total_minor, o.currency)) + "</td>" +
+      "<td data-label=\"Actions\">" + _orderRowActions(o) + "</td>" +
+      "</tr>";
+  }).join("");
+  var pager = "";
+  if (!rows) {
+    rows = "<tr><td colspan=\"5\" class=\"empty\">No orders yet. <a href=\"/\">Browse the shop →</a></td></tr>";
+  } else if (opts.next_cursor) {
+    pager = "<div class=\"account-orders__pager\">" +
+      "<a class=\"btn-secondary\" href=\"/account/orders?cursor=" + esc(encodeURIComponent(String(opts.next_cursor))) +
+      "\">Load more orders →</a></div>";
+  }
+  var body = _render(ORDER_LIST_PAGE, { order_rows: "RAW_ORDER_ROWS" })
+    .replace("RAW_ORDER_ROWS", rows)
+    .replace("RAW_ORDER_LIST_PAGER", pager);
+  return _wrap({
+    title:      "Your orders",
+    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 survey page ----------------------------------------------
 
 // Render one survey question as a fieldset. Rating → a 0/1..max radio
@@ -6152,6 +6446,66 @@ function mount(router, deps) {
     };
   }
 
+  // "You may also like" picks for a PDP. Deterministic same-collection
+  // query so the edge (worker/data/catalog.js#listRelatedProducts) and
+  // the container produce the SAME ordered list and the rail renders
+  // byte-identically wherever the PDP is served: the source product's
+  // primary collection (lowest membership position), then the other
+  // active members of that collection ordered by membership position
+  // then product id, self excluded, capped at `limit`. The signal-based
+  // recommendations engine (co-purchase + RANDOM filler) is intentionally
+  // NOT used here — its order isn't reproducible at the edge, which has
+  // no engine handle and can't replay RANDOM(). Each pick is decorated
+  // with its first variant's current USD price (minor units) + first
+  // media row; the renderer formats the price string with the page's own
+  // currency formatter so the rail tracks the active display currency.
+  // Best-effort: a read failure (tables not migrated) returns [] so the
+  // PDP renders without the rail rather than 500-ing.
+  async function _relatedProductsFor(productId, limit) {
+    var query = function (sql, params) { return b.externalDb.query(sql, params); };
+    try {
+      var primary = (await query(
+        "SELECT collection_slug FROM collection_members WHERE product_id = ?1 " +
+        "ORDER BY position ASC, id ASC LIMIT 1",
+        [productId],
+      )).rows[0];
+      if (!primary) return [];
+      var siblingRows = (await query(
+        "SELECT cm.product_id AS pid FROM collection_members cm " +
+        "JOIN products p ON p.id = cm.product_id " +
+        "WHERE cm.collection_slug = ?1 AND cm.product_id != ?2 AND p.status = 'active' " +
+        "ORDER BY cm.position ASC, cm.product_id ASC LIMIT ?3",
+        [primary.collection_slug, productId, limit],
+      )).rows;
+      var out = [];
+      for (var i = 0; i < siblingRows.length; i += 1) {
+        var pid = siblingRows[i].pid;
+        var prod = await deps.catalog.products.get(pid);
+        if (!prod || prod.status !== "active") continue;
+        var priceMinor = null;
+        var priceCurrency = "USD";
+        var variants = await deps.catalog.variants.listForProduct(pid);
+        if (variants.length) {
+          var pr = await deps.catalog.prices.current(variants[0].id, "USD");
+          if (pr) { priceMinor = pr.amount_minor; priceCurrency = pr.currency; }
+        }
+        var media = await deps.catalog.media.listForProduct(pid);
+        var hero = media.length ? media[0] : null;
+        out.push({
+          slug:          prod.slug,
+          title:         prod.title,
+          hero_r2_key:   hero ? hero.r2_key : null,
+          hero_alt_text: hero ? (hero.alt_text || prod.title) : null,
+          price_minor:   priceMinor,
+          price_currency: priceCurrency,
+        });
+      }
+      return out;
+    } catch (_e) {
+      return [];
+    }
+  }
+
   // Resolve the cart for this request — read session_id from the
   // sealed cookie, create one (and the cart) if absent. Returns
   // the cart row OR null when the cart was just created (caller can
@@ -6660,6 +7014,10 @@ function mount(router, deps) {
     var qtyBreaks = firstVariant && firstPrice
       ? await _resolveQtyBreaks(firstVariant.sku, firstPrice.amount_minor, firstPrice.currency, ccyFmt)
       : [];
+    // "You may also like" — same-collection picks (deterministic order,
+    // mirrored at the edge). Best-effort inside the helper; an empty list
+    // hides the rail.
+    var related = await _relatedProductsFor(product.id, 4);
     var html = renderProduct(Object.assign({
       product:        product,
       variants:       variants,
@@ -6674,6 +7032,7 @@ function mount(router, deps) {
       bundle_offers:  bundleOffers,
       qty_breaks:     qtyBreaks,
       wishlist_count: wishlistCount,
+      related:        related,
       shop_name:      shopName,
       cart_count:     cartCount,
       theme:          theme,
@@ -7454,10 +7813,30 @@ function mount(router, deps) {
           }
         } catch (_e) { recommendations = []; }
       }
+      // Post-handoff shipment + carrier tracking. Best-effort: the
+      // shipments table may not be migrated on every deploy, so a read
+      // failure degrades to "no tracking panel" rather than 500-ing the
+      // order page. getShipment hydrates each shipment's events, but
+      // listForOrder doesn't — so fetch the full shipment per row to drive
+      // the latest-event line. Bounded by the order's shipment count
+      // (typically 1, a handful at most for split shipments).
+      var shipments = [];
+      if (deps.orderTracking) {
+        try {
+          var shipRows = await deps.orderTracking.listForOrder(o.id);
+          for (var si = 0; si < shipRows.length; si += 1) {
+            var full = await deps.orderTracking.getShipment(shipRows[si].id);
+            shipments.push(full || shipRows[si]);
+          }
+        } catch (_e) { shipments = []; }
+      }
+      var ordUrl = req.url ? new URL(req.url, "http://localhost") : null;
       _send(res, 200, renderOrder({
         order:           o,
         product_lookup:  productLookup,
         recommendations: recommendations,
+        shipments:       shipments,
+        reordered:       ordUrl ? ordUrl.searchParams.get("reordered") === "1" : false,
         shop_name:       shopName,
         theme:           theme,
       }));
@@ -7927,6 +8306,48 @@ function mount(router, deps) {
       }));
     });
 
+    // Full order history for the signed-in customer, cursor-paginated.
+    // The dashboard shows only the most-recent ten; this is the complete
+    // list the "View your orders" link (and the returns empty-state CTA)
+    // point at. Each row links to the order page + carries the per-row
+    // Reorder / Request-a-return affordances. Mounted only when an order
+    // handle is wired.
+    if (deps.order) {
+      router.get("/account/orders", async function (req, res) {
+        var ordersAuth;
+        try { ordersAuth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
+          throw e;
+        }
+        if (!ordersAuth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var listUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        var cursor  = listUrl ? listUrl.searchParams.get("cursor") : null;
+        var page;
+        try {
+          page = await deps.order.listForCustomer(ordersAuth.customer_id, {
+            limit:  20,
+            cursor: cursor || undefined,
+          });
+        } catch (e) {
+          // A tampered / malformed cursor throws TypeError — restart the
+          // list from the top rather than 500-ing.
+          if (!(e instanceof TypeError)) throw e;
+          page = await deps.order.listForCustomer(ordersAuth.customer_id, { limit: 20 });
+        }
+        var listCartCount = await _cartCountForReq(req);
+        _send(res, 200, renderOrderList({
+          orders:      page.rows,
+          next_cursor: page.next_cursor || null,
+          shop_name:   shopName,
+          cart_count:  listCartCount,
+        }));
+      });
+    }
+
     router.post("/account/logout", function (_req, res) {
       _clearAuthCookie(res);
       res.status(303); res.setHeader && res.setHeader("location", "/");
@@ -9684,6 +10105,60 @@ function mount(router, deps) {
     }
   }
 
+  // POST /orders/:id/reorder — rebuild a cart from a past order's frozen
+  // lines. Top-level (needs only cart + order, not checkout) so the Reorder
+  // affordance on the dashboard / order-history list works even on a store
+  // without a payment provider configured. Login is NOT required — a guest
+  // order's capability URL is the auth, mirroring the order page's own
+  // ownership gate: an order that BELONGS to a customer is reorderable only
+  // by that signed-in customer; a guest order (no customer_id) is
+  // reorderable by anyone holding its URL. Each line's CURRENT catalog
+  // price applies (cart.addLine reprices from the catalog) — never the
+  // frozen historical price. Variants that no longer exist / are unbuyable
+  // are skipped silently so a partly-discontinued order still reorders
+  // what's still available. Eligibility gates out a never-paid pending
+  // order (no captured purchase to repeat).
+  if (deps.order) {
+    router.post("/orders/:order_id/reorder", async function (req, res) {
+      var orderId = req.params && req.params.order_id;
+      var o;
+      try { o = orderId ? await deps.order.get(orderId) : null; }
+      catch (e) { if (e instanceof TypeError) { o = null; } else throw e; }
+      if (!o) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+      var reAuth = _currentCustomerEnv(req);
+      if (o.customer_id && (!reAuth || o.customer_id !== reAuth.customer_id)) {
+        return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+      }
+      if (!_orderEligibleForReorder(o.status)) {
+        // A still-pending (never-paid) order has no captured purchase to
+        // repeat — bounce back to its page rather than rebuild a cart from
+        // an unpaid order.
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/orders/" + encodeURIComponent(o.id));
+        return res.end ? res.end() : res.send("");
+      }
+      var resolved = await _getOrCreateCart(req, res, o.currency || "USD");
+      var lines = o.lines || [];
+      for (var rli = 0; rli < lines.length; rli += 1) {
+        var line = lines[rli];
+        var wantQty = Number.isInteger(line.qty) && line.qty >= 1 ? line.qty : 1;
+        if (wantQty > 99) wantQty = 99;
+        try {
+          await deps.cart.addLine(resolved.cart.id, { variant_id: line.variant_id, qty: wantQty });
+        } catch (_e) {
+          // Skip a discontinued / unbuyable / out-of-stock variant rather
+          // than fail the whole reorder — the customer still gets a cart of
+          // everything that's still available.
+        }
+      }
+      // Back to the order page with a confirmation banner + a cart link
+      // (PRG so a refresh doesn't re-add the lines).
+      res.status(303);
+      res.setHeader && res.setHeader("location", "/orders/" + encodeURIComponent(o.id) + "?reordered=1");
+      return res.end ? res.end() : res.send("");
+    });
+  }
+
   // POST /cart/lines — add a line. Reads variant_id + qty from the
   // form body (b.middleware.bodyParser parses it into req.body).
   // CSRF token validation is the responsibility of the csrfProtect
@@ -10224,6 +10699,7 @@ module.exports = {
   renderGiftCardBalance: renderGiftCardBalance,
   renderPayPage:         renderPayPage,
   renderOrder:           renderOrder,
+  renderOrderList:       renderOrderList,
   renderAccountLogin:    renderAccountLogin,
   renderAccountRegister: renderAccountRegister,
   renderAccount:         renderAccount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {