@blamejs/blamejs-shop 0.1.29 → 0.1.31

package/lib/storefront.js

@@ -165,6 +165,7 @@ var LAYOUT =
   "          <li><a href=\"/categories\">Categories</a></li>\n" +
   "          <li><a href=\"/?sort=new\">New arrivals</a></li>\n" +
   "          <li><a href=\"/?sort=sale\">On sale</a></li>\n" +
+  "          <li><a href=\"/compare\">Compare</a></li>\n" +
   "          <li><a href=\"/cart\">Cart</a></li>\n" +
   "        </ul>\n" +
   "      </div>\n" +
@@ -745,9 +746,11 @@ var PRODUCT_PAGE =
   "        </div>\n" +
   "      </div>\n" +
   "      RAW_WISHLIST_PLACEHOLDER\n" +
+  "      RAW_COMPARE_PLACEHOLDER\n" +
   "    </div>\n" +
   "  </div>\n" +
   "  RAW_REVIEWS_PLACEHOLDER\n" +
+  "  RAW_QA_PLACEHOLDER\n" +
   "</section>\n";
 
 // PDP gallery markup — composed once per render call from the
@@ -969,6 +972,132 @@ function _reviewMessagePage(opts, heading, message, cta) {
   });
 }
 
+// Builds the PDP Product Q&A block from the published questions + their
+// approved answers. Renders the "no questions yet" empty state when the
+// product has none; `ctaHtml` is the "Ask a question" call-to-action
+// (resolved by the route). Reuses the reviews section's theme classes
+// so no new CSS ships. Mirrors the edge renderer
+// (`worker/render/product.js`) byte-for-byte so both render paths stay
+// in sync.
+function _buildProductQa(questions, ctaHtml) {
+  var esc = b.template.escapeHtml;
+  questions = questions || [];
+
+  var head;
+  if (questions.length > 0) {
+    head = "<p class=\"reviews__count\">" + questions.length +
+      (questions.length === 1 ? " question answered" : " questions answered") + "</p>";
+  } else {
+    head = "<p class=\"reviews__empty\">No questions yet. Be the first to ask about this product.</p>";
+  }
+
+  var list = "";
+  for (var i = 0; i < questions.length; i += 1) {
+    var q = questions[i];
+    var answers = q.answers || [];
+    var answerHtml = "";
+    for (var j = 0; j < answers.length; j += 1) {
+      var a = answers[j];
+      var who = Number(a.is_operator) === 1
+        ? "<span class=\"review__verified\">Answered by the seller</span>"
+        : (a.author === "system"
+            ? "<span class=\"review__verified\">Automated answer</span>"
+            : "<span class=\"review__verified\">Customer answer</span>");
+      var pinned = Number(a.pinned) === 1
+        ? "<span class=\"review__verified\">Top answer</span>"
+        : "";
+      answerHtml +=
+        "<li class=\"review qa__answer\">" +
+          "<div class=\"review__meta\">" + who + pinned + "</div>" +
+          "<p class=\"review__body\">" + esc(String(a.body)) + "</p>" +
+        "</li>";
+    }
+    var answerList = answerHtml
+      ? "<ul class=\"reviews__list qa__answers\">" + answerHtml + "</ul>"
+      : "<p class=\"reviews__empty\">Awaiting an answer.</p>";
+    list +=
+      "<li class=\"review qa__question\">" +
+        "<div class=\"review__head\">" +
+          "<h3 class=\"review__title\">" + esc(String(q.body)) + "</h3>" +
+        "</div>" +
+        answerList +
+      "</li>";
+  }
+  var listHtml = list ? "<ul class=\"reviews__list\">" + list + "</ul>" : "";
+
+  return "<section class=\"reviews qa\" aria-labelledby=\"qa-title\">" +
+           "<h2 id=\"qa-title\" class=\"reviews__heading\">Questions &amp; answers</h2>" +
+           head +
+           listHtml +
+           (ctaHtml || "") +
+         "</section>";
+}
+
+var QA_FORM_PAGE =
+  "<section class=\"review-form-page\">\n" +
+  "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
+  "    <ol>\n" +
+  "      <li><a href=\"/\">Shop</a></li>\n" +
+  "      <li><a href=\"/products/{{slug}}\">{{title}}</a></li>\n" +
+  "      <li aria-current=\"page\">Ask a question</li>\n" +
+  "    </ol>\n" +
+  "  </nav>\n" +
+  "  <h1 class=\"review-form-page__title\">Ask about {{title}}</h1>\n" +
+  "  RAW_NOTICE_PLACEHOLDER\n" +
+  "  <form class=\"review-form\" method=\"post\" action=\"/products/{{slug}}/question\">\n" +
+  "    <label class=\"form-field\">\n" +
+  "      <span class=\"form-field__label\">Your question</span>\n" +
+  "      <textarea name=\"body\" maxlength=\"4000\" rows=\"6\" required></textarea>\n" +
+  "    </label>\n" +
+  "    <button type=\"submit\" class=\"btn-primary\">Submit question</button>\n" +
+  "  </form>\n" +
+  "</section>\n";
+
+// Auth-gated question form. `opts.product` carries { title, slug };
+// `opts.notice` is an optional error string rendered above the form
+// (e.g. a validation rejection bounced back from POST).
+function renderQuestionForm(opts) {
+  var esc = b.template.escapeHtml;
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body = _render(QA_FORM_PAGE, {
+    title: opts.product.title,
+    slug:  opts.product.slug,
+  })
+    .replace("RAW_NOTICE_PLACEHOLDER", notice);
+  return _wrap({
+    title:      "Ask about " + opts.product.title,
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// Generic single-message page for the Q&A flow (submission thank-you).
+// `cta` is an optional { href, label }. Reuses the review-message
+// layout classes.
+function _qaMessagePage(opts, heading, message, cta) {
+  var esc = b.template.escapeHtml;
+  var ctaHtml = cta
+    ? "<a class=\"btn-primary\" href=\"" + esc(cta.href) + "\">" + esc(cta.label) + "</a>"
+    : "";
+  var body =
+    "<section class=\"review-message\">" +
+      "<h1 class=\"review-message__title\">" + esc(heading) + "</h1>" +
+      "<p class=\"review-message__lede\">" + esc(message) + "</p>" +
+      ctaHtml +
+    "</section>";
+  return _wrap({
+    title:      heading,
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Remove control for a wishlist entry — a form POST back through the
 // toggle route with `return_to` so the customer lands back on the
 // account page (not the product PDP the default toggle returns to).
@@ -1035,6 +1164,177 @@ function renderWishlist(opts) {
   });
 }
 
+// Compare page notice banner — surfaced after a toggle / a full-basket
+// refusal. The route passes a short message key; unknown keys render
+// nothing so a forged `?notice=` query can't inject arbitrary copy.
+var COMPARE_NOTICES = {
+  added:   "Added to your comparison.",
+  removed: "Removed from your comparison.",
+  full:    "Your comparison is full (4 products max). Remove one to add another.",
+  cleared: "Comparison cleared.",
+};
+function _compareNotice(key) {
+  var msg = COMPARE_NOTICES[key];
+  if (!msg) return "";
+  return "<p class=\"compare-page__notice\" role=\"status\">" + b.template.escapeHtml(msg) + "</p>";
+}
+
+// Side-by-side comparison table. `opts.columns` is the resolved per-
+// product column list in basket order:
+//   { product_id, product, hero_media, price, available }
+// where `product` is null for a product archived / deleted between the
+// add and this render (orphan-tolerant — the column renders "no longer
+// available" and a remove control, never crashes the table). `opts.rows`
+// is the attribute matrix from product-compare's `compareTable`:
+//   [ { attribute: { slug, label, format }, values_per_product: [...] } ]
+// each `values_per_product` entry positionally aligned with `columns`.
+// The currency/number/boolean formatting happens here (the display
+// layer), not in the primitive.
+function _compareCellValue(value, format) {
+  var esc = b.template.escapeHtml;
+  if (value == null) return "<span class=\"compare-cell--empty\" aria-hidden=\"true\">—</span><span class=\"sr-only\">Not specified</span>";
+  if (format === "currency") {
+    var minor = Number(value);
+    if (!Number.isFinite(minor)) return esc(String(value));
+    return esc(pricing.format(Math.round(minor), "USD"));
+  }
+  if (format === "boolean") {
+    return value ? "Yes" : "No";
+  }
+  return esc(String(value));
+}
+
+function renderCompare(opts) {
+  var esc = b.template.escapeHtml;
+  var columns = opts.columns || [];
+  var attrRows = opts.rows || [];
+  var prefix = opts.asset_prefix || "/assets/";
+  var notice = _compareNotice(opts.notice);
+
+  if (!columns.length) {
+    var empty =
+      "<section class=\"compare-page\">" +
+        "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+          "<li><a href=\"/\">Shop</a></li>" +
+          "<li aria-current=\"page\">Compare</li>" +
+        "</ol></nav>" +
+        "<h1 class=\"compare-page__title\">Compare products</h1>" +
+        notice +
+        "<p class=\"compare-page__empty\">You haven't added anything to compare yet. Browse the shop and tap " +
+          "<strong>Add to compare</strong> on up to four products to line them up side by side.</p>" +
+        "<p><a class=\"btn-secondary\" href=\"/\">Browse the shop →</a></p>" +
+      "</section>";
+    return _wrap({
+      title:      "Compare products",
+      shop_name:  opts.shop_name || "blamejs.shop",
+      cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+      theme_css:  opts.theme_css,
+      body:       empty,
+    });
+  }
+
+  // Per-column header cell — image + title + remove form. A column whose
+  // product resolved out (archived / deleted) renders the gone-state
+  // header and still offers the remove control so the shopper can clear
+  // the dangling entry.
+  function _headerCell(col) {
+    var removeForm =
+      "<form class=\"compare-col__remove\" method=\"post\" action=\"/compare/toggle\">" +
+        "<input type=\"hidden\" name=\"product_id\" value=\"" + esc(col.product_id) + "\">" +
+        "<input type=\"hidden\" name=\"return_to\" value=\"/compare\">" +
+        "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Remove</button>" +
+      "</form>";
+    if (!col.product) {
+      return "<th scope=\"col\" class=\"compare-col compare-col--gone\">" +
+               "<span class=\"compare-col__title\">No longer available</span>" +
+               removeForm +
+             "</th>";
+    }
+    var slug = esc(col.product.slug);
+    var thumb = col.hero_media
+      ? "<img src=\"" + esc(prefix + col.hero_media.r2_key) + "\" alt=\"" + esc(col.hero_media.alt_text || col.product.title) + "\" loading=\"lazy\">"
+      : "<span class=\"compare-col__mark\" aria-hidden=\"true\">" + esc((col.product.title || "?").trim().charAt(0).toUpperCase() || "?") + "</span>";
+    return "<th scope=\"col\" class=\"compare-col\">" +
+             "<a class=\"compare-col__media\" href=\"/products/" + slug + "\">" + thumb + "</a>" +
+             "<a class=\"compare-col__title\" href=\"/products/" + slug + "\">" + esc(col.product.title) + "</a>" +
+             removeForm +
+           "</th>";
+  }
+
+  var headerCells = "";
+  for (var h = 0; h < columns.length; h += 1) headerCells += _headerCell(columns[h]);
+
+  // Fixed display rows resolved directly (richer than the attribute
+  // matrix): price + availability. Price for a gone column renders "—".
+  function _priceCell(col) {
+    if (!col.product) return "<td class=\"compare-cell compare-cell--gone\">—</td>";
+    return "<td class=\"compare-cell\">" + esc(col.price || "—") + "</td>";
+  }
+  function _availCell(col) {
+    if (!col.product) return "<td class=\"compare-cell compare-cell--gone\">—</td>";
+    return col.available
+      ? "<td class=\"compare-cell\"><span class=\"compare-cell__badge compare-cell__badge--ok\">In stock</span></td>"
+      : "<td class=\"compare-cell\"><span class=\"compare-cell__badge\">Out of stock</span></td>";
+  }
+  var priceRow = "<tr><th scope=\"row\" class=\"compare-row-label\">Price</th>";
+  var availRow = "<tr><th scope=\"row\" class=\"compare-row-label\">Availability</th>";
+  for (var c = 0; c < columns.length; c += 1) {
+    priceRow += _priceCell(columns[c]);
+    availRow += _availCell(columns[c]);
+  }
+  priceRow += "</tr>";
+  availRow += "</tr>";
+
+  // Attribute matrix rows from the primitive. The `price` attribute is
+  // already surfaced as the fixed Price row above, so skip its duplicate
+  // here; every other attribute renders one row, one cell per column.
+  var attrRowsHtml = "";
+  for (var r = 0; r < attrRows.length; r += 1) {
+    var ar = attrRows[r];
+    if (ar.attribute && ar.attribute.slug === "price") continue;
+    var label = (ar.attribute && ar.attribute.label) || "";
+    var fmt = ar.attribute && ar.attribute.format;
+    var cells = "";
+    var vals = ar.values_per_product || [];
+    for (var v = 0; v < columns.length; v += 1) {
+      cells += "<td class=\"compare-cell\">" + _compareCellValue(vals[v], fmt) + "</td>";
+    }
+    attrRowsHtml += "<tr><th scope=\"row\" class=\"compare-row-label\">" + esc(label) + "</th>" + cells + "</tr>";
+  }
+
+  var clearForm =
+    "<form class=\"compare-page__clear\" method=\"post\" action=\"/compare/clear\">" +
+      "<button type=\"submit\" class=\"btn-ghost\">Clear comparison</button>" +
+    "</form>";
+
+  var body =
+    "<section class=\"compare-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/\">Shop</a></li>" +
+        "<li aria-current=\"page\">Compare</li>" +
+      "</ol></nav>" +
+      "<header class=\"compare-page__head\">" +
+        "<h1 class=\"compare-page__title\">Compare products (" + columns.length + ")</h1>" +
+        clearForm +
+      "</header>" +
+      notice +
+      "<div class=\"table-scroll\">" +
+        "<table class=\"compare-table\">" +
+          "<thead><tr><th scope=\"col\" class=\"compare-row-label\"><span class=\"sr-only\">Attribute</span></th>" + headerCells + "</tr></thead>" +
+          "<tbody>" + priceRow + availRow + attrRowsHtml + "</tbody>" +
+        "</table>" +
+      "</div>" +
+    "</section>";
+
+  return _wrap({
+    title:      "Compare products",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Account "Saved for later" page. `opts.items` is a resolved list:
 // { save, product, hero_media } for live products, or { save,
 // product: null } when the variant/product behind a saved row was
@@ -1966,6 +2266,27 @@ function _buildWishlist(productId, count) {
          "</div>";
 }
 
+// Product-level "Add to compare" control. Byte-compatible with the
+// edge renderer (`worker/render/product.js`) so both paths emit
+// identical markup. Action-only label — the toggle route resolves
+// add/remove server-side against the sealed session, and a guest who
+// has never compared anything still sees the same neutral control the
+// edge cache serves. The link to the compare table sits beside the
+// toggle so a shopper mid-basket can jump straight to the side-by-side
+// view.
+function _buildCompare(productId) {
+  var esc = b.template.escapeHtml;
+  return "<div class=\"compare\">" +
+           "<form class=\"compare__form\" method=\"post\" action=\"/compare/toggle\">" +
+             "<input type=\"hidden\" name=\"product_id\" value=\"" + esc(productId) + "\">" +
+             "<button type=\"submit\" class=\"btn-secondary compare__btn\">" +
+               "<span class=\"compare__icon\" aria-hidden=\"true\">⇄</span> Add to compare" +
+             "</button>" +
+           "</form>" +
+           "<a class=\"compare__link card-link\" href=\"/compare\">View compare →</a>" +
+         "</div>";
+}
+
 // Schema.org JSON-LD block. JSON.stringify covers the standard escapes;
 // the `</` → `<\/` rewrite neutralises any literal `</script>` in a
 // value. Mirrors the edge renderer's `jsonLdScript`.
@@ -1999,7 +2320,9 @@ function renderProduct(opts) {
       // theme's `{{{ reviews_html }}}` raw slot. The bundled themes
       // include the slot; a custom theme opts in by adding it.
       reviews_html:   _buildReviews(opts.review_summary, opts.reviews, opts.review_cta),
+      qa_html:        _buildProductQa(opts.qa_questions, opts.qa_cta),
       wishlist_html:  _buildWishlist(opts.product.id, opts.wishlist_count),
+      compare_html:   _buildCompare(opts.product.id),
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
@@ -2009,7 +2332,9 @@ function renderProduct(opts) {
   if (!rows) rows = "<tr><td colspan=\"4\" class=\"empty\">No variants available.</td></tr>";
   var galleryHtml = _buildPdpGallery(opts.product, opts.media || [], opts.asset_prefix || "/assets/");
   var reviewsHtml = _buildReviews(opts.review_summary, opts.reviews, opts.review_cta);
+  var qaHtml = _buildProductQa(opts.qa_questions, opts.qa_cta);
   var wishlistHtml = _buildWishlist(opts.product.id, opts.wishlist_count);
+  var compareHtml = _buildCompare(opts.product.id);
   var body = _render(PRODUCT_PAGE, {
     title:        opts.product.title,
     description:  description,
@@ -2018,7 +2343,9 @@ function renderProduct(opts) {
     .replace("RAW_GALLERY_PLACEHOLDER", galleryHtml)
     .replace("RAW_ROWS_PLACEHOLDER", rows)
     .replace("RAW_WISHLIST_PLACEHOLDER", wishlistHtml)
-    .replace("RAW_REVIEWS_PLACEHOLDER", reviewsHtml);
+    .replace("RAW_COMPARE_PLACEHOLDER", compareHtml)
+    .replace("RAW_REVIEWS_PLACEHOLDER", reviewsHtml)
+    .replace("RAW_QA_PLACEHOLDER", qaHtml);
   // 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.
@@ -3407,6 +3734,27 @@ function mount(router, deps) {
       try { wishlistCount = await deps.wishlist.countForProduct(product.id); }
       catch (_e) { wishlistCount = 0; }
     }
+    // Published Q&A — approved questions + their approved answers. A
+    // failed read (e.g. the product_qa tables not yet migrated) degrades
+    // to the empty state rather than 500-ing the PDP — Q&A is
+    // supplementary to the buy path, like reviews. Mirrors the edge
+    // renderer's missing-table resilience.
+    var qaQuestions, qaCta;
+    if (deps.productQa) {
+      qaQuestions = [];
+      try {
+        var qList = (await deps.productQa.questionsForProduct({ product_id: product.id, limit: 20 })).rows;
+        for (var qi = 0; qi < qList.length; qi += 1) {
+          var qrow = qList[qi];
+          qrow.answers = await deps.productQa.answersForQuestion(qrow.id, { limit: 20 });
+          qaQuestions.push(qrow);
+        }
+      } catch (_e) { qaQuestions = []; }
+      // The form route enforces auth, so the CTA links there
+      // unconditionally; logged-out shoppers get redirected to login.
+      qaCta = "<a class=\"btn-secondary reviews__cta\" href=\"/products/" +
+        b.template.escapeHtml(product.slug) + "/question\">Ask a question</a>";
+    }
     // Log the view for a signed-in customer so it surfaces on their
     // "Recently viewed" account page. Drop-silent — a recording failure
     // (table not migrated, write contention) must never break the PDP
@@ -3428,6 +3776,8 @@ function mount(router, deps) {
       review_summary: reviewSummary,
       reviews:        reviewRows,
       review_cta:     reviewCta,
+      qa_questions:   qaQuestions,
+      qa_cta:         qaCta,
       wishlist_count: wishlistCount,
       shop_name:      shopName,
       cart_count:     cartCount,
@@ -3436,6 +3786,224 @@ function mount(router, deps) {
     _send(res, 200, html);
   });
 
+  // Product compare — the guest-or-customer side-by-side basket. Mounts
+  // when the productCompare primitive is wired. The basket is keyed on
+  // the same `shop_sid` session cookie the cart uses (a routing key that
+  // grants zero authority — the primitive namespace-hashes it before it
+  // touches the database), so a shopper compares without authenticating;
+  // a logged-in shopper's customer_id rides alongside so the operator's
+  // account widget could resume the basket on another device. All three
+  // routes (toggle / clear / view) are writes-or-session-reads, so they
+  // live in the container — the edge forwards them (and any request
+  // carrying shop_sid skips the edge cache, so the view always reflects
+  // the live basket).
+  if (deps.productCompare) {
+    // Resolve the compare basket's session id. Reads the cart session
+    // cookie; when `mint` is true and none exists, allocates one + sets
+    // the cookie so the basket has a stable key across requests. A
+    // read-only path (the view) passes mint=false and returns null when
+    // there's no session — that renders the empty state without minting
+    // a cookie on a bare GET.
+    function _compareSid(req, res, mint) {
+      var sid = _readSidCookie(req);
+      if (sid) return sid;
+      if (!mint) return null;
+      sid = b.uuid.v7();
+      _setSidCookie(res, sid);
+      return sid;
+    }
+
+    function _compareRedirect(res, dest, notice) {
+      var sep = dest.indexOf("?") === -1 ? "?" : "&";
+      var to = notice ? (dest + sep + "notice=" + encodeURIComponent(notice)) : dest;
+      res.status(303);
+      res.setHeader && res.setHeader("location", to);
+      return res.end ? res.end() : res.send("");
+    }
+
+    // POST /compare/toggle — add the product if it isn't in the basket,
+    // remove it if it is. Idempotent (the primitive collapses a repeat
+    // add / a remove of an absent id). Redirects to `return_to` when it's
+    // a safe same-origin path (the compare page's per-column Remove uses
+    // it), otherwise back to the product PDP (the canonical slug is
+    // resolved from product_id, so a forged slug can't drive an open
+    // redirect). No auth required — guests compare too.
+    router.post("/compare/toggle", async function (req, res) {
+      var productId = (req.body || {}).product_id;
+      var sid = _compareSid(req, res, true);
+      var custEnv = _currentCustomerEnv(req);
+      var customerId = custEnv ? custEnv.customer_id : null;
+
+      // Resolve the safe redirect destination up front so a validation
+      // failure still lands the shopper somewhere sane.
+      var rt = (req.body || {}).return_to;
+      var dest = null;
+      if (typeof rt === "string" && /^\/[^/]/.test(rt)) dest = rt;
+
+      var notice;
+      try {
+        var list = await deps.productCompare.getCompareList({ session_id: sid });
+        var inBasket = list.product_ids.indexOf(productId) !== -1;
+        if (inBasket) {
+          await deps.productCompare.removeFromCompare({ session_id: sid, product_id: productId });
+          notice = "removed";
+        } else {
+          await deps.productCompare.addToCompare({ session_id: sid, product_id: productId, customer_id: customerId });
+          notice = "added";
+          // Best-effort impression telemetry — drop-silent, never block
+          // the toggle on the merchandising ledger write.
+          try {
+            await deps.productCompare.recordImpression({ session_id: sid, product_id: productId, source_kind: "product_page" });
+          } catch (_e) { /* drop-silent — impression telemetry is supplementary */ }
+        }
+      } catch (e) {
+        if (e && e.code === "COMPARE_FULL") {
+          // Cap reached — refuse the add with a notice rather than a
+          // crash. The basket is unchanged; the shopper removes one to
+          // make room.
+          if (!dest) {
+            var capProduct = null;
+            try { capProduct = await deps.catalog.products.get(productId); } catch (_e2) { capProduct = null; }
+            dest = capProduct ? ("/products/" + encodeURIComponent(capProduct.slug)) : "/compare";
+          }
+          return _compareRedirect(res, dest, "full");
+        }
+        // A malformed product id (or session id) is a client error.
+        res.status(e instanceof TypeError ? 400 : 500);
+        return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+      }
+
+      if (!dest) {
+        var product = null;
+        try { product = await deps.catalog.products.get(productId); } catch (_e) { product = null; }
+        dest = product ? ("/products/" + encodeURIComponent(product.slug)) : "/compare";
+      }
+      return _compareRedirect(res, dest, notice);
+    });
+
+    // POST /compare/clear — drop the whole basket. Idempotent (clearing
+    // an empty basket is a no-op). Always redirects back to the compare
+    // page so the shopper sees the emptied state.
+    router.post("/compare/clear", async function (req, res) {
+      var sid = _compareSid(req, res, false);
+      if (sid) {
+        try { await deps.productCompare.clearCompareList({ session_id: sid }); }
+        catch (e) {
+          if (!(e instanceof TypeError)) {
+            res.status(500);
+            return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+          }
+          // A malformed session cookie can't address a basket — treat
+          // the clear as a no-op rather than a 400 (the cookie grants
+          // zero authority; a stale/garbage value just means "no basket").
+        }
+      }
+      return _compareRedirect(res, "/compare", "cleared");
+    });
+
+    // GET /compare — the side-by-side comparison table for the session's
+    // basket. Empty basket → the friendly empty state. Each product id is
+    // resolved through the catalog; a product archived / deleted between
+    // the add and this render resolves out gracefully (the column renders
+    // "no longer available" with a remove control). The attribute matrix
+    // comes from the primitive's compareTable, fed a getProduct adapter
+    // enriched with the product's first variant + current price so the
+    // baked-in price/sku/weight attributes resolve against this catalog's
+    // schema.
+    router.get("/compare", async function (req, res) {
+      var sid = _compareSid(req, res, false);
+      var cartCount = await _cartCountForReq(req);
+      // Read the post-toggle notice key from the query string the same
+      // way the search route reads `?q=` — via the parsed URL, not
+      // `req.query` (which the router only populates when a route
+      // declares a query validator). renderCompare gates the key
+      // against a fixed allowlist, so a forged value renders nothing.
+      var compareUrl = req.url ? new URL(req.url, "http://localhost") : null;
+      var noticeKey = compareUrl ? compareUrl.searchParams.get("notice") : null;
+
+      if (!sid) {
+        return _send(res, 200, renderCompare({
+          columns: [], rows: [], shop_name: shopName, cart_count: cartCount,
+          asset_prefix: _cardAssetPrefix, notice: noticeKey,
+        }));
+      }
+
+      // Per-request product cache so the header-column decoration and the
+      // attribute-matrix adapter don't double-fetch the same product.
+      var enrichedCache = Object.create(null);
+      async function _enrich(pid) {
+        if (Object.prototype.hasOwnProperty.call(enrichedCache, pid)) return enrichedCache[pid];
+        var result = { product: null, variant: null, price: null, hero_media: null, available: false };
+        var product = null;
+        // get() throws a TypeError on a malformed id; a basket can only
+        // hold strict-UUID ids (the primitive sanitises on add), but stay
+        // defensive — a bad id resolves to the gone-state column.
+        try { product = await deps.catalog.products.get(pid); } catch (_e) { product = null; }
+        if (product && product.status === "active") {
+          result.product = product;
+          var variants = await deps.catalog.variants.listForProduct(pid);
+          if (variants.length) {
+            result.variant = variants[0];
+            var pr = await deps.catalog.prices.current(variants[0].id, "USD");
+            if (pr) result.price = pricing.format(pr.amount_minor, pr.currency);
+            // Availability — best-effort inventory read on the first
+            // variant. A product with no inventory row reads as available
+            // (operators who don't track stock still sell), an explicit
+            // zero-on-hand reads as out of stock.
+            try {
+              var inv = await deps.catalog.inventory.get(variants[0].sku);
+              result.available = !inv || (Number(inv.stock_on_hand) - Number(inv.stock_held)) > 0;
+            } catch (_e) { result.available = true; }
+          } else {
+            result.available = false;
+          }
+          var media = await deps.catalog.media.listForProduct(pid);
+          result.hero_media = media.length ? media[0] : null;
+        }
+        enrichedCache[pid] = result;
+        return result;
+      }
+
+      var list = await deps.productCompare.getCompareList({ session_id: sid });
+      var columns = [];
+      for (var i = 0; i < list.product_ids.length; i += 1) {
+        var pid = list.product_ids[i];
+        var e = await _enrich(pid);
+        columns.push({
+          product_id: pid,
+          product:    e.product,
+          hero_media: e.hero_media,
+          price:      e.price,
+          available:  e.available,
+        });
+      }
+
+      // Attribute matrix from the primitive. compareTable walks the
+      // basket's product ids through the `catalog` adapter wired into the
+      // primitive at create time (server.js) — that adapter enriches each
+      // product with a `variants` array (price as `price_minor`, `weight`
+      // from `weight_grams`) so the baked-in variant-sourced attributes
+      // resolve against this catalog's column shape. compareTable refuses
+      // (throws) when no catalog adapter was wired; a resolution failure
+      // degrades to no attribute rows — the fixed Price/Availability rows
+      // still render the side-by-side view.
+      var attrRows = [];
+      try {
+        var table = await deps.productCompare.compareTable({ session_id: sid });
+        attrRows = table.rows || [];
+      } catch (_e) { attrRows = []; }
+
+      _send(res, 200, renderCompare({
+        columns:      columns,
+        rows:         attrRows,
+        shop_name:    shopName,
+        cart_count:   cartCount,
+        asset_prefix: _cardAssetPrefix,
+        notice:       noticeKey,
+      }));
+    });
+  }
+
   // Collections — operator-curated + smart product lists. Public browse
   // pages; mounted when the collections primitive is wired.
   if (deps.collections) {
@@ -5475,6 +6043,77 @@ function mount(router, deps) {
         ));
       });
     }
+
+    // Product Q&A — asking a question requires a logged-in customer (no
+    // verified-purchase gate; any signed-in shopper can ask). The
+    // question lands `pending` and surfaces on the PDP once an operator
+    // approves it. Customer-authored answers aren't accepted from the
+    // storefront — answering is an operator action in the admin console
+    // (the lib models customer answers, but exposing a public answer
+    // form invites an unmoderated reply surface we don't ship in v1;
+    // operators post the authoritative answer). Only mounts when the
+    // productQa primitive is wired.
+    if (deps.productQa) {
+      async function _qaGateContext(req, res) {
+        var slug = req.params && req.params.slug;
+        var product = slug ? await deps.catalog.products.bySlug(slug) : null;
+        if (!product) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        var cartCount = await _cartCountForReq(req);
+        return { product: product, auth: auth, cartCount: cartCount };
+      }
+
+      router.get("/products/:slug/question", async function (req, res) {
+        var ctx = await _qaGateContext(req, res);
+        if (!ctx) return;
+        _send(res, 200, renderQuestionForm({
+          product:    { title: ctx.product.title, slug: ctx.product.slug },
+          shop_name:  shopName,
+          cart_count: ctx.cartCount,
+        }));
+      });
+
+      router.post("/products/:slug/question", async function (req, res) {
+        var ctx = await _qaGateContext(req, res);
+        if (!ctx) return;
+        var body = req.body || {};
+        try {
+          await deps.productQa.submitQuestion({
+            product_id:  ctx.product.id,
+            customer_id: ctx.auth.customer_id,
+            body:        body.body,
+          });
+        } catch (e) {
+          // Shape rejections bounce back to the form with the reason;
+          // anything else is a real 500.
+          if (e instanceof TypeError) {
+            return _send(res, 400, renderQuestionForm({
+              product:    { title: ctx.product.title, slug: ctx.product.slug },
+              notice:     (e && e.message) || "Please check your question and try again.",
+              shop_name:  shopName,
+              cart_count: ctx.cartCount,
+            }));
+          }
+          throw e;
+        }
+        _send(res, 200, _qaMessagePage(
+          { shop_name: shopName, cart_count: ctx.cartCount },
+          "Thanks for your question",
+          "Your question has been submitted and is pending moderation. It will appear on the product page once an operator approves and answers it.",
+          { href: "/products/" + ctx.product.slug, label: "Back to product" },
+        ));
+      });
+    }
   }
 
   // POST /cart/lines — add a line. Reads variant_id + qty from the