@blamejs/blamejs-shop 0.0.121 → 0.0.122

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.122 (2026-05-24) — **Product reviews on the storefront — verified-buyer submission, operator moderation, and rich-snippet ratings.** The product page now shows customer reviews: an average rating, a per-star distribution, and the published review list, with `AggregateRating` structured data so star ratings can surface in search results. Submission is gated to signed-in customers who have actually purchased the product — the route confirms a completed order for that product before accepting a review, and re-checks on submit. Reviews land in a pending state; operators publish or reject them through new bearer-token admin endpoints. Display and structured data are identical whether the page is served at the edge or from the container. **Added:** *Reviews on the product page* — The PDP renders an average rating, a per-star distribution bar chart, and the published reviews (newest first, verified-buyer badge, date). Products with no reviews show an invite to be the first. Rendered server-side on both the edge and container paths. · *Verified-buyer review submission* — `GET /products/:slug/review` shows the review form to a signed-in customer who has purchased the product; everyone else is redirected to sign in or told only verified buyers can review. `POST /products/:slug/review` re-checks the purchase before accepting the review, so a direct POST can't bypass the gate. Submitted reviews start pending. · *Operator review moderation* — `GET /admin/reviews?status=pending` lists the moderation queue across all products; `GET /admin/reviews/:id` reads one; `POST /admin/reviews/:id/publish` and `POST /admin/reviews/:id/reject` move it. Bearer-token-gated like the rest of the admin API. Pending and rejected reviews never appear on the storefront. · *`AggregateRating` structured data* — The product page emits Schema.org `AggregateRating` (rating value + review count) nested in the existing `Product` JSON-LD when published reviews exist, so eligible products can show star ratings in search results. Omitted entirely at zero reviews to stay valid. The container render path now emits the full `Product` + `AggregateOffer` + `BreadcrumbList` JSON-LD that the edge already did. · *`order.hasPurchasedProduct(customerId, productId)`* — Existence check — true when the customer has an order line for any variant of the product in an order that reached `paid` or later (excludes `pending` and `cancelled`). Backs the review purchase gate. · *`reviews.listByStatus(status, opts)`* — Lists reviews across all products by status, newest first, with the same opaque tuple cursor as `listForProduct`. Backs the admin moderation queue.
+
 - v0.0.121 (2026-05-24) — **Codebase-patterns detector blocks SHA3 primitives in `worker/` — prevents the regression that broke newsletter signup.** v0.0.120 fixed the newsletter signup by routing the POST to the container instead of computing `b.crypto.namespaceHash` (SHA3-512) at the edge — Workers' `nodejs_compat` doesn't expose SHA3-family digests. New `worker-uses-sha3-primitive` codebase-patterns detector flags any `b.crypto.{sha3Hash, hmacSha3, namespaceHash, shake256, shake512, hkdfSha3}(...)` call under `worker/` so the next operator can't re-introduce the substrate-mismatch bug. Catalog grows 121 → 122. Detector targets the exact SHA3-family primitive names rather than a general regex match — Worker code that legitimately uses `b.crypto.toBase64Url`, `b.crypto.timingSafeEqual`, `b.crypto.generateBytes`, `b.crypto.hmacSha256` (the Stripe webhook augment), etc. is unaffected. **Added:** *`worker-uses-sha3-primitive` detector* — Flags `b.crypto.sha3Hash(...)`, `hmacSha3(...)`, `namespaceHash(...)`, `shake256(...)`, `shake512(...)`, and `hkdfSha3(...)` in any file under `worker/`. Catches the substrate-mismatch class that broke v0.0.92's edge newsletter handler (live for 28 versions before being routed back to the container in v0.0.120). When edge code needs a stable hash: route to the container OR use `b.crypto.hmacSha256` IFF both sides read with the same SHA-256 path. Never have one substrate write SHA3 and another read SHA-256 — silent divergence breaks cross-substrate lookups (e.g. unsubscribe-by-email_hash).
 
 - v0.0.120 (2026-05-24) — **Route POST /newsletter through the container — Workers `nodejs_compat` can't compute SHA3-512 (`b.crypto.namespaceHash`).** The v0.0.92 edge-served newsletter handler was 500-ing every submission with `Error: Digest method not supported`. Root cause surfaced via the temporary `X-Newsletter-Diag` header (added in v0.0.119): Cloudflare Workers' `nodejs_compat` runtime exposes `node:crypto` but the supported digest set is a subset of full Node — `createHash("sha3-512")` isn't in it. Working around with a Web-Crypto-API SHA-256 fallback would silently diverge the Worker's `email_hash` values from the container's SHA3-512 values, breaking the unsubscribe lookup (different hash → different row → silent unsubscribe failure). The edge handler was the wrong substrate for this primitive. The POST falls through to `_forwardToContainer` so the framework's SHA3-512 path runs server-side and the `email_hash` column stays consistent across reads. The ~200ms container hop on signup submit is paid back by a working unsubscribe flow. The dead `_edgeNewsletter` function + its `renderNewsletterThanks` / `renderNewsletterError` imports + the diagnostic `X-Newsletter-Diag` header are all removed in the same patch. **Fixed:** *Newsletter signup now uses the framework's SHA3-512 hash via the container* — Removed: `_edgeNewsletter` handler (123 lines), `renderNewsletterThanks` / `renderNewsletterError` imports in `worker/index.js`, the `X-Newsletter-Diag` diagnostic response header (its job is done). The dispatch comment above the now-removed `if (pathname === "/newsletter" && ...)` block documents the substrate decision + the SHA3-512 / Workers-runtime constraint so the next operator doesn't re-introduce the edge handler.

