@blamejs/blamejs-shop 0.4.23 → 0.4.24

package/lib/admin.js

@@ -59,6 +59,19 @@ var AUDIT_NAMESPACE = "shop_admin";
 var NOTES_PANEL_LIMIT    = 50;
 var ACTIVITY_PANEL_LIMIT = 50;
 
+// Newest-N bound on the order-detail timeline panel — a chronological
+// read of the most recent slice of the order's story, not a paginated
+// list (the order page is a single screen, not a feed).
+var TIMELINE_PANEL_LIMIT = 60;
+
+// Role the operator inbox broadcasts to (the audience for the navbar
+// unread badge + the /admin/inbox screen). A single-credential console
+// has no per-operator owner for a new-order ping, so the audience is a
+// role — every operator carrying it sees the same feed. Must match the
+// role the order FSM's paid-edge observer enqueues against (server.js).
+var INBOX_ROLE           = "fulfillment";
+var INBOX_PANEL_LIMIT    = 50;
+
 // Operator-readable error-log sink (lib/error-log.js), set by mount()
 // when the deployment wires `deps.errorLog`. `_safeNotice` records the
 // scrubbed message of a genuine 5xx here so the failure is reachable
@@ -118,6 +131,7 @@ var _ACTION_PERMISSION = Object.freeze({
   gift: "catalog.write", preorder: "catalog.write", quantity_discount: "catalog.write",
   auto_discount: "catalog.write", coupon_policy: "catalog.write",
   promo_banner: "catalog.write", announcement: "catalog.write", blog: "catalog.write",
+  suggestion: "catalog.write", sidebar_widget: "catalog.write",
   page: "catalog.write", help: "catalog.write", survey: "catalog.write",
   hours: "catalog.write", delivery_holiday: "catalog.write",
   delivery_transit: "catalog.write", tax_rate: "catalog.write",
@@ -130,6 +144,7 @@ var _ACTION_PERMISSION = Object.freeze({
   export: "orders.write", tax_filing: "orders.write", quote: "orders.write",
   gift_card: "orders.write", subscription: "orders.write",
   cart_recovery_code: "orders.write", support: "orders.write",
+  inbox: "orders.write",
   // customers
   customer: "customers.write", customer_segment: "customers.write",
   // shop configuration
@@ -846,13 +861,31 @@ function mount(router, deps) {
   var operatorAccounts = deps.operatorAccounts || null;
   var operatorAuditLog = deps.operatorAuditLog || null;
 
+  // Unified order-event feed for the order-detail screen. When wired, the
+  // /admin/orders/:id page renders a chronological timeline aggregated
+  // across the FSM transitions, shipment events, customer-service notes,
+  // returns, shipping labels, and dispatched notifications — one read of
+  // the whole order story rather than scanning each panel. Read-only: the
+  // primitive only memoizes a summary cache, never mutating an event row.
+  var orderTimeline    = deps.orderTimeline    || null;
+
+  // Operator inbox + navbar unread badge. When wired, the /admin/inbox
+  // screen lists notifications broadcast to the fulfillment role (newest
+  // order pings, etc.) with mark-read / archive, and every authed page's
+  // nav carries the unread count. The new-order ping is enqueued by the
+  // order FSM's paid-edge observer (wired in server.js); this console is
+  // the read + clear side. The audience is a role broadcast so a single-
+  // credential deployment surfaces the badge without modelling one owning
+  // operator — `INBOX_ROLE` is that role.
+  var operatorInbox    = deps.operatorInbox    || null;
+
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
   // into every authed render call as `nav_available`.
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns, operators: !!operatorAccounts };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, suggestionBox: !!deps.suggestionBox, sidebarWidgets: !!deps.sidebarWidgets, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns, operators: !!operatorAccounts, inbox: !!operatorInbox };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -868,12 +901,35 @@ function mount(router, deps) {
   if (typeof router.use === "function") {
     router.use(function adminCsrfTokenMiddleware(req, _res, next) {
       try {
-        _csrfAls.enterWith({ csrf_token: req.csrfToken || "" });
+        // One mutable store object per request — the CSRF token is seeded
+        // here synchronously; the inbox-badge middleware below fills in the
+        // unread count on the SAME object once it has awaited the read.
+        _csrfAls.enterWith({ csrf_token: req.csrfToken || "", inbox_unread: 0 });
       } catch (_e) { /* drop-silent — form renders token-less */ }
       next();
     });
   }
 
+  // Seed the navbar unread-inbox badge count onto the per-request ALS
+  // store so `_renderAdminShell` can stamp it into the nav on EVERY authed
+  // page — the operator sees a new sale without polling or opening the
+  // inbox. The audience is a role broadcast (INBOX_ROLE), so the count is
+  // role-scoped (`unreadCountForRole`), independent of whether the actor is
+  // the bootstrap owner or a per-operator session. Runs after the CSRF
+  // middleware (same store object). Drop-silent + best-effort: a read
+  // failure (or an unmigrated table) leaves the badge at zero rather than
+  // 500-ing the console. Skipped entirely when no inbox is wired.
+  if (operatorInbox && typeof router.use === "function") {
+    router.use(async function adminInboxBadgeMiddleware(_req, _res, next) {
+      try {
+        var n = await operatorInbox.unreadCountForRole({ role: INBOX_ROLE });
+        var store = _csrfAls.getStore();
+        if (store) store.inbox_unread = Number(n) || 0;
+      } catch (_e) { /* drop-silent — badge renders at zero */ }
+      next();
+    });
+  }
+
   // The auth context every wrapped route resolves through — the bootstrap
   // token plus the per-operator credential store + the chained audit peer.
   // Threaded into `_wrap` so the single chokepoint owns BOTH the credential
@@ -2119,6 +2175,30 @@ function mount(router, deps) {
           notes = (await orderNotes.listForOrder({ order_id: o.id, limit: NOTES_PANEL_LIMIT })).rows || [];
         } catch (_ne) { notes = []; }
       }
+      // Chronological order story — one feed across FSM transitions,
+      // shipment events, notes, returns, labels, and dispatched
+      // notifications. Operator view (no customer_visible_only), bounded
+      // to the most recent slice. Best-effort: an unwired timeline
+      // primitive (or an unmigrated source table) degrades to no panel
+      // rather than 500-ing the detail page.
+      var timeline = null;
+      if (orderTimeline) {
+        try {
+          var feed = await orderTimeline.forOrder({ order_id: o.id });
+          timeline = (feed || []).slice(0, TIMELINE_PANEL_LIMIT);
+        } catch (_te) { timeline = null; }
+      }
+      // Running refunded total (minor units) so the partial-refund panel
+      // can state how much is already refunded and cap the next slice at
+      // the remaining balance. Sums every `refund` order-transition row's
+      // amount — integer minor-unit arithmetic, never a float. Best-effort:
+      // a read failure leaves the panel to treat the order as un-refunded
+      // (the route re-validates the cap server-side before moving money).
+      var refundedMinor = 0;
+      if (payment && o.payment_intent_id) {
+        try { refundedMinor = await order.refundedTotalMinor(o.id); }
+        catch (_re) { refundedMinor = 0; }
+      }
       _sendHtml(res, 200, renderAdminOrder({
         shop_name:   deps.shop_name,
         nav_available: navAvailable,
@@ -2127,6 +2207,15 @@ 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),
+        // Partial-refund panel inputs. `refunded_minor` is the running
+        // total already refunded; `refundable_minor` is what's left of the
+        // order's grand total. The panel renders a decimal-amount form
+        // capped at the remaining balance; the route re-validates the cap
+        // server-side (the form is display only — the backend is the gate).
+        refunded_minor:    refundedMinor,
+        refundable_minor:  Math.max(0, (Number(o.grand_total_minor) || 0) - refundedMinor),
+        refund_done:       url && url.searchParams.get("refunded"),
+        refund_err:        url && url.searchParams.get("refund_err") ? url.searchParams.get("refund_err") : null,
         // Shipment/tracking panel only renders when the tracking primitive
         // is wired; the carrier + status enums drive its form selects.
         can_track:   !!orderTracking,
@@ -2168,6 +2257,11 @@ function mount(router, deps) {
         note_err:    url && url.searchParams.get("note_err") ? url.searchParams.get("note_err") : null,
         note_authors:    orderNotes ? orderNotes.ALLOWED_AUTHORS : null,
         note_visibility: orderNotes ? orderNotes.ALLOWED_VISIBILITY : null,
+        // Order timeline panel — renders only when the timeline primitive
+        // is wired. The feed is already operator-facing event shape
+        // (`{ kind, occurred_at, title, body?, actor?, link? }`).
+        can_timeline: !!orderTimeline,
+        timeline:     timeline,
         notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this order." : null,
       }));
     },
@@ -3954,6 +4048,214 @@ function mount(router, deps) {
         _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?moved=1");
       },
     ));
