@blamejs/blamejs-shop 0.3.31 → 0.3.32

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- 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/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.31",
+  "version": "0.3.32",
   "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.32",
   "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": {