package/README.md

@@ -63,9 +63,10 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/email.js`** | Transactional templates — order receipt, ship notification, refund confirmation. Strict `{{var}}` renderer with HTML escape + refusal of unknown / unused placeholders. Composed on `b.mail` (DKIM/SPF/DMARC/BIMI upstream). |
 | **`lib/storefront.js`** | Server-rendered HTML — utility bar + sticky header + dark hero with code-preview card + primitives marquee + featured-product callout + collections grid + framework feature band + designed catalog grid + newsletter band + four-column footer. Designed surfaces also for PDP, cart, checkout, pay, order, account login / register / dashboard, search results, `/admin` API landing, 404. Image-bearing cards on the home + search grids pull from `catalog.media`. The default theme stylesheet is external (R2-served `themes/default/assets/css/main.css`) and CSP-compliant — operators override by uploading a replacement at the same key, by passing `opts.theme_css` to renderers, or by registering a named theme through the `theme` primitive. |
 | **`lib/customers.js`** | Customer accounts — passkey-only (WebAuthn). Email is stored hash-only (`b.crypto.namespaceHash` namespace `customer-email`); the raw address never lands in D1. Passkey credentials carry CBOR-encoded public keys, transport hints, and SHA3-512-fingerprinted attestation. Account routes (`/account/login`, `/account/register`, `/account`) ship as designed cards on the storefront. |
+| **`lib/reviews.js`** | Operator-moderated product ratings. Submission requires a signed-in customer **and** a verified purchase — `/products/:slug/review` confirms a completed order for the product (via `order.hasPurchasedProduct`) before accepting, re-checked on POST; reviews land `pending`. Author identity is hash-only (`b.crypto.namespaceHash`); the raw email is never stored. The PDP renders the average, per-star distribution, and published reviews with `AggregateRating` JSON-LD. `/admin/reviews` is the moderation queue (`listByStatus` → publish / reject). |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 
@@ -80,6 +81,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0008_inventory_thresholds.sql` — low-stock alert thresholds + alerts
 - `migrations-d1/0009_subscriptions.sql` — subscription_plans + subscriptions (Stripe-mirrored)
 - `migrations-d1/0010_newsletter_signups.sql` — email signups with hash-based dedup