+
+    // ---- partial refund -------------------------------------------------
+    //
+    // Refund a specific amount that may NOT clear the order's balance. The
+    // operator types a decimal amount (e.g. "12.50"); the backend parses it
+    // through `b.money.of(<decimal>, <currency>)` so the minor-unit count is
+    // exact and currency-exponent-correct (USD→2, JPY→0) — never a float,
+    // and extra fractional digits are refused at the parse boundary. The
+    // remaining-balance cap is enforced SERVER-SIDE before any money moves:
+    // refunded-so-far is summed from the ledger, and a slice that would push
+    // the total past the order's grand total is refused (422) with NOTHING
+    // sent to the provider. The provider refund is issued FIRST under an
+    // idempotency key derived from the order + amount + the refunded-total
+    // seen, so a double-submit (or a retry) collapses to one provider charge
+    // and one ledger row rather than refunding twice — the race guards the
+    // payment-integrity work established. Only after the provider succeeds is
+    // the ledger touched: a slice that exactly clears the remaining balance
+    // drives the terminal FSM `refund` edge (order → refunded, running the
+    // gift-card / loyalty reversals); a slice that leaves a balance records a
+    // same-state partial-refund row (the order keeps its lifecycle state).
+    async function _partialRefund(o, decimalAmount) {
+      var alreadyMinor = await order.refundedTotalMinor(o.id);
+      var remainingMinor = (Number(o.grand_total_minor) || 0) - alreadyMinor;
+      if (remainingMinor <= 0) {
+        var none = new TypeError("This order is already fully refunded — nothing remains to refund.");
+        none._refundCode = "nothing-remaining";
+        throw none;
+      }
+      // Parse the operator-typed decimal into exact minor units via the
+      // money primitive (BigInt, currency-exponent-aware). A bad shape /
+      // too many fractional digits throws — surfaced as a clean 4xx.
+      var minor;
+      try {
+        minor = Number(b.money.of(String(decimalAmount == null ? "" : decimalAmount).trim(), o.currency).toMinorUnits());
+      } catch (_pe) {
+        var bad = new TypeError("Enter a valid amount in " + o.currency + " (e.g. 12.50) — no more decimal places than the currency allows.");
+        bad._refundCode = "bad-amount";
+        throw bad;
+      }
+      if (!Number.isInteger(minor) || minor <= 0) {
+        var pos = new TypeError("The refund amount must be greater than zero.");
+        pos._refundCode = "bad-amount";
+        throw pos;
+      }
+      if (minor > remainingMinor) {
+        // Over-refund — would push the refunded total past what the customer
+        // paid. Refuse BEFORE the provider is called so no money moves.
+        var over = new TypeError("That's more than the " + pricing.format(remainingMinor, o.currency) +
+                                 " still refundable on this order.");
+        over._refundCode = "over-refund";
+        throw over;
+      }
+      var clearsBalance = (minor === remainingMinor);
+      // Idempotency key folds in the refunded-total seen, so two submits of
+      // the same slice (a double-click, a retry) reuse one provider refund.
+      var idemKey = "refund:" + o.id + ":partial:" + alreadyMinor + ":" + minor;
+      var refund = await payment.refund({
+        payment_intent: o.payment_intent_id,
+        amount_minor:   minor,
+        reason:         "requested_by_customer",
+        metadata:       { order_id: o.id, partial: !clearsBalance },
+      }, idemKey);
+      var refundedMinor = Number(refund.amount) || minor;
+      if (clearsBalance) {
+        // The slice clears the remaining balance — drive the terminal FSM
+        // edge so the order moves to `refunded` (and the gift-card / loyalty
+        // reversals fire). A transition refusal (already terminal) is
+        // swallowed: the provider refund has succeeded and is the source of
+        // truth, surfaced via the refreshed ledger.
+        try {
+          await order.transition(o.id, "refund", {
+            reason:   "admin:refund:partial-final",
+            metadata: { stripe_refund_id: refund.id, amount_minor: refundedMinor, partial: true },
+          });
+        } catch (_te) { /* provider refund persisted; FSM refusal surfaced via re-fetch */ }
+      } else {
+        // Leaves a balance — append the partial-refund ledger row WITHOUT
+        // changing the order's lifecycle state.
+        await order.recordPartialRefund(o.id, {
+          amount_minor: refundedMinor,
+          reason:       "admin:refund:partial",
+          metadata:     { stripe_refund_id: refund.id },
+        });
+      }
+      return { refund: refund, amount_minor: refundedMinor, cleared: clearsBalance };
+    }
+
+    router.post("/admin/orders/:id/refund/partial", _pageOrApi(false,
+      W("order.refund", async function (req, res) {
+        var o = await order.get(req.params.id);
+        if (!o) return _problem(res, 404, "order-not-found");
+        if (!o.payment_intent_id) return _problem(res, 422, "no-payment-intent", "Order has no linked payment intent");
+        var body = req.body || {};
+        var result;
+        try {
+          result = await _partialRefund(o, body.amount);
+        } catch (e) {
+          if (e instanceof TypeError) {
+            var status = e._refundCode === "over-refund" || e._refundCode === "nothing-remaining" ? 422 : 400;
+            return _problem(res, status, e._refundCode || "bad-request", e.message);
+          }
+          // allow:admin-5xx-echoes-raw-error-message — 502 surfaces the PAYMENT PROVIDER's refund-failure reason, an operator-actionable upstream message, not a server/storage internal.
+          return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
+        }
+        _json(res, 200, result);
+        return { id: o.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var o;
+        try { o = await order.get(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
+        if (!o || !o.payment_intent_id) {
+          return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
+        }
+        var enc = encodeURIComponent(id);
+        try {
+          await _partialRefund(o, (req.body || {}).amount);
+        } catch (e) {
+          if (e instanceof TypeError) {
+            // Operator-actionable validation message (over-refund, bad amount,
+            // already-refunded) surfaces verbatim on the detail page.
+            return _redirect(res, "/admin/orders/" + enc + "?refund_err=" + encodeURIComponent(e.message));
+          }
+          // Provider refund failed — the order is untouched (the ledger is
+          // only written after a successful provider refund).
+          return _redirect(res, "/admin/orders/" + enc + "?refund_err=" +
+            encodeURIComponent("The refund couldn't be processed by the payment provider. Nothing was charged back — try again."));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.refund", outcome: "success", metadata: { id: id, partial: true } });
+        _redirect(res, "/admin/orders/" + enc + "?refunded=1");
+      },
+    ));
+  }
+
+  // ---- operator inbox -------------------------------------------------
+  //
+  // The in-console notification feed. Mounted only when an operator-inbox
+  // primitive is wired. The audience is a role broadcast (INBOX_ROLE) — a
+  // new-order ping (enqueued by the order FSM's paid-edge observer) reaches
+  // every operator carrying the role without modelling one owning operator,
+  // so the navbar badge + this screen work the same on a single-credential
+  // console and a multi-operator one. The screen lists the role's messages
+  // newest-first with mark-read / archive; each write asserts the row
+  // carries the role before mutating (a guessed id from another role can't
+  // be cleared here).
+  if (operatorInbox) {
+    router.get("/admin/inbox", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var includeArchived = !!(url && url.searchParams.get("archived"));
+        var page = await operatorInbox.inboxForRole({
+          role: INBOX_ROLE, include_archived: includeArchived, limit: INBOX_PANEL_LIMIT,
+        });
+        _json(res, 200, page);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var includeArchived = !!(url && url.searchParams.get("archived"));
+        var messages = [];
+        try {
+          messages = (await operatorInbox.inboxForRole({
+            role: INBOX_ROLE, include_archived: includeArchived, limit: INBOX_PANEL_LIMIT,
+          })).rows || [];
+        } catch (_e) { messages = []; }
+        _sendHtml(res, 200, _renderAdminInbox({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          messages: messages, include_archived: includeArchived,
+          done:  url && url.searchParams.get("done"),
+          notice: url && url.searchParams.get("err") ? "That action couldn't be completed." : null,
+        }));
+      },
+    ));
+
+    // Shared mark-read / archive write — role-scoped (the row must carry
+    // INBOX_ROLE). A malformed id throws (TypeError → clean 4xx); an unknown
+    // id or one addressed elsewhere is a clean 404 with nothing written.
+    function _inboxWriteRoute(suffix, audit, op) {
+      router.post("/admin/inbox/:id" + suffix, _pageOrApi(false,
+        W(audit, async function (req, res) {
+          var out;
+          try { out = await op(req.params.id); }
+          catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            if (e && (e.code === "INBOX_MESSAGE_NOT_FOUND" || e.code === "INBOX_MESSAGE_NOT_ADDRESSABLE")) {
+              return _problem(res, 404, "inbox-message-not-found");
+            }
+            throw e;
+          }
+          _json(res, 200, out);
+          return { id: req.params.id };
+        }),
+        async function (req, res) {
+          try { await op(req.params.id); }
+          catch (_e) {
+            // Malformed / unknown / cross-role id — a clean notice, never a 500.
+            return _redirect(res, "/admin/inbox?err=1");
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + "." + audit, outcome: "success", metadata: { id: req.params.id } });
+          _redirect(res, "/admin/inbox?done=1");
+        },
+      ));
+    }
+
+    _inboxWriteRoute("/read", "inbox.read",
+      function (id) { return operatorInbox.markReadForRole({ id: id, role: INBOX_ROLE }); });
+    _inboxWriteRoute("/archive", "inbox.archive",
+      function (id) { return operatorInbox.archiveForRole({ id: id, role: INBOX_ROLE }); });
   }
 
   // ---- reviews (moderation) -------------------------------------------
