@blamejs/blamejs-shop 0.3.31 → 0.3.33

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.33 (2026-05-31) — **Create and manage customer segments from the admin console.** Customer segments could be shown on a customer's profile but there was no way to define or manage them, so the feature could not actually be used. A new Segments screen in the admin console creates rule-based segments from recency, frequency, lifetime-order, spend, average-order-value, and refund-rate criteria, edits their rules, archives and restores them, and recomputes membership on demand — showing how many customers each segment now contains. Segment membership stays rule-derived: it is recalculated from order history, not assigned by hand. **Added:** *Customer segments administration* — A Segments screen in the admin console manages rule-based customer segments. Each segment is defined by RFM-style criteria — how recently and how often a customer orders, their lifetime order count and spend, average order value, and refund rate — and a list shows every segment with its rules, current member count, and status, filterable by active or archived. You can create and edit segments, archive and restore them, and recompute membership on demand, which re-evaluates the rules against order history and reports how many customers match. Membership is always derived from the rules, never assigned per customer.
+
+- v0.3.32 (2026-05-31) — **Collection pages now page through every product instead of stopping at 24.** A collection page showed only its first 24 products and provided no way to reach the rest, so any product past the 24th in a collection was silently unreachable. Collection pages now have previous/next pagination, matching the search results, so a collection of any size can be browsed in full. A shared link to a specific page keeps its position, while the page's canonical URL stays the plain collection address. **Fixed:** *Collection pages paginate* — A collection with more than 24 products was truncated at the first 24 with no way to see the others. Collection pages now carry previous/next pagination — the same control used on search results — so every product in a collection is reachable. The canonical URL remains the bare collection address on every page (so search engines see one collection page, not duplicates), while a shared link to a deeper page preserves its position.
+
 - v0.3.31 (2026-05-31) — **A public help center, authored from the admin console.** The knowledge-base backend was built but had no pages, so there was no way to publish help content or for a shopper to read it. There is now a Help center at /help: a browsable index of published articles grouped by category, and an article page that renders the article, shows a breadcrumb trail in search results, and lets a reader mark whether it was helpful. Operators get a Help center screen in the admin console to write articles, save them as drafts, publish them, and archive them. Article text is written in a small Markdown subset and is fully escaped on the page, and only published, non-archived articles are publicly reachable. **Added:** *Help center for shoppers* — A new /help section lists published articles by category and renders each article at /help/:slug with a breadcrumb (carried into search results as BreadcrumbList structured data) and a "Was this helpful?" control. Article bodies are written in a Markdown subset and escaped on output, and a draft, archived, or unknown article returns a clean 404 — only published articles are ever publicly reachable. · *Help center authoring in the admin console* — A Help center screen lets operators write articles (slug, title, category, body), keep them as drafts, publish or unpublish them, and archive ones that should no longer appear. The list filters by all/published/drafts and shows each article's view count and helpfulness tally, so the team can see what readers are using and which articles need work.
 
 - v0.3.30 (2026-05-31) — **An unrecognized automatic-discount type is now rejected instead of silently becoming free shipping.** When defining or editing an automatic discount over the API, an unrecognized discount type was silently turned into a free-shipping rule — the most generous kind — and accepted without any error. A discount sent over the API with a type outside the supported set (percent off, amount off the total, amount off each item, buy-X-get-Y, or free shipping) is now rejected with a clear error, so a typo can no longer create a store-wide free-shipping rule by accident. The admin form was never affected, because its type selector only offers the supported values. **Fixed:** *Automatic-discount type is validated* — Defining or editing an automatic discount with a discount type outside the supported set now returns a clear error instead of quietly defaulting to free shipping. Previously an unrecognized type sent over the JSON API was coerced into a free-shipping rule and saved with no warning, which could apply free shipping store-wide from a single typo. Free shipping remains a valid, explicitly chosen type; only unrecognized values are rejected. The admin console form was unaffected, since its selector is limited to the supported types.

package/lib/admin.js

@@ -516,7 +516,7 @@ function mount(router, deps) {
   // `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 = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -7113,6 +7113,305 @@ function mount(router, deps) {
     }
   }
 