+- `migrations-d1/0011_reviews.sql` — operator-moderated product reviews (hash-only author identity)
 
 ### Demo seed
 

package/SECURITY.md

@@ -139,3 +139,12 @@ node -e "
   framework's at-rest key material. Operators MUST rotate the
   passphrase via `b.vault.rotate` after any container image rebuild
   that changed a vendored crypto dependency.
+- **Reviews are purchase-gated and operator-moderated.** A review can
+  only be submitted by a signed-in customer who has a completed order
+  for that product; the route confirms the purchase before accepting
+  and re-checks it on the POST, so a direct request can't plant a
+  review for a product the account never bought. Submissions land in a
+  `pending` state and never reach the storefront until an operator
+  publishes them through `/admin/reviews`. The author identity is
+  stored hash-only (`b.crypto.namespaceHash`) — the raw email is never
+  persisted.

package/lib/admin.js

@@ -162,6 +162,7 @@ function mount(router, deps) {
   var r2            = deps.r2_bridge     || null;   // media-upload endpoint disabled when absent
   var assetPrefix   = typeof deps.asset_prefix === "string" ? deps.asset_prefix : "/assets/";
   var catalogImport = deps.catalogImport || null;   // bulk-import route disabled when absent
+  var reviews       = deps.reviews       || null;   // moderation endpoints disabled when absent
 
   try { _b().audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -529,6 +530,56 @@ function mount(router, deps) {
     }));
   }
 
+  // ---- reviews (moderation) -------------------------------------------
+
+  // Operator-side review moderation. The queue lists reviews across all
+  // products in one status (defaults to `pending`); publish / reject
+  // drive the same transitions the storefront submit path leaves in
+  // `pending`. Endpoints are omitted entirely when no reviews primitive
+  // is wired.
+  if (reviews) {
+    router.get("/admin/reviews", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var status = (url && url.searchParams.get("status")) || "pending";
+      var cursor = url && url.searchParams.get("cursor");
+      var limitS = url && url.searchParams.get("limit");
+      var limit  = limitS == null ? undefined : parseInt(limitS, 10);
+      var page = await reviews.listByStatus(status, { cursor: cursor || undefined, limit: limit });
+      _json(res, 200, page);
+    }));
+
+    router.get("/admin/reviews/:id", R(async function (req, res) {
+      var rev = await reviews.get(req.params.id);
+      if (!rev) return _problem(res, 404, "review-not-found");
+      _json(res, 200, rev);
+    }));
+
+    router.post("/admin/reviews/:id/publish", W("review.publish", async function (req, res) {
+      var rev;
+      try {
+        rev = await reviews.publish(req.params.id);
+      } catch (e) {
+        if (e && e.code === "REVIEW_NOT_FOUND") return _problem(res, 404, "review-not-found");
+        throw e;
+      }
+      _json(res, 200, rev);
+      return rev;
+    }));
+
+    router.post("/admin/reviews/:id/reject", W("review.reject", async function (req, res) {
+      var body = req.body || {};
+      var rev;
+      try {
+        rev = await reviews.reject(req.params.id, body.reason);
+      } catch (e) {
+        if (e && e.code === "REVIEW_NOT_FOUND") return _problem(res, 404, "review-not-found");
+        throw e;
+      }
+      _json(res, 200, rev);
+      return rev;
+    }));
+  }
+
   // ---- config ---------------------------------------------------------
 
   var config = deps.config || null;

package/lib/order.js

@@ -368,6 +368,29 @@ function create(opts) {
       if (r.rowCount === 0) return null;
       return await this.get(orderId);
     },