@@ -5157,9 +5459,19 @@ function mount(router, deps) {
       });
     }
 
+    // The privacy/DSR actions administer a customer's personal data — a PII
+    // export bundle (fulfill / dispatch) or an irreversible erasure (delete).
+    // They gate on `customers.write`, the same grant the customer-record
+    // routes use, so a read-only viewer is refused on the verb (and the
+    // denial is chained through the operator audit log) rather than able to
+    // export or erase. The `customer.` audit-action prefix maps to
+    // `customers.write` in `_ACTION_PERMISSION`; wrapping the JSON handler in
+    // `W(...)` gates BOTH the bearer JSON path (inside `_wrap`) and the
+    // browser-form path (`_dsrAction` forwards the handler to `_pageOrApi`,
+    // which reads its `_adminWriteAction` tag to gate the cookie branch).
     router.post("/admin/dsr/:id/fulfill", _dsrAction(
-      R(async function (req, res) {
-        try { var bundle = await dsr.fulfillRequest({ request_id: req.params.id }); _json(res, 200, bundle); }
+      W("customer.dsr_fulfill", async function (req, res) {
+        try { var bundle = await dsr.fulfillRequest({ request_id: req.params.id }); _json(res, 200, bundle); return { id: req.params.id }; }
         catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
       }),
       "dsr.fulfill",
@@ -5167,9 +5479,9 @@ function mount(router, deps) {
     ));
 
     router.post("/admin/dsr/:id/dispatch", _dsrAction(
-      R(async function (req, res) {
+      W("customer.dsr_dispatch", async function (req, res) {
         var body = req.body || {};
-        try { var row = await dsr.dispatchExport({ request_id: req.params.id, delivery_method: body.delivery_method, delivery_address: body.delivery_address }); _json(res, 200, row); }
+        try { var row = await dsr.dispatchExport({ request_id: req.params.id, delivery_method: body.delivery_method, delivery_address: body.delivery_address }); _json(res, 200, row); return { id: req.params.id }; }
         catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
       }),
       "dsr.dispatch",
@@ -5177,9 +5489,9 @@ function mount(router, deps) {
     ));
 
     router.post("/admin/dsr/:id/dismiss", _dsrAction(
-      R(async function (req, res) {
+      W("customer.dsr_dismiss", async function (req, res) {
         var body = req.body || {};
-        try { var row = await dsr.dismissRequest({ request_id: req.params.id, dismiss_reason: body.dismiss_reason }); _json(res, 200, row); }
+        try { var row = await dsr.dismissRequest({ request_id: req.params.id, dismiss_reason: body.dismiss_reason }); _json(res, 200, row); return { id: req.params.id }; }
         catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
       }),
       "dsr.dismiss",
@@ -5193,8 +5505,8 @@ function mount(router, deps) {
     // which point processDeletion runs for real (dry_run: false). The bearer
     // JSON path executes directly (tooling has no interstitial).
     router.post("/admin/dsr/:id/delete/confirm", _pageOrApi(false,
-      R(async function (req, res) {
-        try { var result = await dsr.processDeletion({ request_id: req.params.id, dry_run: false }); _json(res, 200, result); }
+      W("customer.dsr_delete", async function (req, res) {
+        try { var result = await dsr.processDeletion({ request_id: req.params.id, dry_run: false }); _json(res, 200, result); return { id: req.params.id }; }
         catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
       }),
       async function (req, res) {
@@ -7210,6 +7522,305 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- suggestion box -------------------------------------------------
+  // The customer-submitted idea backlog. The triage list (optionally
+  // filtered by status / category) + a per-suggestion detail screen where
+  // the operator responds (status transition through the roadmap FSM),
+  // archives, or flags as spam. Content-negotiated like the other screens:
+  // bearer → JSON; signed-in browser → the HTML table + detail. The public
+  // /suggestions storefront page is the intake; this is the operator side
+  // of the same instance.
+  if (deps.suggestionBox) {
+    var suggestionBox = deps.suggestionBox;
+
+    // Read a triage page. The console lists open + responded rows (it never
+    // surfaces spam-flagged / archived rows in the default view) sorted
+    // newest-first; a `?status=` / `?category=` chip narrows it. Drop-silent
+    // to an empty list on a read error so the screen renders rather than 500.
+    var _loadSuggestionTriage = async function (status, category, cursor) {
+      var listOpts = { sort: "newest", limit: 50 };
+      if (status)   listOpts.status   = status;
+      if (category) listOpts.category = category;
+      if (cursor)   listOpts.cursor   = cursor;
+      try {
+        var page = await suggestionBox.listSuggestions(listOpts);
+        return { rows: page.rows || [], next_cursor: page.next_cursor || null };
+      } catch (_e) {
+        return { rows: [], next_cursor: null };
+      }
+    };
+
+    router.get("/admin/suggestions", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status   = url && url.searchParams.get("status");
+        var category = url && url.searchParams.get("category");
+        var cursor   = url && url.searchParams.get("cursor");
+        var page = await _loadSuggestionTriage(status || null, category || null, cursor || null);
+        _json(res, 200, { rows: page.rows, next_cursor: page.next_cursor });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status   = (url && url.searchParams.get("status"))   || null;
+        var category = (url && url.searchParams.get("category")) || null;
+        var cursor   = (url && url.searchParams.get("cursor"))   || null;
+        var page = await _loadSuggestionTriage(status, category, cursor);
+        _sendHtml(res, 200, renderAdminSuggestions({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          suggestions: page.rows, next_cursor: page.next_cursor,
+          status_filter: status, category_filter: category,
+          responded: url && url.searchParams.get("responded"),
+          archived:  url && url.searchParams.get("archived"),
+          flagged:   url && url.searchParams.get("flagged"),
+          notice:    (url && url.searchParams.get("err")) ? "That action couldn't be completed for the suggestion." : null,
+        }));
+      },
+    ));
+
+    router.get("/admin/suggestions/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var row = await suggestionBox.getSuggestion(req.params.id);
+        if (!row) return _problem(res, 404, "suggestion-not-found");
+        _json(res, 200, row);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var row = null;
+        try { row = await suggestionBox.getSuggestion(req.params.id); }
+        catch (_e) { row = null; }
+        if (!row) return _sendHtml(res, 404, renderAdminSuggestions({
+          shop_name: deps.shop_name, nav_available: navAvailable, suggestions: [], notice: "Suggestion not found.",
+        }));
+        _sendHtml(res, 200, renderAdminSuggestion({
+          shop_name: deps.shop_name, nav_available: navAvailable, suggestion: row,
+          responded: url && url.searchParams.get("responded"),
+          notice:    (url && url.searchParams.get("err")) ? "That action couldn't be completed for the suggestion." : null,
+        }));
+      },
+    ));
+
+    // Respond — transition the suggestion through the roadmap FSM, optionally
+    // leaving a public-visible reply. The form posts status + response +
+    // responder; the responder is the signed-in operator's id when resolved,
+    // else a console label.
+    router.post("/admin/suggestions/:id/respond", _pageOrApi(false,
+      W("suggestion.respond", async function (req, res) {
+        var body = req.body || {};
+        var row;
+        try {
+          row = await suggestionBox.respondToSuggestion({
+            suggestion_id: req.params.id,
+            status:        body.status,
+            response:      typeof body.response === "string" ? body.response : "",
+            responder:     _suggestionResponder(req, body),
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e && e.code === "SUGGESTION_NOT_FOUND") return _problem(res, 404, "suggestion-not-found");
+          if (e && e.code === "SUGGESTION_INVALID_TRANSITION") return _problem(res, 409, "conflict", e.message);
+          if (e && e.code === "SUGGESTION_ARCHIVED") return _problem(res, 409, "conflict", e.message);
+          throw e;
+        }
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var body = req.body || {};
+        try {
+          await suggestionBox.respondToSuggestion({
+            suggestion_id: id,
+            status:        body.status,
+            response:      typeof body.response === "string" ? body.response : "",
+            responder:     _suggestionResponder(req, body),
+          });
+        } catch (e) {
+          if (e instanceof TypeError || (e && e.code)) return _redirect(res, "/admin/suggestions/" + enc + "?err=1");
+          throw e;
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".suggestion.respond", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/suggestions/" + enc + "?responded=1");
+      },
+    ));
+
+    router.post("/admin/suggestions/:id/archive", _pageOrApi(false,
+      W("suggestion.archive", async function (req, res) {
+        var row;
+        try { row = await suggestionBox.archiveSuggestion(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!row) return _problem(res, 404, "suggestion-not-found");
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var row = null;
+        try { row = await suggestionBox.archiveSuggestion(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!row) return _redirect(res, "/admin/suggestions?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".suggestion.archive", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/suggestions?archived=1");
+      },
+    ));
+
+    router.post("/admin/suggestions/:id/flag", _pageOrApi(false,
+      W("suggestion.flag", async function (req, res) {
+        var body = req.body || {};
+        var flagged = !(body.flagged === "0" || body.flagged === false || body.flagged === "false");
+        var row;
+        try { row = await suggestionBox.flagAsSpam({ suggestion_id: req.params.id, flagged: flagged }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!row) return _problem(res, 404, "suggestion-not-found");
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var body = req.body || {};
+        // The console toggle posts the desired next state via a hidden field
+        // (flag → 1, un-flag → 0); a missing field defaults to flag.
+        var flagged = !(body.flagged === "0");
+        var row = null;
+        try { row = await suggestionBox.flagAsSpam({ suggestion_id: id, flagged: flagged }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!row) return _redirect(res, "/admin/suggestions?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".suggestion.flag", outcome: "success", metadata: { id: id, flagged: flagged } });
+        _redirect(res, "/admin/suggestions?flagged=1");
+      },
+    ));
+  }
+
+  // ---- sidebar widgets ------------------------------------------------
+  // Operator-curated storefront right-rail content. The console defines
+  // widgets (kind-specific payload) + sets each page's ordered placement;
+  // the storefront resolves + renders the placed widgets per page. Content-
+  // negotiated like the other screens: bearer → JSON; signed-in browser →
+  // the HTML table + create form + the per-page placement editor. The
+  // console exposes the all / guest / logged_in audiences; the primitive's
+  // segment audience needs an isMember handle that isn't wired (see
+  // server.js), so it isn't offered here.
+  if (deps.sidebarWidgets) {
+    var sidebarWidgets = deps.sidebarWidgets;
+
+    // The pages a sidebar can be placed on. These page_keys are the same
+    // values the storefront resolver derives from the request path, so an
+    // operator placing widgets on "home" reaches the home page's right rail.
+    var _SIDEBAR_PAGE_KEYS = ["home", "collection", "search", "cart", "product"];
+
+    var _loadSidebarConsole = async function () {
+      var widgets = [];
+      try { widgets = await sidebarWidgets.listWidgets({ include_archived: true, limit: sidebarWidgets.MAX_LIMIT || 500 }); }
+      catch (_e) { widgets = []; }
+      // Resolve each page's current ordered placement so the editor can
+      // pre-check the boxes. widgetsForPage filters by audience/schedule, so
+      // for the editor we read the raw placement via a far-future "now" +
+      // a guest viewer to surface every placed slug regardless of window;
+      // archived widgets drop out (they can't be placed). Drop-silent.
+      var placements = Object.create(null);
+      for (var i = 0; i < _SIDEBAR_PAGE_KEYS.length; i += 1) {
+        var key = _SIDEBAR_PAGE_KEYS[i];
+        placements[key] = [];
+        try {
+          var rows = await sidebarWidgets.widgetsForPage({
+            page_key: key, viewer_kind: "guest", now: 1,
+          });
+          placements[key] = rows.map(function (r) { return r.slug; });
+        } catch (_e2) { placements[key] = []; }
+      }
+      return { widgets: widgets, placements: placements, page_keys: _SIDEBAR_PAGE_KEYS.slice() };
+    };
+
+    router.get("/admin/sidebar-widgets", _pageOrApi(true,
+      R(async function (_req, res) {
+        var console_ = await _loadSidebarConsole();
+        _json(res, 200, { widgets: console_.widgets, placements: console_.placements });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var console_ = await _loadSidebarConsole();
+        _sendHtml(res, 200, renderAdminSidebarWidgets({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          widgets: console_.widgets, placements: console_.placements, page_keys: console_.page_keys,
+          created:  url && url.searchParams.get("created"),
+          updated:  url && url.searchParams.get("updated"),
+          archived: url && url.searchParams.get("archived"),
+          placed:   url && url.searchParams.get("placed"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the widget." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/sidebar-widgets", _pageOrApi(false,
+      W("sidebar_widget.define", async function (req, res) {
+        var row;
+        try { row = await sidebarWidgets.defineWidget(_sidebarWidgetFromForm(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        try {
+          await sidebarWidgets.defineWidget(_sidebarWidgetFromForm(req.body || {}));
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var n = _safeNotice(e, "sidebar_widget.define");
+          var console_ = await _loadSidebarConsole();
+          return _sendHtml(res, n.status, renderAdminSidebarWidgets({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            widgets: console_.widgets, placements: console_.placements, page_keys: console_.page_keys,
+            notice: n.message.replace(/^sidebarWidgets[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".sidebar_widget.define", outcome: "success" });
+        _redirect(res, "/admin/sidebar-widgets?created=1");
+      },
+    ));
+
+    router.post("/admin/sidebar-widgets/:slug/archive", _pageOrApi(false,
+      W("sidebar_widget.archive", async function (req, res) {
+        var row;
+        try { row = await sidebarWidgets.archiveWidget(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        try { await sidebarWidgets.archiveWidget(slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/sidebar-widgets?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".sidebar_widget.archive", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/sidebar-widgets?archived=1");
+      },
+    ));
+
+    // Set a page's ordered placement. The form posts a `page_key` + zero or
+    // more `slug` checkbox values; the order is the form's submitted order
+    // (checkbox values arrive in document order). An empty selection clears
+    // the page's sidebar.
+    router.post("/admin/sidebar-widgets/placement", _pageOrApi(false,
+      W("sidebar_widget.place", async function (req, res) {
+        var body = req.body || {};
+        var pageKey = typeof body.page_key === "string" ? body.page_key : "";
+        var slugs = _sidebarPlacementSlugs(body);
+        var out;
+        try { out = await sidebarWidgets.setPagePlacement(pageKey, slugs); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, out);
+        return { id: pageKey };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var pageKey = typeof body.page_key === "string" ? body.page_key : "";
+        var slugs = _sidebarPlacementSlugs(body);
+        try { await sidebarWidgets.setPagePlacement(pageKey, slugs); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/sidebar-widgets?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".sidebar_widget.place", outcome: "success", metadata: { page_key: pageKey, count: slugs.length } });
+        _redirect(res, "/admin/sidebar-widgets?placed=1");
+      },
+    ));
+  }
+
   // ---- search suggestions ---------------------------------------------
   // Operator curation for the header autocomplete dropdown: featured
   // suggestions (typing "free" surfaces "Free shipping over $50") plus a
@@ -13129,6 +13740,10 @@ var DASHBOARD_LAYOUT =
   "  <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n" +
   "  <meta name=\"robots\" content=\"noindex,nofollow\">\n" +
   "  <title>{{page_title}} — {{shop_name}}</title>\n" +
+  "  <link rel=\"icon\" type=\"image/svg+xml\" href=\"/assets/brand/favicon.svg\">\n" +
+  "  <link rel=\"icon\" type=\"image/png\" href=\"/assets/brand/favicon.png\">\n" +
+  "  <link rel=\"apple-touch-icon\" href=\"/assets/brand/favicon.png\">\n" +
+  "  <meta name=\"theme-color\" content=\"#08080a\">\n" +
   "  RAW_ADMIN_CSS\n" +
   "</head>\n" +
   "<body>\n" +
@@ -13431,6 +14046,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "inventory-transfers", href: "/admin/inventory/transfers", label: "Transfers",       requires: "stockTransfers" },
   { key: "inventory-writeoffs", href: "/admin/inventory/writeoffs", label: "Write-offs",      requires: "inventoryWriteoffs" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
+  { key: "inbox",        href: "/admin/inbox",        label: "Inbox", requires: "inbox", badge: true },
   { key: "quotes",       href: "/admin/quotes",       label: "Quotes",       requires: "quotes" },
   { key: "carts",        href: "/admin/carts",        label: "Abandoned carts", requires: "carts" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
@@ -13467,6 +14083,8 @@ var ADMIN_NAV_ITEMS = [
   { key: "pick-lists",   href: "/admin/pick-lists",   label: "Pick lists",   requires: "pickLists" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
   { key: "promo-banners", href: "/admin/promo-banners", label: "Promo banners", requires: "promoBanners" },
+  { key: "suggestions",  href: "/admin/suggestions",  label: "Suggestion box", requires: "suggestionBox" },
+  { key: "sidebar-widgets", href: "/admin/sidebar-widgets", label: "Sidebar widgets", requires: "sidebarWidgets" },
   { key: "campaigns",    href: "/admin/campaigns",    label: "Email campaigns", requires: "emailCampaigns" },
   { key: "blog",         href: "/admin/blog",         label: "Blog",         requires: "blog" },
   { key: "help",         href: "/admin/help",         label: "Help center",  requires: "knowledgeBase" },
@@ -13488,12 +14106,34 @@ function _adminNav(active, available) {
   var links = ADMIN_NAV_ITEMS.filter(function (it) {
     return !it.requires || !available || available[it.requires];
   }).map(function (it) {
+    // A badge-bearing nav item (the inbox) carries an unread-count
+    // placeholder spliced post-render from the per-request ALS store, so
+    // the count is current on every page without each render call threading
+    // it. A non-badge item renders unchanged.
+    var badge = it.badge ? "{{INBOX_BADGE}}" : "";
     return "<a href=\"" + it.href + "\"" + (it.key === active ? " class=\"active\" aria-current=\"page\"" : "") + ">" +
-      _htmlEscape(it.label) + "</a>";
+      _htmlEscape(it.label) + badge + "</a>";
   }).join("");
   return "<nav class=\"admin-nav\"><div class=\"admin-nav__inner\">" + links + "</div></nav>";
 }
 
+// Replace the inbox nav badge placeholder with the per-request unread
+// count read from the ALS store. A zero count renders no pill (an empty
+// badge is noise); a positive count renders a small count pill, capped at
+// "99+" so the nav layout stays stable. Reached outside a request (no
+// store) the placeholder collapses to empty.
+function _injectAdminInboxBadge(html) {
+  if (typeof html !== "string" || html.indexOf("{{INBOX_BADGE}}") === -1) return html;
+  var store = _csrfAls.getStore();
+  var n = (store && Number(store.inbox_unread)) || 0;
+  var pill = "";
+  if (n > 0) {
+    var label = n > 99 ? "99+" : String(n);
+    pill = " <span class=\"nav-badge\" aria-label=\"" + _htmlEscape(label) + " unread\">" + _htmlEscape(label) + "</span>";
+  }
+  return html.split("{{INBOX_BADGE}}").join(pill);
+}
+
 function _renderAdminShell(shopName, subtitle, bodyHtml, active, available) {
   var html = _renderTemplate(DASHBOARD_LAYOUT, {
     shop_name:    shopName || "blamejs.shop",
@@ -13506,10 +14146,11 @@ function _renderAdminShell(shopName, subtitle, bodyHtml, active, available) {
   // Splice the admin body literally so a `$`-bearing fragment can't trip
   // `String.replace`'s dollar substitution. See `_spliceRaw`.
   html = _spliceRaw(html, "RAW_BODY", bodyHtml);
-  // Token every admin POST form with the per-request double-submit CSRF value
-  // (seeded on the ALS by mount()'s sync middleware). Single funnel — every
-  // authenticated admin page assembles here — so this is the one place the
-  // field needs injecting.
+  // Stamp the per-request inbox unread count into the nav badge (seeded on
+  // the ALS by mount()'s inbox-badge middleware), then token every admin
+  // POST form with the per-request double-submit CSRF value (also ALS-
+  // seeded). Single funnel — every authenticated admin page assembles here.
+  html = _injectAdminInboxBadge(html);
   return _injectAdminCsrfFields(html);
 }
 
@@ -14771,6 +15412,28 @@ function renderAdminOrder(opts) {
       opts.note_authors || [], opts.note_visibility || []);
   }
 
+  // Partial-refund panel — only when a payment provider is wired AND the
+  // order has a captured intent (`can_refund`) AND a balance remains. The
+  // operator types a decimal amount capped at the remaining balance; the
+  // backend re-validates the cap before any money moves. Refund banners
+  // (`refund_done` / `refund_err`) ride the same PRG pattern as the others.
+  var refundPanel = "";
+  if (opts.can_refund) {
+    refundPanel = _orderRefundPanel(o,
+      Number(opts.refunded_minor) || 0,
+      Number(opts.refundable_minor) || 0,
+      opts.refund_done ? "<div class=\"banner banner--ok\">Refund issued.</div>" : "",
+      opts.refund_err ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.refund_err) + "</div>" : "");
+  }
+
+  // Order timeline panel — only when the timeline primitive is wired. A
+  // single chronological feed across every post-checkout source, escaped
+  // at render (titles / bodies are operator + system + carrier free text).
+  var timelinePanel = "";
+  if (opts.can_timeline) {
+    timelinePanel = _orderTimelinePanel(opts.timeline || []);
+  }
+
   var body =
     "<section class=\"mw-48\">" +
       "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/orders\">&larr; Orders</a></div>" +
@@ -14789,6 +15452,8 @@ function renderAdminOrder(opts) {
       "<div class=\"panel mt\"><h3 class=\"subhead\">Actions</h3>" +
         "<div class=\"order-actions\">" + actions + "</div>" +
       "</div>" +
+      refundPanel +
+      timelinePanel +
       documentsPanel +
       resendPanel +
       notesPanel +
@@ -14870,6 +15535,147 @@ function _orderNotesPanel(orderId, notes, doneBanner, errBanner, authors, visibi
   "</div>";
 }
 
+// Refund panel for the order detail. States the order total, how much is
+// already refunded, and how much remains, then offers a partial-refund
+// form (a decimal amount capped at the remaining balance) that POSTs to
+// the `/refund/partial` route. The amount input's max + step are derived
+// from the currency exponent (display hints only — the backend re-parses
+// via b.money and enforces the cap), and the form is omitted once the
+// order is fully refunded. The full-refund button lives in the Actions
+// panel (a legal FSM transition); this panel owns the partial path.
+function _orderRefundPanel(o, refundedMinor, refundableMinor, doneBanner, errBanner) {
+  var currency = o.currency;
+  var totalFmt     = pricing.format(Number(o.grand_total_minor) || 0, currency);
+  var refundedFmt  = pricing.format(refundedMinor, currency);
+  var refundableFmt = pricing.format(refundableMinor, currency);
+  var summary =
+    "<p class=\"refund-summary\">" +
+      "Order total " + _htmlEscape(totalFmt) +
+      " · refunded " + _htmlEscape(refundedFmt) +
+      " · refundable " + _htmlEscape(refundableFmt) +
+    "</p>";
+  var form;
+  if (refundableMinor > 0) {
+    // The currency exponent sets the input's decimal granularity: a 2-dp
+    // currency steps in 0.01, a 0-dp currency (JPY) steps in 1. The max is
+    // the remaining balance as a decimal string built from the same money
+    // primitive so the form hint and the server cap agree.
+    var exp = 2;
+    try { exp = b.money.CURRENCIES[currency]; if (typeof exp !== "number") exp = 2; } catch (_e) { exp = 2; }
+    var step = exp <= 0 ? "1" : "0." + new Array(exp).join("0") + "1";
+    var maxDecimal;
+    try { maxDecimal = b.money.fromMinorUnits(BigInt(refundableMinor), currency).toString().replace(/\s+[A-Z]{3}$/, ""); }
+    catch (_me) { maxDecimal = String(refundableMinor); }
+    form =
+      "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(o.id) + "/refund/partial\" class=\"return-action\">" +
+        "<label class=\"form-field\"><span>Refund amount (" + _htmlEscape(currency) + ")</span>" +
+          "<input type=\"number\" name=\"amount\" inputmode=\"decimal\" min=\"" + _htmlEscape(step) + "\" max=\"" + _htmlEscape(maxDecimal) + "\" step=\"" + _htmlEscape(step) + "\" placeholder=\"" + _htmlEscape(maxDecimal) + "\" required>" +
+          "<small>Up to " + _htmlEscape(refundableFmt) + " remaining. The amount is charged back through the payment provider.</small>" +
+        "</label>" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Issue refund</button>" +
+      "</form>";
+  } else {
+    form = "<p class=\"empty\">This order is fully refunded — nothing remains to refund.</p>";
+  }
+  return "<div class=\"panel mt\"><h3 class=\"subhead\">Refunds</h3>" +
+    doneBanner + errBanner + summary + form +
+  "</div>";
+}
+
+// Order timeline panel for the order detail. Renders the aggregated
+// operator-facing event feed (newest-first) as a vertical timeline. Every
+// interpolated value (title / body / actor) is operator-, system-, or
+// carrier-supplied free text, so each is escaped at render. A link, when
+// present, is a carrier tracking URL — rendered with rel="noopener
+// nofollow" + target="_blank" like the tracking panel's links.
+function _orderTimelinePanel(events) {
+  var items = (events || []).map(function (e) {
+    var when  = "<span class=\"tl-when\">" + _htmlEscape(_fmtDate(e.occurred_at)) + "</span>";
+    var title = "<span class=\"tl-title\">" + _htmlEscape(String(e.title == null ? "" : e.title)) + "</span>";
+    var bodyLine = e.body
+      ? "<div class=\"tl-body\">" + _htmlEscape(String(e.body)) + "</div>"
+      : "";
+    var actorLine = e.actor
+      ? "<div class=\"tl-actor\">" + _htmlEscape(String(e.actor)) + "</div>"
+      : "";
+    var linkLine = e.link
+      ? "<div><a href=\"" + _htmlEscape(String(e.link)) + "\" rel=\"noopener nofollow\" target=\"_blank\">Track ↗</a></div>"
+      : "";
+    return "<li>" +
+      "<div>" + when + " · " + title + "</div>" +
+      bodyLine + actorLine + linkLine +
+    "</li>";
+  }).join("");
+  return "<div class=\"panel mt\"><h3 class=\"subhead\">Timeline</h3>" +
+    (items
+      ? "<ul class=\"timeline\">" + items + "</ul>"
+      : "<p class=\"empty\">No recorded events for this order yet.</p>") +
+  "</div>";
+}
+
+// Operator inbox screen. Lists the role's notifications newest-first with
+// each message's severity pill, subject, body, and timestamp, plus the
+// per-message actions (mark read on an unread one, archive on any active
+// one). Subject + body are application-supplied (a new-order ping today,
+// other system events tomorrow), so both are escaped at render. A toggle
+// link switches between the active feed and the archive. Every form
+// renders through _renderAdminShell, which tokens each POST.
+function _renderAdminInbox(opts) {
+  opts = opts || {};
+  var messages = opts.messages || [];
+  var includeArchived = !!opts.include_archived;
+  var done   = opts.done ? "<div class=\"banner banner--ok\">Inbox updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var items = messages.map(function (m) {
+    var enc = _htmlEscape(encodeURIComponent(m.id));
+    var isUnread   = m.read_at == null;
+    var isArchived = m.archived_at != null;
+    var sev = String(m.severity || "info");
+    // Map severity to the existing status-pill colour classes so the feed
+    // reads at a glance without new colour tokens.
+    var sevClass = sev === "critical" || sev === "urgent" ? "cancelled"
+                 : (sev === "warning" ? "pending" : "paid");
+    var pills =
+      "<span class=\"status-pill " + _htmlEscape(sevClass) + "\">" + _htmlEscape(sev) + "</span>" +
+      (isUnread ? "" : "<span class=\"status-pill\">Read</span>") +
+      (isArchived ? "<span class=\"status-pill refunded\">Archived</span>" : "");
+    var actions = "";
+    if (!isArchived) {
+      if (isUnread) {
+        actions += "<form method=\"post\" action=\"/admin/inbox/" + enc + "/read\" class=\"form-inline\">" +
+          "<button class=\"btn btn--ghost\" type=\"submit\">Mark read</button></form>";
+      }
+      actions += "<form method=\"post\" action=\"/admin/inbox/" + enc + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">Archive</button></form>";
+    }
+    return "<li class=\"" + (isUnread ? "unread" : "") + "\">" +
+      "<div class=\"inbox-meta\">" + _htmlEscape(_fmtDate(m.created_at)) + " " + pills + "</div>" +
+      "<div class=\"inbox-subject\">" + _htmlEscape(String(m.subject == null ? "" : m.subject)) + "</div>" +
+      "<div class=\"tl-body\">" + _htmlEscape(String(m.body == null ? "" : m.body)) + "</div>" +
+      (actions ? "<div class=\"actions-row\">" + actions + "</div>" : "") +
+    "</li>";
+  }).join("");
+
+  var toggle = includeArchived
+    ? "<a class=\"btn btn--ghost\" href=\"/admin/inbox\">Show active only</a>"
+    : "<a class=\"btn btn--ghost\" href=\"/admin/inbox?archived=1\">Include archived</a>";
+
+  var body =
+    "<section class=\"mw-48\">" +
+      "<h2>Inbox</h2>" +
+      "<p class=\"meta\">System notifications for your team — new orders, alerts, and other events. Mark a message read once you've actioned it, or archive it to clear it from the feed.</p>" +
+      done + notice +
+      "<div class=\"actions-row\">" + toggle + "</div>" +
+      "<div class=\"panel mt\">" +
+        (messages.length
+          ? "<ul class=\"inbox-list\">" + items + "</ul>"
+          : "<p class=\"empty\">" + (includeArchived ? "No messages." : "No new messages.") + "</p>") +
+      "</div>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Inbox", body, "inbox", opts.nav_available);
+}
+
 // Per-shipment carrier-label sub-panel for the order detail. Lists the
 // recorded labels (tracking number, broker, cost, status pill) with a
 // "Mark used" action on purchased ones, then a form to record a freshly-
@@ -15197,6 +16003,8 @@ function renderPickListPrint(opts) {
     "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">" +
     "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">" +
     "<meta name=\"robots\" content=\"noindex, nofollow\">" +
+    "<link rel=\"icon\" type=\"image/svg+xml\" href=\"/assets/brand/favicon.svg\">" +
+    "<link rel=\"icon\" type=\"image/png\" href=\"/assets/brand/favicon.png\">" +
     "<title>Pick list " + _htmlEscape(l.id.slice(0, 8)) + "</title>" + style + "</head><body>" +
     "<h1>" + _htmlEscape(shopName) + " — pick list</h1>" +
     "<p class=\"meta\">List " + _htmlEscape(l.id.slice(0, 8)) + " · location " + _htmlEscape(String(l.location_code)) +
@@ -18805,6 +19613,120 @@ function _announcementPatchFromForm(body) {
   return patch;
 }
 
+// ---- suggestion-box form coercion -----------------------------------
+
+// The responder string for a respondToSuggestion call. The signed-in
+// operator's id (stamped onto req by the role gate on the browser path, or
+// resolvable from the bearer) is the audit attribution; a console label is
+// the fallback so the responder field (which the primitive requires non-
+// empty) always lands a value. A hidden form `responder` is ignored — the
+// attribution comes from the authenticated actor, not the request body.
+function _suggestionResponder(req, _body) {
+  if (req && req.operatorActor && req.operatorActor.operator_id) {
+    return String(req.operatorActor.operator_id).slice(0, 200);
+  }
+  return "operator";
+}
+
+// ---- sidebar-widget form coercion -----------------------------------
+
+// Coerce the create form into the shape sidebarWidgets.defineWidget expects.
+// The kind determines the payload shape, so the coercion reads only the
+// fields that kind owns (the primitive refuses unknown payload keys). Every
+// numeric payload field is parsed to an integer; blank optional fields drop
+// out so the primitive applies its own validation. The schedule window
+// (starts_at / expires_at) is required by the primitive — a blank bound
+// defaults to "now" / "now + ~10 years" so an operator who just wants an
+// always-on widget doesn't have to fill the dates.
+function _sidebarWidgetPayloadFromForm(kind, body) {
+  function _int(v) {
+    if (v == null || String(v).trim() === "") return null;
+    var n = parseInt(String(v), 10);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (kind === "newsletter_signup") {
+    return { list_id: body.list_id, headline: body.headline, cta_label: body.cta_label };
+  }
+  if (kind === "recently_viewed") {
+    var rl = _int(body.limit);
+    return rl == null ? {} : { limit: rl };
+  }
+  if (kind === "trust_badges") {
+    var badges = typeof body.badges === "string"
+      ? body.badges.split(",").map(function (s) { return s.trim(); }).filter(function (s) { return s.length; })
+      : [];
+    return { badges: badges };
+  }
+  if (kind === "featured_collection") {
+    var out = { collection_slug: body.collection_slug };
+    var fl = _int(body.limit); if (fl != null) out.limit = fl;
+    return out;
+  }
+  if (kind === "social_proof") {
+    return { headline: body.headline, message_template: body.message_template };
+  }
+  if (kind === "size_chart") {
+    return { chart_slug: body.chart_slug };
+  }
+  if (kind === "live_visitors") {
+    var lv = {};
+    var win = _int(body.window_minutes); if (win != null) lv.window_minutes = win;
+    var thr = _int(body.min_threshold);  if (thr != null) lv.min_threshold  = thr;
+    return lv;
+  }
+  if (kind === "countdown_timer") {
+    var ct = {};
+    var target = _epochFromForm(body.target_at);
+    if (target != null) ct.target_at = target;
+    ct.completed_label = body.completed_label;
+    return ct;
+  }
+  // sticky_addtocart
+  return { variant_slug: body.variant_slug };
+}
+
+function _sidebarWidgetFromForm(body) {
+  body = body || {};
+  var kind = typeof body.kind === "string" ? body.kind : "";
+  var out = {
+    slug:     typeof body.slug === "string" ? body.slug.trim() : body.slug,
+    title:    body.title,
+    kind:     kind,
+    payload:  _sidebarWidgetPayloadFromForm(kind, body),
+    audience: typeof body.audience === "string" && body.audience ? body.audience : "all",
+  };
+  var pr = body.priority;
+  if (pr != null && String(pr).trim() !== "") {
+    var pn = parseInt(String(pr), 10);
+    if (Number.isFinite(pn)) out.priority = pn;
+  }
+  // The schedule window is mandatory at the primitive layer. A blank start
+  // means "live now"; a blank expiry means "no end" — represented as a
+  // far-future bound so the always-on case needs no operator dates.
+  var sa = _epochFromForm(body.starts_at);
+  out.starts_at = sa != null ? sa : Date.now();
+  var ea = _epochFromForm(body.expires_at);
+  out.expires_at = ea != null ? ea : (out.starts_at + 315360000000); // +10y
+  return out;
+}
+
+// Read the ordered placement slugs from the placement form. A multi-value
+// `slug` field arrives as an array (multiple checked boxes) or a single
+// string (one box) or undefined (none) depending on the body parser; all
+// three normalise to an array. Each value is trimmed; blanks drop out. The
+// document order is the placement order.
+function _sidebarPlacementSlugs(body) {
+  body = body || {};
+  var raw = body.slug;
+  var arr = Array.isArray(raw) ? raw : (raw == null ? [] : [raw]);
+  var out = [];
+  for (var i = 0; i < arr.length; i += 1) {
+    var s = typeof arr[i] === "string" ? arr[i].trim() : "";
+    if (s.length) out.push(s);
+  }
+  return out;
+}
+
 // ---- search-suggestion form coercion --------------------------------
 
 // Read every featured suggestion for the curation table — through the
@@ -19118,6 +20040,297 @@ function renderAdminAnnouncements(opts) {
   return _renderAdminShell(opts.shop_name, "Announcements", bodyHtml, "announcements", opts.nav_available);
 }
 
+// ---- suggestion-box console -----------------------------------------
+
+var _ADMIN_SUGGESTION_STATUS_LABEL = {
+  open:                "Open",
+  under_consideration: "Under review",
+  planned:             "Planned",
+  shipped:             "Shipped",
+  declined:            "Not planned",
+  duplicate:           "Merged",
+};
+var _ADMIN_SUGGESTION_CATEGORY_LABEL = {
+  product_idea:    "Product idea",
+  feature_request: "Feature request",
+  improvement:     "Improvement",
+  complaint:       "Issue",
+  general:         "General",
+};
+
+// The suggestion triage list — a filterable table of customer-submitted
+// ideas with their net vote score + status, each linking to the detail
+// screen where the operator responds / archives / flags. Every echoed
+// customer free-text value (title) is _htmlEscape'd at the sink.
+function renderAdminSuggestions(opts) {
+  opts = opts || {};
+  var rows = opts.suggestions || [];
+  var responded = opts.responded ? "<div class=\"banner banner--ok\">Response saved.</div>" : "";
+  var archived  = opts.archived  ? "<div class=\"banner banner--ok\">Suggestion archived.</div>" : "";
+  var flagged   = opts.flagged   ? "<div class=\"banner banner--ok\">Spam flag updated.</div>" : "";
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var sf = opts.status_filter;
+  var cf = opts.category_filter;
+  var statusChips = ["open", "under_consideration", "planned", "shipped", "declined"].map(function (s) {
+    var on = (sf === s) ? " chip--on" : "";
+    return "<a class=\"chip" + on + "\" href=\"/admin/suggestions?status=" + s + "\">" + _htmlEscape(_ADMIN_SUGGESTION_STATUS_LABEL[s]) + "</a>";
+  }).join("");
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (sf == null && cf == null ? " chip--on" : "") + "\" href=\"/admin/suggestions\">All</a>" +
+    statusChips +
+    "</div>";
+
+  var bodyRows = rows.map(function (r) {
+    var enc = _htmlEscape(encodeURIComponent(r.id));
+    var statusKey = _ADMIN_SUGGESTION_STATUS_LABEL[r.status] ? r.status : "open";
+    var catLbl    = _ADMIN_SUGGESTION_CATEGORY_LABEL[r.category] || "General";
+    return "<tr>" +
+      "<td>" + _htmlEscape(r.title) + "</td>" +
+      "<td>" + _htmlEscape(catLbl) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(_ADMIN_SUGGESTION_STATUS_LABEL[statusKey]) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(Number(r.vote_count) || 0)) + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/suggestions/" + enc + "\">Review</a>" +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Title</th><th scope=\"col\">Category</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Votes</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No suggestions" + (sf ? " in this status" : " yet") + ".</p>";
+
+  var more = "";
+  if (opts.next_cursor) {
+    var moreHref = "/admin/suggestions?" +
+      (sf ? "status=" + _htmlEscape(encodeURIComponent(sf)) + "&" : "") +
+      (cf ? "category=" + _htmlEscape(encodeURIComponent(cf)) + "&" : "") +
+      "cursor=" + _htmlEscape(encodeURIComponent(opts.next_cursor));
+    more = "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"" + moreHref + "\">Load more</a></div>";
+  }
+
+  var bodyHtml = "<section><h2>Suggestion box</h2>" +
+    "<p class=\"meta\">Customer-submitted ideas. Respond to move an idea through the roadmap, archive a stale one, or flag spam. The public board lives at <code class=\"order-id\">/suggestions</code>.</p>" +
+    responded + archived + flagged + notice + chips + table + more + "</section>";
+  return _renderAdminShell(opts.shop_name, "Suggestion box", bodyHtml, "suggestions", opts.nav_available);
+}
+
+// One suggestion's detail + the operator respond / archive / flag controls.
+// The respond form drives the roadmap FSM; the response textarea is the
+// public-visible reply (optional — a blank reply is a status-only move).
+function renderAdminSuggestion(opts) {
+  opts = opts || {};
+  var s = opts.suggestion;
+  if (!s) {
+    var nf = "<section><h2>Suggestion</h2><p class=\"empty\">Suggestion not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/suggestions\">Back to suggestions</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Suggestion", nf, "suggestions", opts.nav_available);
+  }
+  var responded = opts.responded ? "<div class=\"banner banner--ok\">Response saved.</div>" : "";
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = _htmlEscape(encodeURIComponent(s.id));
+  var isArchived = s.archived_at != null;
+  var isTerminal = ["shipped", "declined", "duplicate"].indexOf(s.status) !== -1;
+  var statusKey = _ADMIN_SUGGESTION_STATUS_LABEL[s.status] ? s.status : "open";
+  var catLbl    = _ADMIN_SUGGESTION_CATEGORY_LABEL[s.category] || "General";
+
+  // The destination statuses an operator can move to from the current
+  // status. duplicate is excluded (it requires a canonical id — operators
+  // merge via the API). open is the entry state and not a response target.
+  var allowed = {
+    open:                ["under_consideration", "planned", "shipped", "declined"],
+    under_consideration: ["planned", "shipped", "declined"],
+    planned:             ["shipped", "declined"],
+  };
+  var nextStatuses = allowed[s.status] || [];
+  var statusOpts = nextStatuses.map(function (st) {
+    return "<option value=\"" + st + "\">" + _htmlEscape(_ADMIN_SUGGESTION_STATUS_LABEL[st]) + "</option>";
+  }).join("");
+
+  var existingResponse = (s.response_text && String(s.response_text).trim().length)
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Current response</h3><p>" + _htmlEscape(s.response_text) + "</p>" +
+        (s.response_by ? "<p class=\"meta\">By " + _htmlEscape(s.response_by) + "</p>" : "") + "</div>"
+    : "";
+
+  var respondForm = (isArchived || isTerminal || !nextStatuses.length)
+    ? "<p class=\"empty\">" + (isArchived ? "This suggestion is archived." : "This suggestion is in a terminal status and can't be moved further.") + "</p>"
+    : "<div class=\"panel mw-40\"><h3 class=\"subhead\">Respond</h3>" +
+        "<form method=\"post\" action=\"/admin/suggestions/" + enc + "/respond\">" +
+          "<label class=\"form-field\"><span>Move to</span><select name=\"status\">" + statusOpts + "</select></label>" +
+          "<label class=\"form-field\"><span>Public reply (optional)</span><textarea name=\"response\" maxlength=\"5000\" rows=\"4\" placeholder=\"Shown on the public board next to this idea.\"></textarea></label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save response</button></div>" +
+        "</form>" +
+      "</div>";
+
+  // Archive + spam-flag controls. The flag toggle posts the desired next
+  // state (flag → 1, un-flag → 0).
+  var spamFlagged = !!s.spam_flagged;
+  var manageRow = isArchived
+    ? ""
+    : "<div class=\"actions-row\">" +
+        "<form method=\"post\" action=\"/admin/suggestions/" + enc + "/flag\" class=\"form-inline\">" +
+          "<input type=\"hidden\" name=\"flagged\" value=\"" + (spamFlagged ? "0" : "1") + "\">" +
+          "<button class=\"btn btn--ghost\" type=\"submit\">" + (spamFlagged ? "Unflag spam" : "Flag as spam") + "</button>" +
+        "</form>" +
+        "<form method=\"post\" action=\"/admin/suggestions/" + enc + "/archive\" class=\"form-inline\">" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Archive</button>" +
+        "</form>" +
+      "</div>";
+
+  var bodyHtml = "<section><h2>Suggestion</h2>" + responded + notice +
+    "<div class=\"panel\">" +
+      "<h3 class=\"subhead\">" + _htmlEscape(s.title) + "</h3>" +
+      "<dl class=\"detail-grid\">" +
+        "<div><dt>Category</dt><dd>" + _htmlEscape(catLbl) + "</dd></div>" +
+        "<div><dt>Status</dt><dd><span class=\"status-pill\">" + _htmlEscape(_ADMIN_SUGGESTION_STATUS_LABEL[statusKey]) + "</span></dd></div>" +
+        "<div><dt>Votes</dt><dd>" + _htmlEscape(String(Number(s.vote_count) || 0)) + "</dd></div>" +
+        "<div><dt>Spam</dt><dd>" + (spamFlagged ? "Flagged" : "No") + "</dd></div>" +
+      "</dl>" +
+      "<p>" + _htmlEscape(s.body) + "</p>" +
+    "</div>" +
+    existingResponse +
+    respondForm +
+    manageRow +
+    "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/suggestions\">Back to suggestions</a></div>" +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Suggestion", bodyHtml, "suggestions", opts.nav_available);
+}
+
+// ---- sidebar-widget console -----------------------------------------
+
+var _SIDEBAR_KIND_LABEL = {
+  newsletter_signup:   "Newsletter signup",
+  recently_viewed:     "Recently viewed",
+  trust_badges:        "Trust badges",
+  featured_collection: "Featured collection",
+  social_proof:        "Social proof",
+  size_chart:          "Size chart",
+  live_visitors:       "Live visitors",
+  countdown_timer:     "Countdown timer",
+  sticky_addtocart:    "Sticky add-to-cart",
+};
+
+// The per-kind payload field set for the create form. Each entry is the HTML
+// for the kind's payload inputs, shown/hidden by the kind <select> via a
+// small island; with no JS every field is visible and the operator fills the
+// ones their chosen kind needs (the primitive refuses payload keys that don't
+// belong to the kind, so a wrong-kind field is a clean validation error).
+function _sidebarPayloadFields() {
+  return "<fieldset class=\"panel\"><legend>Content</legend>" +
+    "<p class=\"meta\">Fill the fields for the widget kind you chose above.</p>" +
+    // newsletter_signup
+    _setupField("List id (newsletter)", "list_id", "", "text", "newsletter_signup", " maxlength=\"120\"") +
+    _setupField("Headline", "headline", "", "text", "newsletter_signup / social_proof", " maxlength=\"200\"") +
+    _setupField("CTA label", "cta_label", "", "text", "newsletter_signup", " maxlength=\"80\"") +
+    // social_proof
+    "<label class=\"form-field\"><span>Message</span><textarea name=\"message_template\" maxlength=\"500\" rows=\"2\"></textarea><small>social_proof</small></label>" +
+    // trust_badges
+    _setupField("Badge slugs (comma-separated)", "badges", "", "text", "trust_badges", " maxlength=\"500\"") +
+    // featured_collection
+    _setupField("Collection slug", "collection_slug", "", "text", "featured_collection", " maxlength=\"120\"") +
+    // size_chart
+    _setupField("Chart slug", "chart_slug", "", "text", "size_chart", " maxlength=\"120\"") +
+    // sticky_addtocart
+    _setupField("Variant slug", "variant_slug", "", "text", "sticky_addtocart", " maxlength=\"120\"") +
+    // recently_viewed / featured_collection limit + live_visitors + countdown
+    _setupField("Limit", "limit", "", "number", "recently_viewed / featured_collection", " min=\"1\" max=\"24\"") +
+    _setupField("Window minutes", "window_minutes", "", "number", "live_visitors", " min=\"1\" max=\"240\"") +
+    _setupField("Min threshold", "min_threshold", "", "number", "live_visitors", " min=\"0\"") +
+    "<label class=\"form-field\"><span>Countdown target</span><input type=\"datetime-local\" name=\"target_at\"><small>countdown_timer</small></label>" +
+    _setupField("Completed label", "completed_label", "", "text", "countdown_timer", " maxlength=\"200\"") +
+    "</fieldset>";
+}
+
+// The widget definitions table + the create form + the per-page placement
+// editor. Every echoed operator free-text value (title, slug) is
+// _htmlEscape'd at the sink.
+function renderAdminSidebarWidgets(opts) {
+  opts = opts || {};
+  var widgets   = opts.widgets || [];
+  var placements = opts.placements || {};
+  var pageKeys  = opts.page_keys || [];
+  var created   = opts.created   ? "<div class=\"banner banner--ok\">Widget saved.</div>" : "";
+  var updated   = opts.updated   ? "<div class=\"banner banner--ok\">Widget updated.</div>" : "";
+  var archived  = opts.archived  ? "<div class=\"banner banner--ok\">Widget archived.</div>" : "";
+  var placed    = opts.placed    ? "<div class=\"banner banner--ok\">Page placement saved.</div>" : "";
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var widgetRows = widgets.map(function (w) {
+    var enc = _htmlEscape(encodeURIComponent(w.slug));
+    var isArchived = w.archived_at != null;
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(w.slug) + "</code></td>" +
+      "<td>" + _htmlEscape(w.title) + "</td>" +
+      "<td>" + _htmlEscape(_SIDEBAR_KIND_LABEL[w.kind] || w.kind) + "</td>" +
+      "<td>" + _htmlEscape(w.audience) + "</td>" +
+      "<td><span class=\"status-pill " + (isArchived ? "cancelled" : "paid") + "\">" + (isArchived ? "archived" : "active") + "</span></td>" +
+      "<td><div class=\"actions-row\">" +
+        (isArchived ? "" :
+          "<form method=\"post\" action=\"/admin/sidebar-widgets/" + enc + "/archive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = widgets.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Title</th><th scope=\"col\">Kind</th><th scope=\"col\">Audience</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + widgetRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No sidebar widgets yet.</p>";
+
+  var kindOpts = Object.keys(_SIDEBAR_KIND_LABEL).map(function (k) {
+    return "<option value=\"" + k + "\">" + _htmlEscape(_SIDEBAR_KIND_LABEL[k]) + "</option>";
+  }).join("");
+  var audienceOpts = ["all", "guest", "logged_in"].map(function (au) {
+    return "<option value=\"" + au + "\">" + au + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Define a widget</h3>" +
+      "<p class=\"meta\">Each widget has a stable slug + a kind that decides its content shape. Define it here, then place it on a page below. Leave the schedule blank for an always-on widget.</p>" +
+      "<form method=\"post\" action=\"/admin/sidebar-widgets\">" +
+        _setupField("Slug", "slug", "", "text", "Lowercase, hyphenated — a stable id.", " maxlength=\"80\" required") +
+        _setupField("Title", "title", "", "text", "Shown as the widget heading.", " maxlength=\"200\" required") +
+        "<label class=\"form-field\"><span>Kind</span><select name=\"kind\">" + kindOpts + "</select></label>" +
+        "<label class=\"form-field\"><span>Audience</span><select name=\"audience\">" + audienceOpts + "</select></label>" +
+        _setupField("Priority", "priority", "", "number", "Higher shows first in a list.", " min=\"0\"") +
+        "<label class=\"form-field\"><span>Starts at (optional)</span><input type=\"datetime-local\" name=\"starts_at\"></label>" +
+        "<label class=\"form-field\"><span>Expires at (optional)</span><input type=\"datetime-local\" name=\"expires_at\"></label>" +
+        _sidebarPayloadFields() +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Define widget</button></div>" +
+      "</form>" +
+    "</div>";
+
+  // Per-page placement editor. For each page, a form of checkboxes (one per
+  // active widget, pre-checked when already placed) posts the ordered slug
+  // set. Archived widgets are omitted (they can't be placed).
+  var activeWidgets = widgets.filter(function (w) { return w.archived_at == null; });
+  var placementForms = pageKeys.map(function (key) {
+    var placedSlugs = placements[key] || [];
+    var boxes = activeWidgets.map(function (w) {
+      var checked = placedSlugs.indexOf(w.slug) !== -1 ? " checked" : "";
+      return "<label class=\"kv\"><input type=\"checkbox\" name=\"slug\" value=\"" + _htmlEscape(w.slug) + "\"" + checked + "> " +
+        _htmlEscape(w.title) + " <span class=\"meta\">(" + _htmlEscape(_SIDEBAR_KIND_LABEL[w.kind] || w.kind) + ")</span></label>";
+    }).join("");
+    var inner = activeWidgets.length
+      ? boxes + "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save " + _htmlEscape(key) + " sidebar</button></div>"
+      : "<p class=\"empty\">Define a widget first.</p>";
+    return "<div class=\"panel\"><h3 class=\"subhead\">" + _htmlEscape(key) + " page</h3>" +
+      "<form method=\"post\" action=\"/admin/sidebar-widgets/placement\">" +
+        "<input type=\"hidden\" name=\"page_key\" value=\"" + _htmlEscape(key) + "\">" +
+        inner +
+      "</form>" +
+    "</div>";
+  }).join("");
+  var placementSection = "<section class=\"mt\"><h3 class=\"subhead\">Page placement</h3>" +
+    "<p class=\"meta\">Choose which widgets render in each page's right rail, in checkbox order.</p>" +
+    placementForms + "</section>";
+
+  var bodyHtml = "<section><h2>Sidebar widgets</h2>" +
+    created + updated + archived + placed + notice +
+    table + createForm + placementSection + "</section>";
+  return _renderAdminShell(opts.shop_name, "Sidebar widgets", bodyHtml, "sidebar-widgets", opts.nav_available);
+}
+
 // Search-suggestions curation screen: the featured-suggestion table (with
 // a per-row inline priority/status edit + a delete), a create form, and a
 // read-only "Popular searches" view over the recent query log. Every