+  // ---- customer segments ----------------------------------------------
+  //
+  // Operator-defined RFM-style groupings ("VIPs", "lapsed-90d",
+  // "high-refund-rate") used to target campaigns. A segment is a slug +
+  // title + a bag of rule predicates ANDed together; membership is
+  // RULE-DERIVED — the recompute action re-evaluates the rules against the
+  // live order history and rewrites the membership cache. This console
+  // manages the segment DEFINITIONS + triggers a recompute; it never
+  // hand-assigns individual customers (the customer-detail screen shows
+  // the segments a customer sits in, read-only). The structured create /
+  // edit form covers the numeric RFM predicates (recency / frequency /
+  // monetary / AOV / refund-rate); the list-valued predicates
+  // (last_order_status_in / country_in / currency_in) and any future rule
+  // keys pass through the bearer JSON surface untouched. Every rule is
+  // validated by composing defineSegment / update — the form translator
+  // never persists a rules_json blob straight from the body, so a bad /
+  // missing rule throws a TypeError the routes map to a clean 400.
+  if (customerSegments) {
+    // Translate the structured create form (or a bearer JSON body) into a
+    // defineSegment input. A body already carrying an object-shaped `rules`
+    // is a bearer client passing the full vocabulary — forward untouched so
+    // the primitive's validator owns it. Otherwise build `rules` from the
+    // numeric RFM fields the console exposes; an empty field is omitted (a
+    // segment needs at least one predicate, which defineSegment enforces).
+    function _segmentInput(body) {
+      if (body.rules && typeof body.rules === "object") {
+        return body; // full JSON shape from a bearer client
+      }
+      return {
+        slug:        typeof body.slug === "string" ? body.slug.trim() : body.slug,
+        title:       body.title,
+        description: body.description,
+        rules:       _segmentRules(body),
+      };
+    }
+
+    // Translate the edit form (or a bearer JSON patch) into an update patch.
+    // Title / description forward when present; the rules are re-collected
+    // from the same numeric RFM fields the create form uses, but only when
+    // the form declared it via the hidden `rules_present` marker — so a
+    // title-only edit doesn't wipe the rule set. A bearer client posting an
+    // object-shaped `rules` forwards it verbatim for the primitive to validate.
+    function _segmentPatch(body) {
+      var patch = {};
+      if (Object.prototype.hasOwnProperty.call(body, "title") && body.title !== "") patch.title = body.title;
+      if (Object.prototype.hasOwnProperty.call(body, "description")) patch.description = body.description;
+      if (body.rules && typeof body.rules === "object") {
+        patch.rules = body.rules;
+      } else if (body.rules_present === "1") {
+        patch.rules = _segmentRules(body);
+      }
+      return patch;
+    }
+
+    // Build the `rules` object from the structured form's numeric RFM
+    // fields. Each field is optional; a blank field is left out. The values
+    // pass into defineSegment / update verbatim, which validate every key
+    // (non-negative integers, bps caps, min ≤ max coherence) and throw a
+    // TypeError on a bad / empty rule set — surfaced as a clean 400. This
+    // translator never writes the rule itself; it only shapes the typed
+    // bag the primitive's validator owns.
+    function _segmentRules(body) {
+      var rules = {};
+      var NUMERIC = [
+        "recency_days_max", "recency_days_min",
+        "frequency_orders_min", "lifetime_orders_min", "lifetime_orders_max",
+        "monetary_minor_min", "monetary_minor_max", "aov_minor_min",
+        "refund_rate_bps_max", "refund_rate_bps_min",
+      ];
+      for (var i = 0; i < NUMERIC.length; i += 1) {
+        var k = NUMERIC[i];
+        if (body[k] != null && body[k] !== "") {
+          rules[k] = _strictMinorInt(body[k], "customerSegments", k);
+        }
+      }
+      return rules;
+    }
+
+    // One-line human summary of a segment's rules for the list/detail.
+    function _segmentSummary(seg) {
+      var rules = (seg && seg.rules) || {};
+      var keys = Object.keys(rules);
+      if (!keys.length) return "—";
+      return keys.map(function (k) {
+        var v = rules[k];
+        return k + " " + (Array.isArray(v) ? v.join("/") : String(v));
+      }).join(" · ");
+    }
+
+    async function _renderSegments(flags) {
+      flags = flags || {};
+      var url = flags.url || null;
+      var filter = url && url.searchParams.get("filter");
+      var includeArchived = filter === "all" || filter === "archived";
+      var all = await customerSegments.listSegments({ include_archived: includeArchived });
+      var segments = all;
+      if (filter === "archived") {
+        segments = all.filter(function (s) { return s.archived_at != null; });
+      } else if (filter !== "all") {
+        // default = active only (listSegments already excluded archived).
+        segments = all;
+      }
+      return renderAdminSegments(Object.assign({
+        shop_name: deps.shop_name, nav_available: navAvailable,
+        segments: segments, filter: filter || "active", summarize: _segmentSummary,
+      }, flags));
+    }
+
+    // List — every segment with its rule summary, member count, and archived
+    // state; an All/Active/Archived filter; a clean empty state. Content-
+    // negotiated: bearer → the JSON array; browser cookie → the rendered table.
+    router.get("/admin/segments", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var includeArchived = url && (url.searchParams.get("filter") === "all" || url.searchParams.get("filter") === "archived");
+        var segments = await customerSegments.listSegments({ include_archived: !!includeArchived });
+        _json(res, 200, { segments: segments });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, await _renderSegments({
+          url:        url,
+          created:    url && url.searchParams.get("created"),
+          updated:    url && url.searchParams.get("updated"),
+          archived:   url && url.searchParams.get("archived"),
+          unarchived: url && url.searchParams.get("unarchived"),
+          recomputed: url && url.searchParams.get("recomputed"),
+          notice:     (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        }));
+      },
+    ));
+
+    // New-segment form — its own GET so the create page survives a bad
+    // submit's err redirect with the operator's context intact.
+    router.get("/admin/segments/new", _pageOrApi(true,
+      R(async function (_req, res) {
+        // Bearer clients don't need a form; hand back the rule vocabulary so
+        // tooling knows what a valid create body accepts.
+        _json(res, 200, {
+          known_rule_keys:        customerSegments.KNOWN_RULE_KEYS,
+          allowed_order_statuses: customerSegments.ALLOWED_ORDER_STATUSES,
+        });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminSegmentNew({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          notice: (url && url.searchParams.get("err")) ? "Check the segment's slug and rules — at least one rule is required." : null,
+        }));
+      },
+    ));
+
+    // Create — composes defineSegment, which validates the slug + rules and
+    // throws a TypeError (→ 400) on a bad / missing rule. The bearer path
+    // returns 201 + the created segment; the browser path PRGs to the list.
+    router.post("/admin/segments", _pageOrApi(false,
+      W("customer_segment.create", async function (req, res) {
+        var seg = await customerSegments.defineSegment(_segmentInput(req.body || {}));
+        _json(res, 201, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try {
+          await customerSegments.defineSegment(_segmentInput(req.body || {}));
+        } catch (e) {
+          // A bad / missing rule (TypeError) or a duplicate slug
+          // (CUSTOMER_SEGMENT_SLUG_EXISTS) is operator input — bounce back to
+          // the create form's err state, never a 500. _safeNotice records an
+          // unknown failure server-side and yields a 5xx only for a genuine
+          // fault.
+          var n = _safeNotice(e, "customer_segment.create");
+          if (n.status >= 500) throw e;
+          return _redirect(res, "/admin/segments/new?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.create", outcome: "success" });
+        _redirect(res, "/admin/segments?created=1");
+      },
+    ));
+
+    // Resolve a :slug to its segment. A malformed slug throws inside
+    // listSegments' slug guard chain — but here we read via listSegments and
+    // match, so an unknown slug simply yields null → a clean 404.
+    async function _segmentBySlug(slug) {
+      // stats() is the cheapest single-segment read that also throws a
+      // TypeError on a malformed slug; pair it with the full hydrate via the
+      // list so the detail screen has the rules + archived state.
+      var all = await customerSegments.listSegments({ include_archived: true });
+      for (var i = 0; i < all.length; i += 1) {
+        if (all[i].slug === slug) return all[i];
+      }
+      return null;
+    }
+
+    // Detail — the single segment + its current member count + stats, and a
+    // full edit form (title / description / rules). Content-negotiated.
+    router.get("/admin/segments/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var seg = await _segmentBySlug(req.params.slug);
+        if (!seg) return _problem(res, 404, "customer-segment-not-found");
+        var stats = await customerSegments.stats(seg.slug);
+        _json(res, 200, Object.assign({}, seg, { stats: stats }));
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var seg = await _segmentBySlug(req.params.slug);
+        if (!seg) return _sendHtml(res, 404, await _renderSegments({ url: url, notice: "Segment not found." }));
+        var stats = null;
+        try { stats = await customerSegments.stats(seg.slug); }
+        catch (_e) { stats = null; }
+        _sendHtml(res, 200, renderAdminSegment({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          segment: seg, stats: stats, summary: _segmentSummary(seg),
+          updated:    url && url.searchParams.get("updated"),
+          recomputed: url && url.searchParams.get("recomputed"),
+          recomputed_count: url && url.searchParams.get("members"),
+          notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the segment." : null,
+        }));
+      },
+    ));
+
+    // Edit — composes update, which re-validates the rules and throws on a
+    // bad set. A terms edit returns to the detail screen on error so the
+    // operator sees their input in context.
+    router.post("/admin/segments/:slug/edit", _pageOrApi(false,
+      W("customer_segment.update", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.update(req.params.slug, _segmentPatch(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        try { await customerSegments.update(slug, _segmentPatch(req.body || {})); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments/" + enc + "?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.update", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/segments/" + enc + "?updated=1");
+      },
+    ));
+
+    // Recompute — re-evaluate this segment's rules against the live order
+    // history and rewrite its membership cache. Surfaces the resulting member
+    // count in the PRG banner (this is the action that populates a freshly
+    // defined or edited segment).
+    router.post("/admin/segments/:slug/recompute", _pageOrApi(false,
+      W("customer_segment.recompute", async function (req, res) {
+        var report;
+        try { report = await customerSegments.recompute({ slugs: [req.params.slug] }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        var count = report.per_segment[req.params.slug];
+        _json(res, 200, { slug: req.params.slug, member_count: count == null ? 0 : count, report: report });
+        return { id: req.params.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        var report;
+        try { report = await customerSegments.recompute({ slugs: [slug] }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments/" + enc + "?err=1"); }
+        var count = report.per_segment[slug];
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.recompute", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/segments/" + enc + "?recomputed=1&members=" + encodeURIComponent(String(count == null ? 0 : count)));
+      },
+    ));
+
+    router.post("/admin/segments/:slug/archive", _pageOrApi(false,
+      W("customer_segment.archive", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.archive(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try { await customerSegments.archive(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.archive", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/segments?archived=1");
+      },
+    ));
+
+    router.post("/admin/segments/:slug/unarchive", _pageOrApi(false,
+      W("customer_segment.unarchive", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.unarchive(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try { await customerSegments.unarchive(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.unarchive", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/segments?unarchived=1");
+      },
+    ));
+  }
+
   // ---- quantity discounts ---------------------------------------------
   // Tier-set CRUD for automatic per-line quantity breaks ("buy 5, save
   // 10%"). The pricing engine already applies these at PDP / cart /
@@ -8347,6 +8646,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
   { key: "customers",    href: "/admin/customers",    label: "Customers",    requires: "customers" },
+  { key: "segments",     href: "/admin/segments",     label: "Segments",     requires: "customerSegments" },
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "support",      href: "/admin/support",      label: "Support",      requires: "supportTickets" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
@@ -11036,6 +11336,192 @@ function renderAdminDiscounts(opts) {
   return _renderAdminShell(opts.shop_name, "Discounts", body, "discounts", opts.nav_available);
 }
 
+// The numeric RFM rule fields the structured segment form collects. Each
+// maps 1:1 to a customer-segments rule key; a blank field is omitted from
+// the rules object, and the backend validates whatever's present (rejecting
+// an empty rule set, a bad integer, or an out-of-range basis-point value).
+var SEGMENT_RULE_FIELDS = [
+  { name: "frequency_orders_min", label: "Min lifetime orders (frequency)", hint: "Customer has placed at least this many paid orders.", extra: " min=\"0\"" },
+  { name: "lifetime_orders_max",  label: "Max lifetime orders",             hint: "At most this many orders — gate \"new\" buyers.", extra: " min=\"0\"" },
+  { name: "recency_days_max",     label: "Ordered within N days (recency)", hint: "Last order ≤ N days ago — recent buyers.", extra: " min=\"0\"" },
+  { name: "recency_days_min",     label: "Lapsed for N+ days",              hint: "Last order ≥ N days ago — the lapsed half of RFM.", extra: " min=\"0\"" },
+  { name: "monetary_minor_min",   label: "Min lifetime spend (minor)",      hint: "Lifetime gross ≥ N in the smallest currency unit.", extra: " min=\"0\"" },
+  { name: "monetary_minor_max",   label: "Max lifetime spend (minor)",      hint: "Lifetime gross ≤ N.", extra: " min=\"0\"" },
+  { name: "aov_minor_min",        label: "Min average order value (minor)", hint: "Average order value ≥ N.", extra: " min=\"0\"" },
+  { name: "refund_rate_bps_max",  label: "Max refund rate (bps)",           hint: "Refunds ÷ orders ≤ N basis points (10000 = 100%).", extra: " min=\"0\" max=\"10000\"" },
+  { name: "refund_rate_bps_min",  label: "Min refund rate (bps)",           hint: "Refunds ÷ orders ≥ N basis points — catch high-refund customers.", extra: " min=\"0\" max=\"10000\"" },
+];
+
+// Status pill for a segment's lifecycle: active = green (paid), archived =
+// neutral-off (cancelled). Reuses the shared order-pill classes.
+function _segmentPill(seg) {
+  var archived = seg && seg.archived_at != null;
+  return "<span class=\"status-pill " + (archived ? "cancelled" : "paid") + "\">" +
+    (archived ? "archived" : "active") + "</span>";
+}
+
+// Render the numeric RFM rule field set, each prefilled from the supplied
+// rules object (empty when creating). The list-valued predicates
+// (last_order_status_in / country_in / currency_in) and any future rule key
+// stay on the bearer JSON surface — documented in the form's help text.
+function _segmentRuleFields(rules) {
+  rules = rules || {};
+  return SEGMENT_RULE_FIELDS.map(function (f) {
+    var v = rules[f.name] != null ? String(rules[f.name]) : "";
+    return _setupField(f.label, f.name, v, "number", f.hint, f.extra);
+  }).join("");
+}
+
+function renderAdminSegments(opts) {
+  opts = opts || {};
+  var segments = opts.segments || [];
+  var summarize = typeof opts.summarize === "function" ? opts.summarize : function () { return "—"; };
+  var filter = opts.filter || "active";
+  var created    = opts.created    ? "<div class=\"banner banner--ok\">Segment created.</div>" : "";
+  var updated    = opts.updated    ? "<div class=\"banner banner--ok\">Segment updated.</div>" : "";
+  var archived   = opts.archived   ? "<div class=\"banner banner--ok\">Segment archived.</div>" : "";
+  var unarchived = opts.unarchived ? "<div class=\"banner banner--ok\">Segment unarchived.</div>" : "";
+  var recomputed = opts.recomputed ? "<div class=\"banner banner--ok\">Membership recomputed.</div>" : "";
+  var notice     = opts.notice     ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var FILTERS = [
+    { value: "active",   label: "Active" },
+    { value: "all",      label: "All" },
+    { value: "archived", label: "Archived" },
+  ];
+  var chips = "<div class=\"order-filters\">" + FILTERS.map(function (fl) {
+    var href = fl.value === "active" ? "/admin/segments" : "/admin/segments?filter=" + fl.value;
+    return "<a class=\"chip" + (filter === fl.value ? " chip--on" : "") + "\" href=\"" + href + "\">" + _htmlEscape(fl.label) + "</a>";
+  }).join("") + "</div>";
+
+  var rows = segments.map(function (s) {
+    var enc = encodeURIComponent(s.slug);
+    var isArchived = s.archived_at != null;
+    var actions =
+      "<a class=\"btn btn--ghost\" href=\"/admin/segments/" + _htmlEscape(enc) + "\">Manage</a> " +
+      (isArchived
+        ? "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost\" type=\"submit\">Unarchive</button></form>"
+        : "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/recompute\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost\" type=\"submit\">Recompute</button></form> " +
+          "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>");
+    return "<tr>" +
+      "<td><a href=\"/admin/segments/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(s.title) + "</strong></a><br><code class=\"order-id\">" + _htmlEscape(s.slug) + "</code></td>" +
+      "<td>" + _htmlEscape(summarize(s)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(s.last_member_count == null ? 0 : s.last_member_count)) + "</td>" +
+      "<td>" + _segmentPill(s) + "</td>" +
+      "<td><div class=\"actions-row\">" + actions + "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = segments.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Segment</th><th scope=\"col\">Rules</th><th scope=\"col\" class=\"num\">Members</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No " + (filter === "archived" ? "archived " : (filter === "all" ? "" : "active ")) + "segments yet. Define one to start grouping customers for campaigns.</p>";
+
+  var body = "<section><h2>Customer segments</h2>" + created + updated + archived + unarchived + recomputed + notice +
+    "<p class=\"meta\">Rule-derived groupings for targeted campaigns. Membership is recomputed from order history — define a segment, then recompute to populate it.</p>" +
+    chips + table +
+    "<div class=\"actions-row mt\"><a class=\"btn\" href=\"/admin/segments/new\">Define a segment</a></div>" +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Segments", body, "segments", opts.nav_available);
+}
+
+function renderAdminSegmentNew(opts) {
+  opts = opts || {};
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var form =
+    "<div class=\"panel mw-42\">" +
+      "<h3 class=\"subhead\">Define a segment</h3>" +
+      "<p class=\"meta\">Fill at least one rule — every rule must hold for a customer to land in the segment. Leave a rule blank to skip it. Members are populated by a recompute after the segment is saved.</p>" +
+      "<form method=\"post\" action=\"/admin/segments\">" +
+        _setupField("Slug", "slug", "", "text", "Stable handle, e.g. vip-buyers.", " maxlength=\"64\" required") +
+        _setupField("Title", "title", "", "text", "Operator-facing name, e.g. VIP buyers.", " maxlength=\"200\" required") +
+        _setupField("Description (optional)", "description", "", "text", "What this segment is for.", " maxlength=\"1000\"") +
+        "<h3 class=\"subhead subhead--sp-lg\">Rules (all must hold)</h3>" +
+        _segmentRuleFields({}) +
+        "<p class=\"meta\">List-valued rules (last order status / country / currency) are available through the JSON API.</p>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create segment</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/segments\">Cancel</a></div>" +
+      "</form>" +
+    "</div>";
+  var body = "<section><h2>Define a segment</h2>" + notice + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "New segment", body, "segments", opts.nav_available);
+}
+
+function renderAdminSegment(opts) {
+  opts = opts || {};
+  var s = opts.segment;
+  if (!s) {
+    var nf = "<section><h2>Segment</h2><p class=\"empty\">Segment not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/segments\">Back to segments</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Segment", nf, "segments", opts.nav_available);
+  }
+  var stats = opts.stats || null;
+  var updated    = opts.updated    ? "<div class=\"banner banner--ok\">Segment updated.</div>" : "";
+  var recomputed = opts.recomputed
+    ? "<div class=\"banner banner--ok\">Membership recomputed — " + _htmlEscape(String(opts.recomputed_count == null ? 0 : opts.recomputed_count)) + " member(s).</div>"
+    : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var isArchived = s.archived_at != null;
+  var enc = encodeURIComponent(s.slug);
+
+  var memberCount = stats && stats.member_count != null ? stats.member_count : (s.last_member_count == null ? 0 : s.last_member_count);
+  var lastRecomputed = stats && stats.last_recomputed_at != null ? _fmtDate(stats.last_recomputed_at)
+                     : (s.last_recomputed_at != null ? _fmtDate(s.last_recomputed_at) : "never");
+
+  var statCards =
+    "<div class=\"stat-grid\">" +
+      _statCard("Members", String(memberCount)) +
+      _statCard("Avg lifetime (minor)", stats && stats.avg_lifetime_minor != null ? String(stats.avg_lifetime_minor) : "0") +
+      _statCard("Last recomputed", lastRecomputed) +
+    "</div>";
+
+  var head = "<div class=\"panel\"><dl class=\"detail-grid\">" +
+    "<div><dt>Segment</dt><dd><strong>" + _htmlEscape(s.title) + "</strong><br><code class=\"order-id\">" + _htmlEscape(s.slug) + "</code></dd></div>" +
+    "<div><dt>Rules</dt><dd>" + _htmlEscape(opts.summary || "—") + "</dd></div>" +
+    (s.description ? "<div><dt>Description</dt><dd>" + _htmlEscape(s.description) + "</dd></div>" : "") +
+    "<div><dt>Status</dt><dd>" + _segmentPill(s) + "</dd></div>" +
+  "</dl></div>";
+
+  // Recompute is the action that makes the rules actually populate the
+  // membership cache — surface it prominently for an active segment.
+  var recomputeForm = isArchived ? "" :
+    "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/recompute\" class=\"form-inline\">" +
+      "<button class=\"btn\" type=\"submit\">Recompute membership</button>" +
+    "</form>";
+
+  var editForm = isArchived
+    ? "<p class=\"empty\">This segment is archived. Unarchive it to edit or recompute.</p>" +
+        "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+          "<button class=\"btn\" type=\"submit\">Unarchive</button></form>"
+    : "<div class=\"panel mt mw-42\">" +
+        "<h3 class=\"subhead\">Edit segment</h3>" +
+        "<p class=\"meta\">Change the title, description, or rules. Editing the rules takes effect on the next recompute.</p>" +
+        "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/edit\">" +
+          "<input type=\"hidden\" name=\"rules_present\" value=\"1\">" +
+          _setupField("Title", "title", s.title, "text", "Operator-facing name.", " maxlength=\"200\"") +
+          _setupField("Description", "description", s.description || "", "text", "What this segment is for.", " maxlength=\"1000\"") +
+          "<h3 class=\"subhead subhead--sp-lg\">Rules (all must hold)</h3>" +
+          _segmentRuleFields(s.rules) +
+          "<p class=\"meta\">Leaving every rule blank is rejected — a segment needs at least one rule. List-valued rules stay on the JSON API.</p>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save changes</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveForm = isArchived ? "" :
+    "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+      "<button class=\"btn btn--danger\" type=\"submit\">Archive segment</button></form>";
+
+  var body = "<section><h2>" + _htmlEscape(s.title) + "</h2>" + updated + recomputed + notice +
+    head + statCards +
+    "<div class=\"actions-row mt\">" + recomputeForm + archiveForm + "</div>" +
+    editForm +
+    "<div class=\"actions-row mt\"><a class=\"btn btn--ghost\" href=\"/admin/segments\">Back to segments</a></div>" +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Segment " + s.slug, body, "segments", opts.nav_available);
+}
+
 function renderAdminGiftCards(opts) {
   opts = opts || {};
   var rows = opts.cards || [];

package/lib/asset-manifest.json

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

package/lib/collections.js

@@ -753,21 +753,29 @@ function create(opts) {
           throw new TypeError("collections.productsIn: cursor — " + (e && e.message || "malformed"));
         }
       }
+      // Fetch one row beyond the page so the next cursor is emitted ONLY
+      // when a member past this page actually exists. Keying the cursor off
+      // a full page alone (rows.length === limit) advertises a phantom next
+      // page when the collection size is an exact multiple of the limit —
+      // following it lands on an empty page. The smart path peeks the same
+      // way (startIdx + slice.length < matched.length).
       var sql, params;
       if (cursorVals) {
         sql = "SELECT * FROM collection_members WHERE collection_slug = ?1 AND " +
               "(position > ?2 OR (position = ?2 AND id > ?3)) " +
               "ORDER BY position ASC, id ASC LIMIT ?4";
-        params = [input.slug, cursorVals[0], cursorVals[1], limit];
+        params = [input.slug, cursorVals[0], cursorVals[1], limit + 1];
       } else {
         sql = "SELECT * FROM collection_members WHERE collection_slug = ?1 " +
               "ORDER BY position ASC, id ASC LIMIT ?2";
-        params = [input.slug, limit];
+        params = [input.slug, limit + 1];
       }
       var r = await query(sql, params);
-      var lastM = r.rows[r.rows.length - 1];
+      var hasMore = r.rows.length > limit;
+      var pageRows = hasMore ? r.rows.slice(0, limit) : r.rows;
+      var lastM = pageRows[pageRows.length - 1];
       var nextM = null;
-      if (lastM && r.rows.length === limit) {
+      if (lastM && hasMore) {
         nextM = b.pagination.encodeCursor({
           orderKey: MEMBER_ORDER_KEY,
           vals:     [lastM.position, lastM.id],
@@ -777,7 +785,7 @@ function create(opts) {
       return {
         type: "manual",
         sort_strategy: row.sort_strategy,
-        rows: r.rows.map(function (mr) {
+        rows: pageRows.map(function (mr) {
           return {
             id:                mr.id,
             collection_slug:   mr.collection_slug,

package/lib/storefront.js

@@ -1466,6 +1466,84 @@ function _renderSearchPagination(q, filters, total, page, pageSize) {
     "</nav>\n";
 }
 
+// The fixed collection page size — the number of product cards one page of
+// `/collections/:slug` shows. Pages past the first are reached via the
+// `?cursor=` trail the pagination nav emits. A collection is keyset/offset
+// paginated by its lib (`collections.productsIn` returns an opaque,
+// forward-only `next_cursor`); it exposes no total, so the page UI is a
+// prev/next pair (not the numbered `/search` UI), reusing the same
+// `search-pagination` shell + `rel="prev"/"next"` so no new CSS ships.
+var COLLECTION_PAGE_SIZE = 24;
+
+// Cursor characters are RFC 4648 base64url plus a single `.` tag separator —
+// no `,`, `+`, `/`, or `=` — so a comma joins a list of page-start cursors
+// into one URL-safe `?cursor=` value. This is the page trail: page 1 carries
+// no `cursor`; each Next appends the page's `next_cursor`; each Previous
+// drops the last entry. The current page starts at the trail's last cursor.
+var COLLECTION_CURSOR_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+// Parse the `?cursor=` trail off a parsed URL into an array of opaque
+// page-start cursors. A missing param is page 1 (empty trail). Each
+// comma-separated entry must match the base64url`.`base64url cursor shape;
+// any entry that doesn't is dropped, and a trail longer than a sane bound is
+// truncated — a defensive request-shape reader that returns a clean trail
+// (never throws) so a tampered / stale `?cursor=` degrades to a reachable
+// page rather than a 500. The route additionally retries page 1 if the
+// lib rejects the resolved start cursor's HMAC.
+var COLLECTION_MAX_TRAIL = 512;
+function _parseCollectionCursorTrail(url) {
+  if (!url || !url.searchParams) return [];
+  var raw = url.searchParams.get("cursor");
+  if (raw == null || raw === "") return [];
+  if (raw.length > COLLECTION_MAX_TRAIL * 200) return [];
+  var parts = raw.split(",");
+  var out = [];
+  for (var i = 0; i < parts.length && out.length < COLLECTION_MAX_TRAIL; i += 1) {
+    if (COLLECTION_CURSOR_RE.test(parts[i])) out.push(parts[i]);
+  }
+  return out;
+}
+
+// `/collections/:slug` URL for a given cursor trail. An empty trail is the
+// bare collection page (page 1) so the first page has one canonical URL;
+// otherwise the trail joins into the `?cursor=` param. Mirrors the search
+// renderer's `_searchPageUrl` (page 1 omits the param).
+function _collectionPageUrl(slug, trail) {
+  var base = "/collections/" + encodeURIComponent(slug);
+  if (!trail || !trail.length) return base;
+  return base + "?cursor=" + trail.join(",");
+}
+
+// Prev/next pagination for a collection product grid. Reuses the
+// `search-pagination` shell + `rel="prev"/"next"` + disabled-state spans
+// so no new CSS ships and the markup matches the search nav. Renders
+// nothing when there is neither a previous page (empty trail) nor a next
+// page (`nextCursor == null`) — i.e. a single-page collection stays
+// byte-identical to the unpaginated render. `trail` is the current page's
+// cursor trail (the last entry is this page's start); `nextCursor` is the
+// lib's opaque forward cursor for the following page (null on the last
+// page).
+function _renderCollectionPagination(slug, trail, nextCursor) {
+  var esc = b.template.escapeHtml;
+  var hasPrev = trail && trail.length > 0;
+  var hasNext = nextCursor != null && nextCursor !== "";
+  if (!hasPrev && !hasNext) return "";
+  var prevTrail = hasPrev ? trail.slice(0, trail.length - 1) : [];
+  var nextTrail = (trail || []).concat([nextCursor]);
+  var prev = hasPrev
+    ? _render("<a class=\"search-pagination__link search-pagination__prev\" href=\"{{href}}\" rel=\"prev\">Previous</a>\n",
+        { href: esc(_collectionPageUrl(slug, prevTrail)) })
+    : "<span class=\"search-pagination__link search-pagination__prev is-disabled\" aria-disabled=\"true\">Previous</span>\n";
+  var next = hasNext
+    ? _render("<a class=\"search-pagination__link search-pagination__next\" href=\"{{href}}\" rel=\"next\">Next</a>\n",
+        { href: esc(_collectionPageUrl(slug, nextTrail)) })
+    : "<span class=\"search-pagination__link search-pagination__next is-disabled\" aria-disabled=\"true\">Next</span>\n";
+  return "<nav class=\"search-pagination collection-pagination\" aria-label=\"Collection pages\">\n" +
+    prev +
+    next +
+    "</nav>\n";
+}
+
 // Read the 1-based `?page=N` results page off a parsed URL. A missing,
 // non-integer, or sub-1 value reads as page 1 (the canonical first page);
 // the upper bound is clamped against the real page count by `_clampPage`
@@ -2884,6 +2962,16 @@ function renderCollection(opts) {
   var grid = cards
     ? "<div class=\"catalog-grid collection-grid\">" + cards + "</div>"
     : "<p class=\"collection-empty\">No products in this collection yet.</p>";
+  // Prev/next nav under the grid — the `?cursor=` trail carries the lib's
+  // opaque forward cursor so a collection larger than one page is fully
+  // reachable (the silent 24-cap truncation is the bug this closes). Renders
+  // nothing for a single-page collection (no trail + no next cursor), so the
+  // small-collection render is unchanged.
+  var pagination = _renderCollectionPagination(
+    col.slug,
+    opts.cursor_trail || [],
+    opts.next_cursor == null ? null : opts.next_cursor
+  );
   var body =
     "<section class=\"collection-page\">" +
       "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
@@ -2896,6 +2984,7 @@ function renderCollection(opts) {
         (col.description ? "<p class=\"collection-page__desc\">" + esc(col.description) + "</p>" : "") +
       "</header>" +
       grid +
+      pagination +
     "</section>";
   // BreadcrumbList JSON-LD mirroring the on-page `<nav class="breadcrumb">`
   // trail (Shop → Collections → this collection). Google's result panel
@@ -8902,18 +8991,49 @@ function mount(router, deps) {
 
     router.get("/collections/:slug", async function (req, res) {
       var slug = req.params && req.params.slug;
-      // get() and productsIn() both throw on a malformed slug (the
-      // primitive validates shape). A bad path segment is a 404, not a
-      // 500 — the route is a defensive request-shape reader.
-      var col, result;
+      // get() throws a TypeError on a malformed slug (the primitive
+      // validates shape). A bad path segment / unknown / archived
+      // collection is a 404, not a 500 — the route is a defensive
+      // request-shape reader.
+      var col;
       try {
         col = slug ? await deps.collections.get(slug) : null;
         if (!col || col.archived_at != null) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
-        result = await deps.collections.productsIn({ slug: slug, limit: 24 });
       } catch (e) {
         if (e instanceof TypeError) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
         throw e;
       }
+
+      // `?cursor=` trail — the comma-joined list of page-start cursors. The
+      // current page starts at the trail's last cursor (page 1 = empty
+      // trail). Parsed defensively (garbage entries dropped); the lib still
+      // HMAC-verifies the resolved start cursor, so a tampered-but-well-
+      // shaped cursor is caught below and falls back to page 1 rather than
+      // 500/404 — matching how `/search` treats a bad `?page=`.
+      var url   = req.url ? new URL(req.url, "http://localhost") : null;
+      var trail = _parseCollectionCursorTrail(url);
+      var startCursor = trail.length ? trail[trail.length - 1] : null;
+
+      var result;
+      try {
+        result = await deps.collections.productsIn({ slug: slug, limit: COLLECTION_PAGE_SIZE, cursor: startCursor });
+      } catch (e2) {
+        // A bad/stale/tampered cursor surfaces as a TypeError whose message
+        // names the cursor. Behave like page 1 (a reachable, link-followable
+        // result) instead of a 404 — the collection still exists. Any other
+        // TypeError (an impossible slug change between get() and productsIn)
+        // is a 404; non-TypeErrors propagate.
+        if (e2 instanceof TypeError && /cursor/i.test(e2.message || "")) {
+          trail = [];
+          startCursor = null;
+          result = await deps.collections.productsIn({ slug: slug, limit: COLLECTION_PAGE_SIZE, cursor: null });
+        } else if (e2 instanceof TypeError) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        } else {
+          throw e2;
+        }
+      }
+
       var products = [];
       for (var i = 0; i < result.rows.length; i += 1) {
         var pid = result.rows[i].product_id || result.rows[i].id;
@@ -8923,6 +9043,7 @@ function mount(router, deps) {
       var cartCount = await _cartCountForReq(req);
       _send(res, 200, renderCollection(Object.assign({
         collection: col, products: products, shop_name: shopName, cart_count: cartCount,
+        cursor_trail: trail, next_cursor: result.next_cursor,
       }, _requestUrls(req))));
     });
   }

package/package.json

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