+
+    // Has this customer purchased this product? True iff an order
+    // line for any variant of the product sits in an order owned by
+    // the customer whose status is a real purchase — anything except
+    // pending (never captured) or cancelled (reversed before
+    // fulfillment). paid|fulfilling|shipped|delivered|refunded all
+    // count as purchased. The review gate composes this so only
+    // verified buyers can leave a review. Existence check, one round
+    // trip.
+    hasPurchasedProduct: async function (customerId, productId) {
+      _uuid(customerId, "customer id");
+      _uuid(productId, "product id");
+      var rows = (await query(
+        "SELECT 1 FROM order_lines ol " +
+        "JOIN orders o   ON o.id = ol.order_id " +
+        "JOIN variants v ON v.id = ol.variant_id " +
+        "WHERE o.customer_id = ?1 AND v.product_id = ?2 " +
+        "AND o.status NOT IN ('pending','cancelled') " +
+        "LIMIT 1",
+        [customerId, productId],
+      )).rows;
+      return rows.length > 0;
+    },
   };
 }
 

package/lib/reviews.js

@@ -349,6 +349,35 @@ function create(opts) {
       return { rows: r.rows, next_cursor: _encodeNext(r.rows, REVIEW_ORDER_KEY, limit) };
     },
 
+    // Cross-product moderation listing — every review in one status
+    // regardless of product. The moderation queue needs all `pending`
+    // rows globally, which listForProduct (per-product) can't serve.
+    // status is required here (the queue is always status-scoped). Same
+    // (created_at DESC, id DESC) tuple cursor as listForProduct.
+    listByStatus: async function (status, listOpts) {
+      status = _statusFilter(status);
+      if (status === undefined) {
+        throw new TypeError("reviews.listByStatus: status is required (one of " + ALLOWED_STATUSES.join(", ") + ")");
+      }
+      listOpts = listOpts || {};
+      var limit  = _limit(listOpts.limit);
+      var cursorVals = _decodeCursor(listOpts.cursor, REVIEW_ORDER_KEY, "listByStatus");
+
+      var sql, params;
+      if (cursorVals) {
+        sql = "SELECT * FROM reviews WHERE status = ?1 " +
+              "AND (created_at < ?2 OR (created_at = ?2 AND id < ?3)) " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?4";
+        params = [status, cursorVals[0], cursorVals[1], limit];
+      } else {
+        sql = "SELECT * FROM reviews WHERE status = ?1 " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?2";
+        params = [status, limit];
+      }
+      var r = await query(sql, params);
+      return { rows: r.rows, next_cursor: _encodeNext(r.rows, REVIEW_ORDER_KEY, limit) };
+    },
+
     // Aggregate ratings — published-only by construction; counts
     // every star bucket so the storefront can draw the distribution
     // bar chart without a second query.

package/lib/storefront.js

@@ -678,6 +678,7 @@ var PRODUCT_PAGE =
   "      </div>\n" +
   "    </div>\n" +
   "  </div>\n" +
+  "  RAW_REVIEWS_PLACEHOLDER\n" +
   "</section>\n";
 
 // PDP gallery markup — composed once per render call from the
@@ -720,6 +721,193 @@ function _buildPdpGallery(product, media, assetPrefix) {
   return heroImg + "<ul class=\"pdp__thumbs\" aria-hidden=\"true\">" + thumbs.join("") + "</ul>";
 }
 
