@aglyn/plugins-commerce 1.0.0-beta.199 → 1.0.0-beta.200

package/src/lib/server/catalog.js

@@ -1,3 +1,5 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -13,17 +15,13 @@
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
- */ import { _ as _extends } from "@swc/helpers/_/_extends";
+ */ import { nameSearchNormalizers } from "@aglyn/aglyn/app-utils/name-search";
 import * as Aglyn from "@aglyn/aglyn/server";
-import * as CommerceModel from "../model/index.js";
+import { planListQuery } from "@aglyn/shared-ui-jsx/const/list-query-plan";
 import { firebaseAdmin } from "@aglyn/tenant-data-admin";
-/**
- * Displayed price in cents (AGL-564): the low end of the variant range —
- * the number grid cards render (`$X` / `From $X`) — so price filtering
- * matches what visitors see.
- */ export function displayedPriceCents(product) {
-    return Math.round(CommerceModel.productPriceRange(product)[0] * 100);
-}
+import { applyListQuery } from "@aglyn/tenant-data-admin/server/list-query";
+import { smartCollectionScope, STOREFRONT_CATALOG_BASE, STOREFRONT_CATALOG_DECLARATION, STOREFRONT_CATALOG_SORTS, STOREFRONT_PRODUCT_TYPES, storefrontCatalogSort } from "../constants/storefront-catalog-query.js";
+import * as CommerceModel from "../model/index.js";
 /** Non-negative integer cents from a query param; undefined otherwise. */ function parsePriceCents(value) {
     const raw = String(value != null ? value : '').trim();
     if (!raw) return undefined;
@@ -31,35 +29,243 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
     if (!Number.isFinite(cents) || cents < 0) return undefined;
     return Math.round(cents);
 }
-/**
- * Case-insensitive catalog search (AGL-561): matches the product name,
- * description, or any tag. An empty/blank query matches everything.
- */ export function matchesCatalogQuery(product, query) {
-    var _product_description, _product_tags;
-    const needle = query.trim().toLowerCase();
-    if (!needle) return true;
-    return product.name.toLowerCase().includes(needle) || ((_product_description = product.description) != null ? _product_description : '').toLowerCase().includes(needle) || ((_product_tags = product.tags) != null ? _product_tags : []).some((tag)=>tag.toLowerCase().includes(needle));
-}
 /** A fresh read scope. One per render, never reused across hosts. */ export function createCatalogReadScope() {
     return {};
 }