+// Accessible star glyph row — the precise figure rides in a visually-
+// hidden label so a screen reader announces "4.3 out of 5 stars" while
+// sighted users see the rounded glyph fill. Mirrors the edge renderer
+// (`worker/render/product.js`) so both paths emit identical markup.
+function _reviewStars(value, label) {
+  var esc = _b().template.escapeHtml;
+  var filled = Math.round(value);
+  if (filled < 0) filled = 0;
+  if (filled > 5) filled = 5;
+  var glyphs = "";
+  for (var i = 1; i <= 5; i += 1) {
+    glyphs += "<span class=\"star" + (i <= filled ? " star--on" : "") + "\">" +
+      (i <= filled ? "★" : "☆") + "</span>";
+  }
+  return "<span class=\"stars\" aria-hidden=\"true\">" + glyphs + "</span>" +
+         "<span class=\"sr-only\">" + esc(label) + "</span>";
+}
+
+function _reviewDate(ts) {
+  var n = Number(ts);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  return new Date(n).toISOString().slice(0, 10);
+}
+
+// Builds the PDP reviews block from the published aggregate + list.
+// Renders the "no reviews yet" empty state when the product has none;
+// `ctaHtml` is the operator/customer call-to-action (a "Write a review"
+// link, or "Sign in to review", resolved by the route). Mirrors the
+// edge renderer byte-for-byte so the two render paths stay in sync.
+function _buildReviews(summary, reviews, ctaHtml) {
+  var esc = _b().template.escapeHtml;
+  summary = summary || { count: 0, avg_rating: 0, distribution: { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 } };
+  reviews = reviews || [];
+  var count = Number(summary.count) || 0;
+
+  var head;
+  if (count > 0) {
+    var avg = Number(summary.avg_rating) || 0;
+    var avgStr = avg.toFixed(1);
+    var dist = summary.distribution || {};
+    var bars = "";
+    for (var s = 5; s >= 1; s -= 1) {
+      var n   = Number(dist[s]) || 0;
+      var pct = count > 0 ? Math.round((n / count) * 100) : 0;
+      bars +=
+        "<li class=\"rating-bar\">" +
+          "<span class=\"rating-bar__label\">" + s + " star</span>" +
+          "<span class=\"rating-bar__track\"><span class=\"rating-bar__fill\" style=\"width:" + pct + "%\"></span></span>" +
+          "<span class=\"rating-bar__count\">" + n + "</span>" +
+        "</li>";
+    }
+    head =
+      "<div class=\"reviews__summary\">" +
+        "<div class=\"reviews__average\">" +
+          "<span class=\"reviews__average-num\">" + esc(avgStr) + "</span>" +
+          _reviewStars(avg, avgStr + " out of 5 stars") +
+          "<span class=\"reviews__count\">" + count + (count === 1 ? " review" : " reviews") + "</span>" +
+        "</div>" +
+        "<ul class=\"reviews__distribution\">" + bars + "</ul>" +
+      "</div>";
+  } else {
+    head = "<p class=\"reviews__empty\">No reviews yet. Be the first to review this product.</p>";
+  }
+
+  var list = "";
+  for (var i = 0; i < reviews.length; i += 1) {
+    var r = reviews[i];
+    var rating = Number(r.rating) || 0;
+    var verified = Number(r.verified_purchase) === 1
+      ? "<span class=\"review__verified\">Verified buyer</span>"
+      : "";
+    var date = _reviewDate(r.created_at);
+    var bodyHtml = r.body
+      ? "<p class=\"review__body\">" + esc(String(r.body)) + "</p>"
+      : "";
+    list +=
+      "<li class=\"review\">" +
+        "<div class=\"review__head\">" +
+          _reviewStars(rating, rating + " out of 5 stars") +
+          "<h3 class=\"review__title\">" + esc(String(r.title || "")) + "</h3>" +
+        "</div>" +
+        "<div class=\"review__meta\">" + verified +
+          (date ? "<time class=\"review__date\" datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+        "</div>" +
+        bodyHtml +
+      "</li>";
+  }
+  var listHtml = list ? "<ul class=\"reviews__list\">" + list + "</ul>" : "";
+
+  return "<section class=\"reviews\" aria-labelledby=\"reviews-title\">" +
+           "<h2 id=\"reviews-title\" class=\"reviews__heading\">Customer reviews</h2>" +
+           head +
+           listHtml +
+           (ctaHtml || "") +
+         "</section>";
+}
+
+var REVIEW_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\">Write a review</li>\n" +
+  "    </ol>\n" +
+  "  </nav>\n" +
+  "  <h1 class=\"review-form-page__title\">Review {{title}}</h1>\n" +
+  "  RAW_NOTICE_PLACEHOLDER\n" +
+  "  <form class=\"review-form\" method=\"post\" action=\"/products/{{slug}}/review\">\n" +
+  "    <fieldset class=\"review-form__rating\">\n" +
+  "      <legend>Your rating</legend>\n" +
+  "      RAW_STARS_PLACEHOLDER\n" +
+  "    </fieldset>\n" +
+  "    <label class=\"form-field\">\n" +
+  "      <span class=\"form-field__label\">Title</span>\n" +
+  "      <input type=\"text\" name=\"title\" maxlength=\"120\" required autocomplete=\"off\">\n" +
+  "    </label>\n" +
+  "    <label class=\"form-field\">\n" +
+  "      <span class=\"form-field__label\">Your review</span>\n" +
+  "      <textarea name=\"body\" maxlength=\"4000\" rows=\"6\"></textarea>\n" +
+  "    </label>\n" +
+  "    <button type=\"submit\" class=\"btn-primary\">Submit review</button>\n" +
+  "  </form>\n" +
+  "</section>\n";
+
+// Auth-gated review 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 renderReviewForm(opts) {
+  var esc = _b().template.escapeHtml;
+  var slug = opts.product.slug;
+  var stars = "";
+  for (var rv = 5; rv >= 1; rv -= 1) {
+    stars +=
+      "<label class=\"star-radio\">" +
+        "<input type=\"radio\" name=\"rating\" value=\"" + rv + "\" required>" +
+        "<span>" + rv + (rv === 1 ? " star" : " stars") + "</span>" +
+      "</label>";
+  }
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body = _render(REVIEW_FORM_PAGE, {
+    title: opts.product.title,
+    slug:  slug,
+  })
+    .replace("RAW_NOTICE_PLACEHOLDER", notice)
+    .replace("RAW_STARS_PLACEHOLDER", stars);
+  return _wrap({
+    title:      "Review " + 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 review flow (purchase-gate
+// refusal, submission thank-you). `cta` is an optional { href, label }.
+function _reviewMessagePage(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,
+  });
+}
+
+// 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`.
+function _jsonLdScript(data) {
+  var serialised = JSON.stringify(data).replace(/<\/(?=script>)/gi, "<\\/");
+  return "<script type=\"application/ld+json\">" + serialised + "</script>";
+}
+
 function renderProduct(opts) {
   if (!opts || !opts.product) throw new TypeError("storefront.renderProduct: opts.product required");
   var variants = opts.variants || [];
@@ -741,6 +929,10 @@ function renderProduct(opts) {
       product:        { title: opts.product.title, description: description },
       variants:       rendered,
       has_variants:   rendered.length > 0,
+      // Pre-rendered reviews block (internally HTML-escaped) for the
+      // 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),
       asset_css_main: opts.theme.assetUrl("css/main.css"),
     });
   }
@@ -749,18 +941,73 @@ function renderProduct(opts) {
   }).join("");
   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 body = _render(PRODUCT_PAGE, {
     title:        opts.product.title,
     description:  description,
     variant_rows: "RAW_ROWS_PLACEHOLDER",
   })
     .replace("RAW_GALLERY_PLACEHOLDER", galleryHtml)
-    .replace("RAW_ROWS_PLACEHOLDER", rows);
+    .replace("RAW_ROWS_PLACEHOLDER", rows)
+    .replace("RAW_REVIEWS_PLACEHOLDER", reviewsHtml);
   // 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.
   var heroMedia = (opts.media && opts.media[0]) || null;
   var ogImage   = heroMedia ? ((opts.asset_prefix || "/assets/") + heroMedia.r2_key) : "/assets/brand/logo.png";
+
+  // Product + AggregateOffer JSON-LD, with AggregateRating folded in
+  // when published reviews exist. Kept byte-compatible with the edge
+  // renderer so the structured data is identical whichever substrate
+  // serves the PDP. AggregateRating is omitted (not null) at zero
+  // reviews — Google rejects `reviewCount: 0`.
+  var priceList = variants
+    .map(function (v) { return prices[v.id] ? prices[v.id].amount_minor : null; })
+    .filter(function (n) { return Number.isInteger(n); });
+  var jsonLd = null;
+  if (priceList.length > 0) {
+    var lowMinor = Math.min.apply(null, priceList);
+    var hiMinor  = Math.max.apply(null, priceList);
+    var currency = (prices[variants[0].id] && prices[variants[0].id].currency) || "USD";
+    var divisor  = currency === "JPY" || currency === "KRW" ? 1 : 100;
+    var aggregateRating;
+    if (opts.review_summary && Number(opts.review_summary.count) > 0) {
+      aggregateRating = {
+        "@type":       "AggregateRating",
+        "ratingValue": (Number(opts.review_summary.avg_rating) || 0).toFixed(1),
+        "reviewCount": Number(opts.review_summary.count),
+        "bestRating":  5,
+        "worstRating": 1,
+      };
+    }
+    jsonLd = _jsonLdScript({
+      "@context":        "https://schema.org",
+      "@type":           "Product",
+      "name":            opts.product.title,
+      "description":     description || ("Browse " + opts.product.title + " on " + shopName + "."),
+      "image":           heroMedia ? [ogImage] : undefined,
+      "sku":             variants[0] && variants[0].sku,
+      "aggregateRating": aggregateRating,
+      "offers":          {
+        "@type":         "AggregateOffer",
+        "priceCurrency": currency,
+        "lowPrice":      (lowMinor / divisor).toFixed(divisor === 1 ? 0 : 2),
+        "highPrice":     (hiMinor  / divisor).toFixed(divisor === 1 ? 0 : 2),
+        "offerCount":    variants.length,
+        "availability":  "https://schema.org/InStock",
+      },
+    });
+  }
+  var breadcrumbJsonLd = _jsonLdScript({
+    "@context":        "https://schema.org",
+    "@type":           "BreadcrumbList",
+    "itemListElement": [
+      { "@type": "ListItem", "position": 1, "name": "Shop", "item": "/" },
+      { "@type": "ListItem", "position": 2, "name": opts.product.title, "item": "/products/" + opts.product.slug },
+    ],
+  });
+  jsonLd = (jsonLd || "") + breadcrumbJsonLd;
+
   return _wrap({
     title:          opts.product.title,
     shop_name:      shopName,
@@ -770,7 +1017,7 @@ function renderProduct(opts) {
     og_title:       opts.product.title + " — " + shopName,
     og_description: description || ("Browse " + opts.product.title + " on " + shopName + "."),
     og_image:       ogImage,
-    body:           body,
+    body:           body + jsonLd,
   });
 }
 