+/** Most products one page returns. */ const CATALOG_PAGE_MAX = 100;
+/** Page size when a grid names none. */ const CATALOG_PAGE_DEFAULT = 24;
+/**
+ * Members of a MANUAL collection read by id. A hand-curated list is its own
+ * complete set, so it is read whole and every visitor control is answered over
+ * all of it rather than over a window of the catalog.
+ */ const MANUAL_COLLECTION_MAX = 1000;
+/** Ids per `getAll`, well inside the Admin SDK's comfortable batch. */ const GET_ALL_CHUNK = 100;
+function toRow(docSnapshot) {
+    var _raw_deletedAt, _product_name;
+    const raw = docSnapshot.data();
+    if (!raw) return null;
+    const product = CommerceModel.liftLegacyProduct(raw);
+    return {
+        id: docSnapshot.id,
+        product,
+        values: _extends({}, raw, {
+            status: product.status,
+            type: product.type,
+            deletedAt: (_raw_deletedAt = raw['deletedAt']) != null ? _raw_deletedAt : null
+        }, CommerceModel.productSearchFields({
+            name: String((_product_name = product.name) != null ? _product_name : ''),
+            variants: product.variants
+        }), CommerceModel.productStockFields(product))
+    };
+}
+/** A row's value at a queried path, as the query sees it. */ function rowValue(row, path) {
+    return row.values[path];
+}
+/** A held row a shopper may be shown: live and active, as the query's scope. */ const onSale = (row)=>STOREFRONT_CATALOG_BASE.every((filter)=>rowMatches(row, filter));
+/** One plan predicate over one row, with Firestore's meaning of each operator. */ function rowMatches(row, filter) {
+    const actual = rowValue(row, filter.path);
+    if (actual === undefined) return false;
+    const value = filter.value;
+    const list = Array.isArray(value) ? value : [
+        value
+    ];
+    switch(filter.op){
+        case '==':
+            return actual === value;
+        case '!=':
+            return actual !== null && actual !== value;
+        case 'in':
+            return list.includes(actual);
+        case 'array-contains':
+            return Array.isArray(actual) && actual.includes(value);
+        case 'array-contains-any':
+            return Array.isArray(actual) && actual.some((member)=>list.includes(member));
+        case '<':
+            return typeof actual === typeof value && actual < value;
+        case '<=':
+            return typeof actual === typeof value && actual <= value;
+        case '>':
+            return typeof actual === typeof value && actual > value;
+        case '>=':
+            return typeof actual === typeof value && actual >= value;
+        default:
+            return false;
+    }
+}
+/** A cursor: the last row's order value and id, opaque to the grid. */ function encodeCursor(value, id) {
+    return Buffer.from(JSON.stringify([
+        value != null ? value : null,
+        id
+    ])).toString('base64url');
+}
+function decodeCursor(raw) {
+    if (!raw) return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+        if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+        const [value, id] = parsed;
+        if (typeof id !== 'string' || !id) return null;
+        if (value !== null && typeof value !== 'string' && typeof value !== 'number') return null;
+        return {
+            value,
+            id
+        };
+    } catch (unused) {
+        return null;
+    }
+}
+const compareValues = (a, b)=>{
+    if (a === b) return 0;
+    // A row without the ordered value sorts after every row with one.
+    if (a === undefined || a === null) return 1;
+    if (b === undefined || b === null) return -1;
+    return a < b ? -1 : a > b ? 1 : 0;
+};
+/**
+ * One page of rows already held WHOLE — a manual collection, an id list, a
+ * smart collection's scan — ordered by `key` then id, after the cursor.
+ */ function pageHeldRows(rows, key, direction, after, max) {
+    const signed = (value)=>direction === 'desc' ? -value : value;
+    const ordered = [
+        ...rows
+    ].sort((a, b)=>signed(compareValues(key(a), key(b))) || signed(compareValues(a.id, b.id)));
+    const cursor = decodeCursor(after);
+    const start = cursor ? ordered.findIndex((row)=>signed(compareValues(key(row), cursor.value)) > 0 || compareValues(key(row), cursor.value) === 0 && signed(compareValues(row.id, cursor.id)) > 0) : 0;
+    if (start === -1) return {
+        rows: []
+    };
+    const page = ordered.slice(start, start + max);
+    const last = page[page.length - 1];
+    return _extends({
+        rows: page
+    }, last && start + max < ordered.length ? {
+        nextCursor: encodeCursor(key(last), last.id)
+    } : {});
+}
+/** Documents by id, in chunks, dropping the ones that do not exist. */ async function readProductsById(productsRef, ids) {
+    const firestore = firebaseAdmin.app().firestore();
+    const rows = [];
+    for(let start = 0; start < ids.length; start += GET_ALL_CHUNK){
+        const refs = ids.slice(start, start + GET_ALL_CHUNK).map((id)=>productsRef.doc(id));
+        if (!refs.length) continue;
+        const snapshots = await firestore.getAll(...refs);
+        for (const snapshot of snapshots){
+            if (!snapshot.exists) continue;
+            const row = toRow(snapshot);
+            if (row) rows.push(row);
+        }
+    }
+    return rows;
+}
+/** The card a grid renders for one product. */ function toItem(row) {
+    var _ref;
+    var _product_mediaUrls, _product_mediaUrls1, _product_tags;
+    const { product } = row;
+    const [minPrice, maxPrice] = CommerceModel.productPriceRange(product);
+    const primary = product.variants[0];
+    return _extends({
+        id: row.id,
+        name: product.name,
+        slug: product.slug,
+        type: product.type,
+        priceUsd: minPrice,
+        maxPriceUsd: maxPrice
+    }, (primary == null ? void 0 : primary.compareAtPriceUsd) ? {
+        compareAtPriceUsd: primary.compareAtPriceUsd
+    } : {}, ((_product_mediaUrls = product.mediaUrls) == null ? void 0 : _product_mediaUrls[0]) || product.imageUrl ? {
+        imageUrl: (_ref = (_product_mediaUrls1 = product.mediaUrls) == null ? void 0 : _product_mediaUrls1[0]) != null ? _ref : product.imageUrl
+    } : {}, {
+        // The same verdict the In stock chip queries (`soldOut`), from the one
+        // function every stock writer stores it through.
+        soldOut: CommerceModel.productStockFields(product).soldOut
+    }, ((_product_tags = product.tags) == null ? void 0 : _product_tags.length) ? {
+        tags: product.tags
+    } : {});
+}
+/**
+ * The plan's refusals, as the plan made them; the grid words each one. A
+ * search refused because a smart collection already holds the query's one
+ * array clause gets a reason a shopper can read.
+ */ function refusalsOf(plan) {
+    return plan.refused.map((refusal)=>refusal.clause === 'search' && refusal.reason.startsWith('this list is already narrowed') ? _extends({}, refusal, {
+            reason: 'this collection is already narrowed by a tag or category, which search cannot combine with'
+        }) : refusal);
+}
+/** How a sort reads in the grid's select, for the notice below. */ const SORT_LABELS = {
+    nameLower: 'Name',
+    createdAtMs: 'Newest'
+};
+/**
+ * The plan, ordered the way the visitor asked when a range forced its field.
+ *
+ * A range leads the order, so while the price slider (or a smart collection's
+ * "price under" rule) is set the query is ordered by price: "high to low"
+ * stays high to low, and any other sort — Name, Newest — becomes low to high
+ * and is SAID to, rather than silently replaced (AGL-3321).
+ */ function planFor(request, sort) {
+    const plan = planListQuery(STOREFRONT_CATALOG_DECLARATION, request, nameSearchNormalizers);
+    if (plan.orderBy.path !== sort.path) {
+        const asked = SORT_LABELS[sort.path];
+        return asked ? _extends({}, plan, {
+            notices: [
+                ...plan.notices,
+                `Sorted by price, low to high, while a price range is set — ${asked} applies again when it is cleared.`
+            ]
+        }) : plan;
+    }
+    return plan.orderBy.direction !== sort.direction ? _extends({}, plan, {
+        orderBy: sort
+    }) : plan;
+}
+/** A price bound as the grid's slider shows it, for a refusal's sentence. */ const dollars = (cents)=>`$${(cents / 100).toFixed(cents % 100 ? 2 : 0)}`;
 /**
- * Public catalog listing (AGL-291): active products for storefront
- * blocks — filterable by collection/category slug or tag, sortable,
- * capped at 100 items per request. Storefront catalog UX (AGL-561)
- * adds text search, a product-type filter, offset paging (for Load
- * more), and facets for filter chips. The price-range filter (AGL-564)
- * bounds on the displayed price and reports `priceBounds`.
- * Read-only public data; prices here are display-only (charges always
- * come from the docs server-side).
+ * Public catalog listing (AGL-291): active products for storefront blocks —
+ * a collection, a category or a tag, searched, filtered by type and price,
+ * sorted, and paged by cursor (AGL-561, AGL-564).
+ *
+ * EVERY CONTROL IS ON THE QUERY (AGL-3321). This used to read `limit(500)`
+ * products and narrow them in memory, so a catalog past five hundred answered
+ * every search, chip and slider from an arbitrary five hundred of them. Now:
+ *
+ *   - the catalog, a category or a tag — ONE query built by the list query
+ *     plan (`STOREFRONT_CATALOG_DECLARATION`), paged by its own cursor;
+ *   - a SMART collection whose rules a query can hold — the same query, with
+ *     the rules as its scope (`smartCollectionScope`);
+ *   - a MANUAL collection, or an explicit id list — read whole by id, which
+ *     is a complete set, and answered over all of it;
+ *   - a smart collection whose rules no query can hold (a NOT, an OR, a name
+ *     rule, a price over) — the same query, scoped by the membership every
+ *     product writer stores (`collectionIds array-contains <id>`), which the
+ *     collection-membership route re-stamps whenever the rules change.
+ *
+ * What one query cannot hold — two array clauses, two ranges — is refused by
+ * name in `refused` and not applied, never applied to some rows and not
+ * others. Read-only public data; prices here are display-only (charges
+ * always come from the docs server-side).
  *
  * Extracted from the handler (AGL-659) so the site-page enricher seeds a
  * grid's first page through THIS function rather than a reimplementation
  * of it. A seed that filters or sorts differently from the API would
  * server-render one set of products and hydrate to another.
  */ export async function queryPublicCatalog(params) {
-    var _params_collectionSlug, _params_categorySlug, _params_collectionId, _params_categoryId, _params_tag, _params_query, _params_type, _params_ids, _params_limit, _params_offset;
-    var _categoriesSnapshot_docs_;
+    var _reads, _results;
+    const { reads } = params, question = _object_without_properties_loose(params, [
+        "reads"
+    ]);
+    if (!reads) return runPublicCatalog(question);
+    const key = JSON.stringify(question);
+    (_results = (_reads = reads).results) != null ? _results : _reads.results = new Map();
+    const shared = reads.results.get(key);
+    if (shared) return shared;
+    // Stored BEFORE it is awaited, so grids running together under one
+    // `Promise.all` share the one in-flight read rather than racing to store it.
+    const pending = runPublicCatalog(question, reads);
+    reads.results.set(key, pending);
+    return pending;
+}
+async function runPublicCatalog(params, reads) {
+    var _params_collectionSlug, _params_categorySlug, _params_collectionId, _params_categoryId, _params_tag, _params_query, _params_ids, _params_limit;
+    var _categoriesSnapshot_docs_, _lowest_docs_, _highest_docs_;
     const { hostId } = params;
     const collectionSlug = (_params_collectionSlug = params.collectionSlug) != null ? _params_collectionSlug : '';
     const categorySlug = (_params_categorySlug = params.categorySlug) != null ? _params_categorySlug : '';
@@ -67,36 +273,38 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
     // for legacy screens and template-URL resolution.
     const collectionIdParam = (_params_collectionId = params.collectionId) != null ? _params_collectionId : '';
     const categoryIdParam = (_params_categoryId = params.categoryId) != null ? _params_categoryId : '';
-    const tag = (_params_tag = params.tag) != null ? _params_tag : '';
-    const query = (_params_query = params.query) != null ? _params_query : '';
-    const type = [
-        'physical',
-        'digital',
-        'service'
-    ].includes((_params_type = params.type) != null ? _params_type : '') ? params.type : '';
-    const ids = ((_params_ids = params.ids) != null ? _params_ids : []).slice(0, 100);
-    const minPriceCents = params.minPriceCents;
-    const maxPriceCents = params.maxPriceCents;
-    const sort = params.sort || 'name';
-    const max = Math.min(100, Math.max(1, Number((_params_limit = params.limit) != null ? _params_limit : 24)));
-    const offset = Math.max(0, Math.round(Number((_params_offset = params.offset) != null ? _params_offset : 0)) || 0);
+    const tag = ((_params_tag = params.tag) != null ? _params_tag : '').trim();
+    const query = ((_params_query = params.query) != null ? _params_query : '').trim();
+    const type = STOREFRONT_PRODUCT_TYPES.includes(params.type) ? params.type : '';
+    const ids = ((_params_ids = params.ids) != null ? _params_ids : []).slice(0, CATALOG_PAGE_MAX);
+    const asked = Math.floor(Number((_params_limit = params.limit) != null ? _params_limit : CATALOG_PAGE_DEFAULT));
+    const max = Number.isFinite(asked) && asked > 0 ? Math.min(CATALOG_PAGE_MAX, asked) : CATALOG_PAGE_DEFAULT;
+    const sort = storefrontCatalogSort(params.sort);
     const wantFacets = Boolean(params.facets);
     const firestore = firebaseAdmin.app().firestore();
     const hostRef = firestore.collection('hosts').doc(hostId);
-    const reads = params.reads;
-    // Assigned into the scope BEFORE it is awaited, so grids running together
-    // under one `Promise.all` share the single in-flight read rather than each
-    // starting their own and racing to store it.
-    const sharedProducts = ()=>{
-        var _reads, _products;
-        return reads ? (_products = (_reads = reads).products) != null ? _products : _reads.products = hostRef.collection('products').limit(500).get() : hostRef.collection('products').limit(500).get();
-    };
+    const productsRef = hostRef.collection('products');
     const sharedCategories = ()=>{
         var _reads, _categories;
         return reads ? (_categories = (_reads = reads).categories) != null ? _categories : _reads.categories = hostRef.collection('productCategories').limit(200).get() : hostRef.collection('productCategories').limit(200).get();
     };
-    const [productsSnapshot, collectionsSnapshot, categoriesSnapshot, collectionByIdSnapshot, facetsSnapshot] = await Promise.all([
-        sharedProducts(),
+    // Wishlist and related rendering (AGL-297): an explicit id list is its own
+    // complete set — read it by id, keep what is on sale, in the given order.
+    if (ids.length) {
+        const order = new Map(ids.map((id, index)=>[
+                id,
+                index
+            ]));
+        const rows = (await readProductsById(productsRef, ids)).filter(onSale);
+        rows.sort((a, b)=>{
+            var _order_get, _order_get1;
+            return ((_order_get = order.get(a.id)) != null ? _order_get : 0) - ((_order_get1 = order.get(b.id)) != null ? _order_get1 : 0);
+        });
+        return {
+            items: rows.slice(0, max).map(toItem)
+        };
+    }
+    const [collectionsSnapshot, categoriesSnapshot, collectionByIdSnapshot, facetsSnapshot] = await Promise.all([
         // limit(5) not 1: content collections share this path and a slug is
         // unique only within a kind (AGL-954) — the catalog match is picked
         // out below rather than trusting whichever doc came back first.
@@ -106,114 +314,12 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
         wantFacets ? sharedCategories() : null
     ]);
     const collectionById = (collectionByIdSnapshot == null ? void 0 : collectionByIdSnapshot.exists) && Aglyn.hostCollectionKind(collectionByIdSnapshot.data()) === 'catalog' ? collectionByIdSnapshot : undefined;
-    const collection = collectionById != null ? collectionById : collectionsSnapshot == null ? void 0 : collectionsSnapshot.docs.find((docSnapshot)=>Aglyn.hostCollectionKind(docSnapshot.data()) === 'catalog');
-    const categoryId = categoryIdParam || (categoriesSnapshot == null ? void 0 : (_categoriesSnapshot_docs_ = categoriesSnapshot.docs[0]) == null ? void 0 : _categoriesSnapshot_docs_.id);
-    let products = productsSnapshot.docs.map((docSnapshot)=>_extends({}, CommerceModel.liftLegacyProduct(docSnapshot.data()), {
-            $id: docSnapshot.id
-        })).filter((product)=>!product.deletedAt && product.status === 'active');
-    if (collection) {
-        const shaped = collection.data();
-        products = products.filter((product)=>CommerceModel.matchesCollection(product, shaped, product.$id));
-        if (shaped.mode === 'manual') {
-            var _shaped_productIds;
-            const order = new Map(((_shaped_productIds = shaped.productIds) != null ? _shaped_productIds : []).map((id, index)=>[
-                    id,
-                    index
-                ]));
-            products.sort((a, b)=>{
-                var _order_get, _order_get1;
-                return ((_order_get = order.get(a.$id)) != null ? _order_get : 999) - ((_order_get1 = order.get(b.$id)) != null ? _order_get1 : 999);
-            });
-        }
-    }
-    if (categoryId) {
-        products = products.filter((product)=>{
-            var _product_categoryIds;
-            return ((_product_categoryIds = product.categoryIds) != null ? _product_categoryIds : []).includes(categoryId);
-        });
-    }
-    if (tag) {
-        products = products.filter((product)=>{
-            var _product_tags;
-            return ((_product_tags = product.tags) != null ? _product_tags : []).includes(tag);
-        });
-    }
-    // Storefront catalog UX (AGL-561): type filter + text search.
-    if (type) {
-        products = products.filter((product)=>product.type === type);
-    }
-    if (query.trim()) {
-        products = products.filter((product)=>matchesCatalogQuery(product, query));
-    }
-    // Wishlist rendering (AGL-297): explicit id list, given order.
-    if (ids.length) {
-        const order = new Map(ids.map((id, index)=>[
-                id,
-                index
-            ]));
-        products = products.filter((product)=>order.has(product.$id)).sort((a, b)=>{
-            var _order_get, _order_get1;
-            return ((_order_get = order.get(a.$id)) != null ? _order_get : 0) - ((_order_get1 = order.get(b.$id)) != null ? _order_get1 : 0);
-        });
-    }
-    // Price facets + filter (AGL-564): bounds are computed before the
-    // price filter (with everything else applied) so the grid's slider
-    // stays anchored while the visitor narrows it. Both use the
-    // displayed price — the low end of the variant range grid cards
-    // show — so filtering matches what visitors see.
-    const priceBounds = wantFacets && products.length ? {
-        minCents: Math.min(...products.map(displayedPriceCents)),
-        maxCents: Math.max(...products.map(displayedPriceCents))
-    } : undefined;
-    if (minPriceCents != null || maxPriceCents != null) {
-        products = products.filter((product)=>{
-            const cents = displayedPriceCents(product);
-            return (minPriceCents == null || cents >= minPriceCents) && (maxPriceCents == null || cents <= maxPriceCents);
-        });
-    }
-    if (sort === 'price-asc' || sort === 'price-desc') {
-        products.sort((a, b)=>{
-            const [minA] = CommerceModel.productPriceRange(a);
-            const [minB] = CommerceModel.productPriceRange(b);
-            return sort === 'price-asc' ? minA - minB : minB - minA;
-        });
-    } else if (sort === 'newest') {
-        products.sort((a, b)=>{
-            var _b_createdAtMs, _a_createdAtMs;
-            return ((_b_createdAtMs = b.createdAtMs) != null ? _b_createdAtMs : 0) - ((_a_createdAtMs = a.createdAtMs) != null ? _a_createdAtMs : 0);
-        });
-    } else if (!ids.length && (!collection || collection.data().mode !== 'manual')) {
-        products.sort((a, b)=>a.name.localeCompare(b.name));
-    }
-    // Offset paging (AGL-561): grids pass `offset` for Load more;
-    // `nextOffset` comes back only while more filtered items remain.
-    const page = products.slice(offset, offset + max);
-    const nextOffset = offset + max < products.length ? offset + max : undefined;
-    const items = page.map((product)=>{
-        var _ref;
-        var _product_mediaUrls, _product_mediaUrls1, _product_tags;
-        const [minPrice, maxPrice] = CommerceModel.productPriceRange(product);
-        const primary = product.variants[0];
-        const inventory = CommerceModel.productInventory(product);
-        return _extends({
-            id: product.$id,
-            name: product.name,
-            slug: product.slug,
-            type: product.type,
-            priceUsd: minPrice,
-            maxPriceUsd: maxPrice
-        }, (primary == null ? void 0 : primary.compareAtPriceUsd) ? {
-            compareAtPriceUsd: primary.compareAtPriceUsd
-        } : {}, ((_product_mediaUrls = product.mediaUrls) == null ? void 0 : _product_mediaUrls[0]) || product.imageUrl ? {
-            imageUrl: (_ref = (_product_mediaUrls1 = product.mediaUrls) == null ? void 0 : _product_mediaUrls1[0]) != null ? _ref : product.imageUrl
-        } : {}, {
-            soldOut: inventory != null && inventory <= 0 && product.oversellPolicy !== 'backorder'
-        }, ((_product_tags = product.tags) == null ? void 0 : _product_tags.length) ? {
-            tags: product.tags
-        } : {});
-    });
+    const collectionDoc = collectionById != null ? collectionById : collectionsSnapshot == null ? void 0 : collectionsSnapshot.docs.find((docSnapshot)=>Aglyn.hostCollectionKind(docSnapshot.data()) === 'catalog');
+    const collection = collectionDoc ? collectionDoc.data() : undefined;
+    const categoryId = categoryIdParam || (categoriesSnapshot == null ? void 0 : (_categoriesSnapshot_docs_ = categoriesSnapshot.docs[0]) == null ? void 0 : _categoriesSnapshot_docs_.id) || '';
     // Category facets (AGL-561): id/name/slug for grid filter chips,
-    // parent-tree order preserved (order, then name).
+    // parent-tree order preserved (order, then name). The taxonomy is a
+    // bounded picker, read whole.
     const categories = facetsSnapshot ? facetsSnapshot.docs.map((docSnapshot)=>{
         var _data_name, _data_slug, _data_order;
         const data = docSnapshot.data();
@@ -228,15 +334,230 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
             name,
             slug
         })) : undefined;
-    return _extends({
-        items
-    }, nextOffset != null ? {
-        nextOffset
-    } : {}, categories ? {
-        categories
-    } : {}, priceBounds ? {
-        priceBounds
-    } : {});
+    // The visitor's controls, as clauses on the one declaration. A price
+    // clause carries the dollars the slider showed, for a refusal's sentence.
+    const priceClauses = [
+        ...params.minPriceCents != null ? [
+            {
+                field: 'price',
+                op: '>=',
+                value: String(params.minPriceCents),
+                label: dollars(params.minPriceCents)
+            }
+        ] : [],
+        ...params.maxPriceCents != null ? [
+            {
+                field: 'price',
+                op: '<=',
+                value: String(params.maxPriceCents),
+                label: dollars(params.maxPriceCents)
+            }
+        ] : []
+    ];
+    const otherClauses = [
+        ...categoryId ? [
+            {
+                field: 'category',
+                op: 'contains',
+                value: categoryId
+            }
+        ] : [],
+        ...tag ? [
+            {
+                field: 'tag',
+                op: 'contains',
+                value: tag
+            }
+        ] : [],
+        ...type ? [
+            {
+                field: 'type',
+                op: 'equals',
+                value: type
+            }
+        ] : [],
+        ...params.inStock ? [
+            {
+                field: 'stock',
+                op: 'is',
+                value: 'false'
+            }
+        ] : []
+    ];
+    // The words typed, as a quick search hands them over: the plan searches by
+    // the first and says so when there were more.
+    const search = query.split(/\s+/).filter(Boolean);
+    const result = (rows, plan, extra = {})=>{
+        var _extra_notices;
+        const refused = refusalsOf(plan);
+        const notices = [
+            ...plan.notices,
+            ...(_extra_notices = extra.notices) != null ? _extra_notices : []
+        ];
+        return _extends({
+            items: rows.map(toItem)
+        }, extra.nextCursor ? {
+            nextCursor: extra.nextCursor
+        } : {}, categories ? {
+            categories
+        } : {}, extra.priceBounds ? {
+            priceBounds: extra.priceBounds
+        } : {}, refused.length ? {
+            refused
+        } : {}, notices.length ? {
+            notices
+        } : {});
+    };
+    /*
+   * A collection held WHOLE: a manual one's members, or a smart one whose
+   * rules no query can hold. The plan still decides what is applied — the
+   * same refusals as the query path, so a grid behaves the same whatever it
+   * lists — and its predicates are answered over every held row.
+   */ const answerHeld = (held, options)=>{
+        const request = {
+            base: STOREFRONT_CATALOG_BASE,
+            clauses: [
+                ...otherClauses,
+                ...priceClauses
+            ],
+            search,
+            sort
+        };
+        const plan = planFor(request, sort);
+        const unpriced = planFor(_extends({}, request, {
+            clauses: otherClauses
+        }), sort);
+        const matched = held.filter((row)=>plan.filters.every((filter)=>rowMatches(row, filter)));
+        // Bounds span every OTHER control, so the slider stays anchored while the
+        // visitor narrows it.
+        const bounding = held.filter((row)=>unpriced.filters.every((filter)=>rowMatches(row, filter)));
+        const priceBounds = wantFacets && bounding.length ? {
+            minCents: Math.min(...bounding.map((row)=>Number(rowValue(row, 'priceFromCents')))),
+            maxCents: Math.max(...bounding.map((row)=>Number(rowValue(row, 'priceFromCents'))))
+        } : undefined;
+        // A manual collection keeps the merchant's order unless the visitor (or
+        // the author) chose a price or recency sort.
+        const keepManual = options.manualOrder && plan.orderBy.path === STOREFRONT_CATALOG_SORTS.name.path;
+        const page = keepManual ? pageHeldRows(matched, (row)=>{
+            var _ref;
+            var _options_manualOrder;
+            return (_ref = (_options_manualOrder = options.manualOrder) == null ? void 0 : _options_manualOrder.get(row.id)) != null ? _ref : Number.MAX_SAFE_INTEGER;
+        }, 'asc', params.after, max) : pageHeldRows(matched, (row)=>rowValue(row, plan.orderBy.path), plan.orderBy.direction, params.after, max);
+        return result(page.rows, plan, _extends({}, page.nextCursor ? {
+            nextCursor: page.nextCursor
+        } : {}, priceBounds ? {
+            priceBounds
+        } : {}, options.notices ? {
+            notices: options.notices
+        } : {}));
+    };
+    let scope = [];
+    if (collection) {
+        var _collection_rules;
+        if (collection.mode === 'manual') {
+            var _collection_productIds;
+            const memberIds = ((_collection_productIds = collection.productIds) != null ? _collection_productIds : []).slice(0, MANUAL_COLLECTION_MAX);
+            const manualOrder = new Map(memberIds.map((id, index)=>[
+                    id,
+                    index
+                ]));
+            return answerHeld(await readProductsById(productsRef, memberIds), {
+                manualOrder
+            });
+        }
+        const smart = smartCollectionScope(collection);
+        if (!((_collection_rules = collection.rules) != null ? _collection_rules : []).length) {
+            // A smart collection with no rules holds nothing (`matchesCollection`).
+            return result([], planFor({
+                base: STOREFRONT_CATALOG_BASE,
+                clauses: [],
+                sort
+            }, sort));
+        }
+        if ('unservable' in smart) {
+            var _ref;
+            // Rules no query can express (a NOT, an OR, a name rule, a price over)
+            // are answered by the membership every product writer stores
+            // (`collectionIds`, AGL-3321): one array clause on the same query, so
+            // the grid's other array controls are refused by name beside it.
+            scope = [
+                {
+                    path: CommerceModel.PRODUCT_COLLECTION_IDS,
+                    op: 'array-contains',
+                    value: String((_ref = collectionDoc == null ? void 0 : collectionDoc.id) != null ? _ref : '')
+                }
+            ];
+        } else {
+            scope = smart.filters;
+            // A "type is not" rule is `type in […]`; the visitor's Type chip is the
+            // narrower question, answered inside it or not at all.
+            const typeRule = scope.find((filter)=>filter.path === 'type');
+            if (typeRule && type) {
+                const allowed = Array.isArray(typeRule.value) ? typeRule.value : [
+                    typeRule.value
+                ];
+                if (!allowed.includes(type)) {
+                    return result([], planFor({
+                        base: STOREFRONT_CATALOG_BASE,
+                        clauses: [],
+                        sort
+                    }, sort));
+                }
+                scope = scope.filter((filter)=>filter !== typeRule);
+            }
+        }
+    }
+    // THE QUERY: every predicate, one order, a page and one row to spare.
+    const request = {
+        base: [
+            ...STOREFRONT_CATALOG_BASE,
+            ...scope
+        ],
+        clauses: [
+            ...otherClauses,
+            ...priceClauses
+        ],
+        search,
+        sort
+    };
+    const plan = planFor(request, sort);
+    const byId = firebaseAdmin.firestore.FieldPath.documentId();
+    const ordered = (target)=>applyListQuery(productsRef, target).orderBy(byId, target.orderBy.direction);
+    let pageQuery = ordered(plan);
+    const cursor = decodeCursor(params.after);
+    if (cursor) pageQuery = pageQuery.startAfter(cursor.value, cursor.id);
+    // Bounds span every OTHER control, so the slider stays anchored while the
+    // visitor narrows it: the lowest and highest price the rest allows, as two
+    // one-row reads ordered by price.
+    const byPrice = STOREFRONT_CATALOG_SORTS['price-asc'];
+    const unpriced = wantFacets ? planFor(_extends({}, request, {
+        clauses: otherClauses,
+        sort: byPrice
+    }), byPrice) : null;
+    const pricedBy = (target, direction)=>ordered(_extends({}, target, {
+            orderBy: {
+                path: 'priceFromCents',
+                direction
+            }
+        })).limit(1).get();
+    const [snapshot, lowest, highest] = await Promise.all([
+        pageQuery.limit(max + 1).get(),
+        unpriced ? pricedBy(unpriced, 'asc') : null,
+        unpriced ? pricedBy(unpriced, 'desc') : null
+    ]);
+    const docs = snapshot.docs.slice(0, max);
+    const rows = docs.map(toRow).filter((row)=>Boolean(row));
+    const last = docs[docs.length - 1];
+    const low = lowest == null ? void 0 : (_lowest_docs_ = lowest.docs[0]) == null ? void 0 : _lowest_docs_.get('priceFromCents');
+    const high = highest == null ? void 0 : (_highest_docs_ = highest.docs[0]) == null ? void 0 : _highest_docs_.get('priceFromCents');
+    return result(rows, plan, _extends({}, last && snapshot.docs.length > max ? {
+        nextCursor: encodeCursor(last.get(plan.orderBy.path), last.id)
+    } : {}, typeof low === 'number' && typeof high === 'number' ? {
+        priceBounds: {
+            minCents: low,
+            maxCents: high
+        }
+    } : {}));
 }
 /** Public catalog listing endpoint — a thin parse over queryPublicCatalog. */ export const catalogHandler = async (req, res)=>{
     var _req_query_hostId;
@@ -245,7 +566,7 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
         error: 'Missing hostId'
     });
     try {
-        var _req_query_collection, _req_query_category, _req_query_collectionId, _req_query_categoryId, _req_query_tag, _req_query_q, _req_query_type, _req_query_ids, _req_query_sort, _req_query_limit, _req_query_offset, _req_query_facets;
+        var _req_query_collection, _req_query_category, _req_query_collectionId, _req_query_categoryId, _req_query_tag, _req_query_q, _req_query_type, _req_query_inStock, _req_query_ids, _req_query_sort, _req_query_limit, _req_query_after, _req_query_facets;
         const result = await queryPublicCatalog({
             hostId,
             collectionSlug: String((_req_query_collection = req.query.collection) != null ? _req_query_collection : ''),
@@ -255,13 +576,14 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
             tag: String((_req_query_tag = req.query.tag) != null ? _req_query_tag : ''),
             query: String((_req_query_q = req.query.q) != null ? _req_query_q : ''),
             type: String((_req_query_type = req.query.type) != null ? _req_query_type : ''),
+            inStock: String((_req_query_inStock = req.query.inStock) != null ? _req_query_inStock : '') === '1',
             ids: String((_req_query_ids = req.query.ids) != null ? _req_query_ids : '').split(',').map((id)=>id.trim()).filter(Boolean),
             // Price-range filter (AGL-564): integer cents on the displayed price.
             minPriceCents: parsePriceCents(req.query.minPriceCents),
             maxPriceCents: parsePriceCents(req.query.maxPriceCents),
             sort: String((_req_query_sort = req.query.sort) != null ? _req_query_sort : 'name'),
-            limit: Number((_req_query_limit = req.query.limit) != null ? _req_query_limit : 24),
-            offset: Number((_req_query_offset = req.query.offset) != null ? _req_query_offset : 0),
+            limit: Number((_req_query_limit = req.query.limit) != null ? _req_query_limit : CATALOG_PAGE_DEFAULT),
+            after: String((_req_query_after = req.query.after) != null ? _req_query_after : ''),
             facets: String((_req_query_facets = req.query.facets) != null ? _req_query_facets : '') === '1'
         });
         res.setHeader('Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300');