@@ -1797,14 +2044,34 @@ function mount(router, deps) {
         cartCount = lines.length;
       }
     }
+    // Published reviews aggregate + list. A failed read (e.g. the
+    // reviews table not yet migrated) degrades to the empty state
+    // rather than 500-ing the whole PDP — reviews are supplementary
+    // to the buy path. Mirrors the edge renderer's missing-table
+    // resilience.
+    var reviewSummary, reviewRows, reviewCta;
+    if (deps.reviews) {
+      try {
+        reviewSummary = await deps.reviews.summaryForProduct(product.id);
+        reviewRows    = (await deps.reviews.listForProduct(product.id, { limit: 10 })).rows;
+      } catch (_e) { reviewSummary = undefined; reviewRows = []; }
+      // The form route enforces auth + the verified-purchase gate, so
+      // the CTA links there unconditionally; logged-out shoppers get
+      // redirected to login, non-purchasers get a clear "not eligible".
+      reviewCta = "<a class=\"btn-secondary reviews__cta\" href=\"/products/" +
+        _b().template.escapeHtml(product.slug) + "/review\">Write a review</a>";
+    }
     var html = renderProduct({
-      product:    product,
-      variants:   variants,
-      prices:     prices,
-      media:      media,
-      shop_name:  shopName,
-      cart_count: cartCount,
-      theme:      theme,
+      product:        product,
+      variants:       variants,
+      prices:         prices,
+      media:          media,
+      review_summary: reviewSummary,
+      reviews:        reviewRows,
+      review_cta:     reviewCta,
+      shop_name:      shopName,
+      cart_count:     cartCount,
+      theme:          theme,
     });
     _send(res, 200, html);
   });
@@ -2339,6 +2606,89 @@ function mount(router, deps) {
       res.status(303); res.setHeader && res.setHeader("location", "/");
       return res.end ? res.end() : res.send("");
     });
+
+    // Product reviews — submission requires a logged-in customer AND a
+    // verified purchase of the product (the gate, not just a badge).
+    // Only mounts when both the reviews primitive and an order handle
+    // (for the purchase check) are wired.
+    if (deps.reviews && deps.order) {
+      async function _reviewGateContext(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);
+        var purchased = await deps.order.hasPurchasedProduct(auth.customer_id, product.id);
+        return { product: product, auth: auth, cartCount: cartCount, purchased: purchased };
+      }
+
+      function _reviewIneligible(res, ctx, code) {
+        return _send(res, code, _reviewMessagePage(
+          { shop_name: shopName, cart_count: ctx.cartCount },
+          "Only verified buyers can review",
+          "We can only accept a review for a product you've purchased. Make sure you're signed in with the account you ordered with.",
+          { href: "/products/" + ctx.product.slug, label: "Back to product" },
+        ));
+      }
+
+      router.get("/products/:slug/review", async function (req, res) {
+        var ctx = await _reviewGateContext(req, res);
+        if (!ctx) return;
+        if (!ctx.purchased) return _reviewIneligible(res, ctx, 200);
+        _send(res, 200, renderReviewForm({
+          product:    { title: ctx.product.title, slug: ctx.product.slug },
+          shop_name:  shopName,
+          cart_count: ctx.cartCount,
+        }));
+      });
+
+      router.post("/products/:slug/review", async function (req, res) {
+        var ctx = await _reviewGateContext(req, res);
+        if (!ctx) return;
+        // Re-check the gate on write — a client can POST directly
+        // without ever fetching the form.
+        if (!ctx.purchased) return _reviewIneligible(res, ctx, 403);
+        var body = req.body || {};
+        try {
+          await deps.reviews.submit({
+            product_id:        ctx.product.id,
+            customer_id:       ctx.auth.customer_id,
+            rating:            parseInt(body.rating, 10),
+            title:             body.title,
+            body:              body.body,
+            verified_purchase: 1,
+          });
+        } 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, renderReviewForm({
+              product:    { title: ctx.product.title, slug: ctx.product.slug },
+              notice:     (e && e.message) || "Please check your review and try again.",
+              shop_name:  shopName,
+              cart_count: ctx.cartCount,
+            }));
+          }
+          throw e;
+        }
+        _send(res, 200, _reviewMessagePage(
+          { shop_name: shopName, cart_count: ctx.cartCount },
+          "Thanks for your review",
+          "Your review has been submitted and is pending moderation. It will appear on the product page once an operator approves it.",
+          { href: "/products/" + ctx.product.slug, label: "Back to product" },
+        ));
+      });
+    }
   }
 
   // POST /cart/lines — add a line. Reads variant_id + qty from the

package/lib/vendor/MANIFEST.json

@@ -3,8 +3,8 @@
   "_about": "blamejs.shop vendors a single framework — blamejs — which itself bundles every server-side crypto/identity dependency. The transitive packages blamejs ships are surfaced in its own MANIFEST.json at lib/vendor/blamejs/lib/vendor/MANIFEST.json — Trivy / Grype rely on that nested data for CVE attribution.",
   "packages": {
     "blamejs": {
-      "version": "0.12.21",
-      "tag": "v0.12.21",
+      "version": "0.12.28",
+      "tag": "v0.12.28",
       "license": "Apache-2.0",
       "author": "blamejs contributors",
       "source": "https://github.com/blamejs/blamejs",