@zappie/verify 0.3.3 → 0.3.5

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   sumMoney,
   validateConfig,
   validateLine
-} from "./chunk-CW3HI5TY.js";
+} from "./chunk-5DRY6Y4G.js";
 
 // src/browser.ts
 var CHROMIUM_ENV = "ZAPPIE_VERIFY_CHROMIUM";
@@ -1599,13 +1599,13 @@ async function readMenu(options) {
 function sortedItems(menu) {
   return Object.values(menu.items).sort((a, b) => a.id.localeCompare(b.id));
 }
-function simpleItem(menu) {
-  return sortedItems(menu).find(
+function simpleItems(menu) {
+  return sortedItems(menu).filter(
     (item) => item.isAvailable && !item.optionGroups.some((group) => group.required)
   );
 }
-function configurableItem(menu) {
-  return sortedItems(menu).find(
+function configurableItems(menu) {
+  return sortedItems(menu).filter(
     (item) => item.isAvailable && item.optionGroups.some((group) => group.required)
   );
 }
@@ -1628,6 +1628,12 @@ function catalogues(menu) {
     };
   }).filter((catalogue) => catalogue.items.length > 0);
 }
+function sellableItems(menu) {
+  const held = new Set(menu.categories.flatMap((category) => category.itemIds));
+  return sortedItems(menu).filter(
+    (item) => item.isAvailable && (held.size === 0 || held.has(item.id))
+  );
+}
 function fillStartPath(template, menu) {
   const first = catalogues(menu)[0]?.id ?? menu.menus?.[0]?.id ?? menu.id;
   return { path: cataloguePage(template, first, menu.branchId), menuId: first };
@@ -1682,6 +1688,42 @@ function itemPath(options, menu, itemId) {
   return holder && options.cataloguePath ? cataloguePage(options.cataloguePath, holder.id, menu.branchId) : startPath(options);
 }
 
+// src/checks/sample.ts
+import { randomInt } from "crypto";
+var SEED_ENV = "ZAPPIE_VERIFY_SEED";
+var MAX_SEED = 2 ** 32;
+function sampleSeed(option, env = process.env) {
+  for (const value of [option, env[SEED_ENV]?.trim()]) {
+    if (value === void 0 || value === "") {
+      continue;
+    }
+    const seed = Number(value);
+    if (Number.isInteger(seed) && seed >= 0 && seed < MAX_SEED) {
+      return seed;
+    }
+  }
+  return randomInt(0, MAX_SEED);
+}
+function seededRandom(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let value = state;
+    value = Math.imul(value ^ value >>> 15, value | 1);
+    value ^= value + Math.imul(value ^ value >>> 7, value | 61);
+    return ((value ^ value >>> 14) >>> 0) / MAX_SEED;
+  };
+}
+function sample(values, count, random) {
+  const pool = [...values];
+  const size = Math.min(Math.max(0, count), pool.length);
+  for (let index = 0; index < size; index++) {
+    const pick = index + Math.floor(random() * (pool.length - index));
+    [pool[index], pool[pick]] = [pool[pick], pool[index]];
+  }
+  return pool.slice(0, size);
+}
+
 // ../sdk/src/pricing/index.ts
 var cheapest = (prices) => prices.filter((price) => price.amountMinor >= 0).sort((a, b) => a.amountMinor - b.amountMinor)[0];
 function startingPrice(item) {
@@ -1708,15 +1750,6 @@ function showsFromPrice(item) {
 }
 
 // src/checks/menu-match.ts
-function menuCoverage(items, shownIds) {
-  const available = items.filter((item) => item.isAvailable);
-  const shown = available.filter((item) => shownIds.has(item.id)).length;
-  return {
-    available: available.length,
-    shown,
-    passes: available.length === 0 || shown / available.length >= 0.95
-  };
-}
 function priceMatches(text, formatted) {
   return text?.includes(formatted) ?? false;
 }
@@ -1731,100 +1764,336 @@ function shownPrices(item) {
   return prices;
 }
 
-// src/checks/v03-menu.ts
-var v03 = {
-  id: "V03",
-  title: "Menu matches store",
-  viewports: "mobile",
-  async run({ page, options, fault }, viewport) {
-    const menu = await readMenu(options);
-    await page.setViewportSize(viewport);
-    const pages = cataloguePages(options, menu);
-    const severalMenus = !options.cataloguePath && pages[0]?.name === void 0 && catalogues(menu).length > 1;
-    for (const catalogue of pages) {
-      await open(page, catalogue.path);
-      await applyPageFault(page, fault);
-      await judgeCatalogue(
-        page,
-        catalogue.items,
-        catalogue.name === void 0 ? "menu" : `${catalogue.name} menu at ${catalogue.path}`,
-        severalMenus
-      );
+// src/checks/sitemap.ts
+var MAX_SITEMAP_FILES = 10;
+var entities = {
+  amp: "&",
+  apos: "'",
+  gt: ">",
+  lt: "<",
+  quot: '"'
+};
+function locations(xml) {
+  return [...xml.matchAll(/<loc>\s*([^<]*?)\s*<\/loc>/g)].map(
+    (match) => match[1].replace(
+      /&(amp|apos|gt|lt|quot);/g,
+      (entity) => entities[entity.slice(1, -1)] ?? entity
+    )
+  );
+}
+function sitemapPath(location2) {
+  try {
+    const url = new URL(location2, "http://site.invalid");
+    return `${url.pathname}${url.search}`;
+  } catch {
+    return void 0;
+  }
+}
+async function readSitemap(fetchText) {
+  const queue = ["/sitemap.xml"];
+  const seen = /* @__PURE__ */ new Set();
+  const pages = /* @__PURE__ */ new Set();
+  let found = false;
+  while (queue.length > 0 && seen.size < MAX_SITEMAP_FILES) {
+    const path4 = queue.shift();
+    if (seen.has(path4)) {
+      continue;
+    }
+    seen.add(path4);
+    const xml = await fetchText(path4).catch(() => void 0);
+    if (xml === void 0) {
+      continue;
+    }
+    if (/<sitemapindex[\s>]/.test(xml)) {
+      found = true;
+      for (const location2 of locations(xml)) {
+        const child = sitemapPath(location2);
+        if (child !== void 0) {
+          queue.push(child);
+        }
+      }
+    } else if (/<urlset[\s>]/.test(xml)) {
+      found = true;
+      for (const location2 of locations(xml)) {
+        const page = sitemapPath(location2);
+        if (page !== void 0) {
+          pages.add(page);
+        }
+      }
     }
   }
-};
-async function judgeCatalogue(page, items, menuName, severalMenus) {
-  const available = items.filter((item) => item.isAvailable);
-  const shownIds = /* @__PURE__ */ new Set();
-  const markerText = /* @__PURE__ */ new Map();
-  for (const item of available) {
-    const marker = page.locator(`[data-zappie-item="${item.id}"]`);
-    const text = await visibleMarkerText(marker);
-    markerText.set(item.id, text);
-    const prices = shownPrices(item);
-    if (text.some(
-      (value) => nameMatches(value, item.name) && prices.some((price) => priceMatches(value, normalizeText(price)))
-    ) || await marker.count() === 0 && await page.getByText(item.name, { exact: true }).filter({ visible: true }).count() > 0) {
-      shownIds.add(item.id);
+  return found ? [...pages] : void 0;
+}
+function itemIdInPath(path4, itemIds) {
+  let url;
+  try {
+    url = new URL(path4, "http://site.invalid");
+  } catch {
+    return void 0;
+  }
+  const values = [
+    ...url.pathname.split("/").filter(Boolean),
+    ...url.searchParams.values()
+  ];
+  for (const raw of values.reverse()) {
+    let value;
+    try {
+      value = decodeURIComponent(raw);
+    } catch {
+      value = raw;
+    }
+    for (const candidate of [
+      value,
+      `item_${value}`,
+      value.startsWith("item_") ? value.slice("item_".length) : void 0
+    ]) {
+      if (candidate !== void 0 && itemIds.has(candidate)) {
+        return candidate;
+      }
     }
   }
-  for (const item of available) {
-    if (shownIds.has(item.id)) {
-      continue;
+  return void 0;
+}
+function itemPages(paths, itemIds) {
+  const pages = /* @__PURE__ */ new Map();
+  for (const path4 of paths) {
+    const id = itemIdInPath(path4, itemIds);
+    if (id !== void 0 && !pages.has(id)) {
+      pages.set(id, path4);
     }
-    const text = markerText.get(item.id)?.find((value) => nameMatches(value, item.name));
-    if (text === void 0) {
+  }
+  return pages;
+}
+
+// src/checks/v03-judge.ts
+var SAMPLE_SIZE = 20;
+var MAX_MENU_PAGES = 3;
+var MIN_PAGE_ITEMS = 8;
+var NAME_PROBES = 20;
+function judgedScopes(scopes, seed) {
+  if (scopes.length <= MAX_MENU_PAGES) {
+    return scopes;
+  }
+  const [first, ...rest] = scopes;
+  const drawn = new Set(
+    sample(rest, MAX_MENU_PAGES - 1, seededRandom(seed ^ 2654435769))
+  );
+  return [first, ...rest.filter((scope) => drawn.has(scope))];
+}
+function contractItemPath(item) {
+  const id = item.id.startsWith("item_") ? item.id : `item_${item.id}`;
+  return `/item/${encodeURIComponent(id)}`;
+}
+async function judgeCatalogue(input) {
+  const { site, catalogue, seed } = input;
+  const random = seededRandom(seed);
+  const details = {
+    seed,
+    pageLoads: 0,
+    availableItems: catalogue.length,
+    firstPageItems: 0,
+    nextPage: "not-needed",
+    sampledItems: []
+  };
+  input.record?.(details);
+  const ids = new Set(Object.keys(input.items));
+  const sitemapPaths = await readSitemap(site.fetchText);
+  const sitemapPages = sitemapPaths && itemPages(sitemapPaths, ids);
+  if (sitemapPages) {
+    details.sitemapItems = sitemapPages.size;
+  }
+  const cardLinks = /* @__PURE__ */ new Map();
+  let paginated = false;
+  for (const [index, scope] of input.scopes.entries()) {
+    const label2 = scope.name === void 0 ? "menu" : `${scope.name} menu at ${scope.path}`;
+    details.pageLoads++;
+    const first = await site.open(scope.path);
+    const shown = await judgePage(first, input, label2, cardLinks);
+    const available = scope.items.filter((item) => item.isAvailable);
+    const count = available.filter((item) => shown.has(item.id)).length;
+    if (index === 0) {
+      details.firstPageItems = count;
+    }
+    if (first.markers === 0 && available.length > 0) {
+      const names = available.slice(0, NAME_PROBES).map((item) => item.name);
+      assertion(
+        !await site.namesShown(names),
+        "item_marker_missing",
+        `The ${label2} has no item marker`,
+        "Add data-zappie-item to each rendered menu item."
+      );
+    }
+    if (count >= available.length) {
       continue;
     }
+    assertion(
+      count > 0 || input.severalMenus,
+      "menu_mismatch",
+      `The ${label2} shows ${count} of ${available.length} available items`,
+      'Render every available item with a visible data-zappie-item marker that contains its name and price, or link the next page with <a rel="next">. A filter that drops items without a category or a photo hides them from shoppers.'
+    );
+    assertion(
+      count > 0,
+      "menu_mismatch",
+      `The ${label2} shows ${count} of ${available.length} available items`,
+      'Render every available item with a visible data-zappie-item marker that contains its name and price, or link the next page with <a rel="next">. If each menu has its own page, set verify.cataloguePath, such as /menu?menu={menu}.'
+    );
+    assertion(
+      first.next !== void 0 || first.loadMore,
+      "menu_mismatch",
+      `The ${label2} shows ${count} of ${available.length} available items and links to no next page`,
+      'Render every available item, or link the next page with <a rel="next">. A filter that drops items without a category or a photo hides them from shoppers.'
+    );
+    const least = Math.min(available.length, MIN_PAGE_ITEMS);
+    assertion(
+      count >= least,
+      "menu_mismatch",
+      `The ${label2} shows ${count} of ${available.length} available items on its first page. A page shows at least ${least}`,
+      `Show at least ${MIN_PAGE_ITEMS} items on each page of the catalogue, or every item when there are fewer.`
+    );
+    paginated = true;
+    let next;
+    if (first.next !== void 0) {
+      details.pageLoads++;
+      next = await site.open(first.next);
+      details.nextPage = "link";
+    } else {
+      next = await site.loadMore();
+      details.nextPage = "load-more";
+    }
+    const nextLabel = first.next === void 0 ? `${label2} after load more` : `next page of the ${label2} at ${first.next}`;
+    const more = await judgePage(next, input, nextLabel, cardLinks);
+    assertion(
+      available.some((item) => more.has(item.id) && !shown.has(item.id)),
+      "next_page_mismatch",
+      `The ${nextLabel} shows no available item the first page didn't`,
+      'Link the page that holds the next items with <a rel="next">, or make data-zappie-action="load-more" add them.'
+    );
+  }
+  if (sitemapPages && sitemapPages.size > 0) {
+    const missing = catalogue.filter((item) => !sitemapPages.has(item.id));
+    assertion(
+      missing.length === 0,
+      "sitemap_incomplete",
+      `The sitemap lists ${catalogue.length - missing.length} of ${catalogue.length} available items. Missing: ${listed(missing)}`,
+      "List a page for every available item in /sitemap.xml, as the starter's sitemap route does. A filter that drops an item from the sitemap usually hides it from shoppers too."
+    );
+  } else {
+    assertion(
+      !paginated || sitemapPaths !== void 0,
+      "sitemap_missing",
+      "The site serves no /sitemap.xml, so verify can't tell whether the catalogue shows every item beyond its first page",
+      "Serve /sitemap.xml with a page for every available item, as the starter's sitemap route does."
+    );
+    assertion(
+      !paginated,
+      "sitemap_missing",
+      "The sitemap lists no item pages, so verify can't tell whether the catalogue shows every item beyond its first page",
+      "List a page for every available item in /sitemap.xml, as the starter's sitemap route does."
+    );
+    const message = sitemapPaths ? "The sitemap lists no item pages, so verify can't tell whether the catalogue shows every item" : "The site serves no /sitemap.xml, so verify can't tell whether the catalogue shows every item";
+    input.warn?.("sitemap_missing", message);
+  }
+  const drawn = sample(catalogue, SAMPLE_SIZE, random);
+  for (const item of drawn) {
+    details.sampledItems.push(item.id);
+    const path4 = sitemapPages?.get(item.id) ?? cardLinks.get(item.id) ?? contractItemPath(item);
+    details.pageLoads++;
+    const opened = await site.itemPage(path4, item.name);
+    const page = { ...opened, text: normalizeText(opened.text) };
+    assertion(
+      page.status === 200,
+      "item_page_missing",
+      `The page of ${item.name} at ${path4} answered ${page.status}`,
+      "Serve each item's page at the path the sitemap lists, or at /item/{id}, with a 200 response."
+    );
+    assertion(
+      nameMatches(page.text, item.name),
+      "item_page_mismatch",
+      `The page at ${path4} does not show ${item.name}`,
+      "Show the item's name on its own page."
+    );
     const prices = shownPrices(item);
     assertion(
-      prices.some((price) => priceMatches(text, normalizeText(price))),
+      prices.some((price) => priceMatches(page.text, normalizeText(price))),
       "price_mismatch",
-      `${item.name} does not show ${prices.join(" or From ")}`,
+      `The page of ${item.name} at ${path4} does not show ${prices.join(" or From ")}`,
       "Render prices with format.money from @zappie/sdk, and a From price with startingPrice from @zappie/sdk/pricing."
     );
   }
-  const coverage = menuCoverage(items, shownIds);
-  assertion(
-    coverage.passes || severalMenus,
-    "menu_mismatch",
-    `The ${menuName} shows ${coverage.shown} of ${coverage.available} available items`,
-    "Render at least 95% of available menu items with visible data-zappie-item markers that contain their name and price, or visible names when no marker exists."
-  );
-  assertion(
-    coverage.passes,
-    "menu_mismatch",
-    `The ${menuName} shows ${coverage.shown} of ${coverage.available} available items`,
-    "Render at least 95% of available menu items with visible data-zappie-item markers that contain their name and price, or visible names when no marker exists. If each menu has its own page, set verify.cataloguePath, such as /menu?menu={menu}."
-  );
-  assertion(
-    await page.locator("[data-zappie-item]").count(),
-    "item_marker_missing",
-    `The ${menuName} has no item marker`,
-    "Add data-zappie-item to each rendered menu item."
-  );
-  for (const item of items.filter((entry) => !entry.isAvailable)) {
-    const add = page.locator(
-      `[data-zappie-item="${item.id}"] [data-zappie-action="add-to-cart"]`
+  return details;
+}
+async function judgePage(page, input, label2, cardLinks) {
+  const shown = /* @__PURE__ */ new Set();
+  for (const view of page.cards) {
+    const card = { ...view, texts: view.texts.map(normalizeText) };
+    const item = input.items[card.id];
+    assertion(
+      item,
+      "unknown_item",
+      `The ${label2} shows data-zappie-item="${card.id}", which is not an item of this store${knownAs(card.id, input.items)}`,
+      "Render items from the menu @zappie/sdk returns, with their own ids in data-zappie-item. Remove demo and stale data."
     );
-    if (await add.count()) {
+    if (card.href !== void 0 && !cardLinks.has(item.id)) {
+      cardLinks.set(item.id, card.href);
+    }
+    const named = card.texts.filter((text) => nameMatches(text, item.name));
+    if (!item.isAvailable) {
       assertion(
-        await add.isDisabled(),
+        !card.addEnabled,
         "unavailable_item_addable",
         `Shoppers can add the unavailable item ${item.name}`,
         "Disable add-to-cart for unavailable items."
       );
+      assertion(
+        named.length === 0 || card.addDisabled || card.texts.some((text) => showsUnavailable(text, item)),
+        "unavailable_item_shown",
+        `The ${label2} shows ${item.name} for sale, but it is unavailable`,
+        "Hide unavailable items, or mark them sold out: a disabled add-to-cart, the item's stockLabel, or words such as Sold out."
+      );
+      continue;
     }
+    if (named.length === 0) {
+      continue;
+    }
+    const prices = shownPrices(item);
+    assertion(
+      named.some(
+        (text) => prices.some((price) => priceMatches(text, normalizeText(price)))
+      ),
+      "price_mismatch",
+      `${item.name} does not show ${prices.join(" or From ")}`,
+      "Render prices with format.money from @zappie/sdk, and a From price with startingPrice from @zappie/sdk/pricing."
+    );
+    shown.add(item.id);
   }
+  return shown;
+}
+function knownAs(id, items) {
+  const known = [`item_${id}`, id.replace(/^item_/, "")].find(
+    (candidate) => candidate !== id && items[candidate] !== void 0
+  );
+  return known ? `. The store's item is ${known}` : "";
+}
+function showsUnavailable(text, item) {
+  return item.stockLabel !== void 0 && text.includes(normalizeText(item.stockLabel)) || // Card text runs together, as in "₦7,500.00Sold out", so only letters bound the words.
+  /(?<![a-z])(?:sold[ -]?out|unavailable|out of stock|not available)(?![a-z])/.test(
+    text
+  );
+}
+function listed(items) {
+  const names = items.slice(0, 5).map((item) => `${item.name} (${item.id})`);
+  return items.length > 5 ? `${names.join(", ")} and ${items.length - 5} more` : names.join(", ");
 }
 function nameMatches(text, name) {
-  return text.includes(normalizeText(decodeBasicEntities(name)));
+  const shown = normalizeText(text);
+  return shown.includes(normalizeText(decodeBasicEntities(name))) || shown.includes(normalizeText(name));
 }
 function normalizeText(value) {
-  return value.normalize("NFKC").replace(/[\u00ad\u200b-\u200d\u2060\ufeff]/g, "").replace(/\s+/g, " ").trim().toLocaleLowerCase();
+  return value.normalize("NFKC").replace(/[­​-‍⁠]/g, "").replace(/\s+/g, " ").trim().toLocaleLowerCase();
 }
 function decodeBasicEntities(value) {
-  const entities = {
+  const entities2 = {
     amp: "&",
     apos: "'",
     gt: ">",
@@ -1833,78 +2102,234 @@ function decodeBasicEntities(value) {
   };
   return value.replace(
     /&(amp|apos|gt|lt|quot);/gi,
-    (entity) => entities[entity.slice(1, -1).toLowerCase()] ?? entity
+    (entity) => entities2[entity.slice(1, -1).toLowerCase()] ?? entity
   );
 }
-async function visibleMarkerText(marker) {
-  const text = await marker.evaluateAll(
-    (nodes) => nodes.flatMap((node) => {
-      for (let current = node; current; current = current.parentElement) {
-        const ariaHidden = current.getAttribute("aria-hidden")?.trim().toLowerCase();
-        const style = getComputedStyle(current);
-        if (current.hasAttribute("hidden") || ariaHidden === "true" || style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse" || style.contentVisibility === "hidden" || fullyClipped(current, style)) {
-          return [];
-        }
-      }
-      const hasBox = [...node.getClientRects()].some((box) => {
-        const documentRight = box.right + window.scrollX;
-        const documentBottom = box.bottom + window.scrollY;
-        return box.width >= 2 && box.height >= 2 && documentRight > 0 && documentBottom > 0;
+
+// src/checks/v03-menu.ts
+var RENDER_WAIT_MS = 1e4;
+var v03 = {
+  id: "V03",
+  title: "Menu matches store",
+  viewports: "mobile",
+  async run({ page, options, fault, warn, recordCatalogue }, viewport) {
+    const menu = await readMenu(options);
+    await page.setViewportSize(viewport);
+    const seed = sampleSeed(options.catalogueSeed);
+    const pages = cataloguePages(options, menu);
+    const severalMenus = !options.cataloguePath && pages[0]?.name === void 0 && catalogues(menu).length > 1;
+    await judgeCatalogue({
+      site: browserSite(page, options, fault),
+      items: menu.items,
+      catalogue: sellableItems(menu),
+      scopes: judgedScopes(pages, seed),
+      seed,
+      severalMenus,
+      warn,
+      ...recordCatalogue ? { record: recordCatalogue } : {}
+    });
+  }
+};
+function browserSite(page, options, fault) {
+  const read = () => page.evaluate(readPageView);
+  return {
+    async open(path4) {
+      await open(page, path4);
+      await page.locator("[data-zappie-item]").first().waitFor({ state: "attached", timeout: RENDER_WAIT_MS }).catch(() => void 0);
+      await applyPageFault(page, fault);
+      return read();
+    },
+    async loadMore() {
+      const before = await page.locator("[data-zappie-item]").count();
+      await page.locator('[data-zappie-action="load-more"]').filter({ visible: true }).first().click();
+      await page.waitForFunction(
+        (count) => document.querySelectorAll("[data-zappie-item]").length > count,
+        before,
+        { timeout: RENDER_WAIT_MS }
+      ).catch(() => void 0);
+      return read();
+    },
+    async itemPage(path4, name) {
+      const response = await page.goto(path4, {
+        waitUntil: "domcontentloaded"
       });
-      if (!hasBox) {
-        return [];
-      }
-      const text2 = node.textContent;
-      return text2 === null ? [] : [text2];
-      function fullyClipped(element, style) {
-        const box = element.getBoundingClientRect();
-        const clip = style.clip.match(
-          /^rect\((auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)\)$/
-        );
-        if (clip) {
-          const top2 = length(clip[1], 0);
-          const right2 = length(clip[2], box.width);
-          const bottom2 = length(clip[3], box.height);
-          const left2 = length(clip[4], 0);
-          if (right2 <= left2 || bottom2 <= top2) {
-            return true;
-          }
-        }
-        const clipPath = style.clipPath;
-        if (/^(circle|ellipse)\(0(?:px|%)?(?:\s|\))/i.test(clipPath)) {
+      await page.waitForFunction(
+        (wanted) => (document.body?.innerText ?? "").normalize("NFKC").replace(/[­​-‍⁠]/g, "").replace(/\s+/g, " ").toLocaleLowerCase().includes(wanted),
+        normalizeText(name),
+        { timeout: RENDER_WAIT_MS }
+      ).catch(() => void 0);
+      return {
+        status: response?.status() ?? 0,
+        text: await page.evaluate(() => document.body?.innerText ?? "")
+      };
+    },
+    async namesShown(names) {
+      for (const name of names) {
+        if (await page.getByText(name, { exact: true }).filter({ visible: true }).count() > 0) {
           return true;
         }
-        const inset = clipPath.match(/^inset\(([^)]+)\)/i);
-        if (!inset) {
-          return false;
-        }
-        const values = inset[1].split(/\s+/).slice(0, 4).map(
-          (value, index) => insetLength(value, index % 2 ? box.width : box.height)
-        );
-        if (values.some((value) => value === void 0)) {
-          return false;
-        }
-        const top = values[0];
-        const right = values.length === 1 ? top : values[1];
-        const bottom = values.length < 3 ? top : values[2];
-        const left = values.length < 4 ? right : values[3];
-        return top + bottom >= box.height || right + left >= box.width;
       }
-      function length(value, fallback) {
-        return value === "auto" || value === void 0 ? fallback : Number.parseFloat(value);
+      return false;
+    },
+    async fetchText(path4) {
+      const response = await page.request.get(new URL(path4, options.url).href);
+      return response.ok() ? response.text() : void 0;
+    }
+  };
+}
+function readPageView() {
+  const add = '[data-zappie-action="add-to-cart"]';
+  const sitePath = (href) => {
+    if (!href) {
+      return void 0;
+    }
+    try {
+      const url = new URL(href, location.href);
+      return url.origin === location.origin ? `${url.pathname}${url.search}` : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  const markers = [...document.querySelectorAll("[data-zappie-item]")];
+  const cards = /* @__PURE__ */ new Map();
+  for (const node of markers) {
+    if (!visible(node)) {
+      continue;
+    }
+    const id = node.getAttribute("data-zappie-item") ?? "";
+    const card = cards.get(id) ?? {
+      id,
+      texts: [],
+      addEnabled: false,
+      addDisabled: false
+    };
+    card.texts.push(node.textContent ?? "");
+    for (const control of [
+      ...node.matches(add) ? [node] : [],
+      ...node.querySelectorAll(add)
+    ]) {
+      const disabled = control.disabled === true || control.getAttribute("aria-disabled") === "true";
+      if (disabled) {
+        card.addDisabled = true;
+      } else {
+        card.addEnabled = true;
       }
-      function insetLength(value, dimension) {
-        if (value.endsWith("%")) {
-          return Number.parseFloat(value) / 100 * dimension;
-        }
-        if (value.endsWith("px") || value === "0") {
-          return Number.parseFloat(value);
-        }
-        return void 0;
+    }
+    if (card.href === void 0) {
+      const link = node.closest("a[href]") ?? node.querySelector("a[href]");
+      const href = sitePath(link?.getAttribute("href"));
+      if (href !== void 0) {
+        card.href = href;
       }
-    })
+    }
+    cards.set(id, card);
+  }
+  const nextLink = document.querySelector(
+    'a[rel~="next"][href], link[rel~="next"][href]'
+  );
+  const next = sitePath(nextLink?.getAttribute("href"));
+  const loadMore = [
+    ...document.querySelectorAll('[data-zappie-action="load-more"]')
+  ].some(
+    (control) => visible(control) && control.disabled !== true && control.getAttribute("aria-disabled") !== "true"
   );
-  return text.map(normalizeText);
+  return {
+    path: `${location.pathname}${location.search}`,
+    markers: markers.length,
+    cards: [...cards.values()],
+    ...next !== void 0 ? { next } : {},
+    loadMore
+  };
+  function visible(node) {
+    for (let current = node; current; current = current.parentElement) {
+      const ariaHidden = current.getAttribute("aria-hidden")?.trim().toLowerCase();
+      const style = getComputedStyle(current);
+      if (current.hasAttribute("hidden") || ariaHidden === "true" || style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse" || style.contentVisibility === "hidden" || fullyClipped(current, style)) {
+        return false;
+      }
+    }
+    return [...node.getClientRects()].some((box) => {
+      const documentRight = box.right + window.scrollX;
+      const documentBottom = box.bottom + window.scrollY;
+      return box.width >= 2 && box.height >= 2 && documentRight > 0 && documentBottom > 0;
+    });
+  }
+  function fullyClipped(element, style) {
+    const box = element.getBoundingClientRect();
+    const clip = style.clip.match(
+      /^rect\((auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)[, ]+(auto|-?[\d.]+px)\)$/
+    );
+    if (clip) {
+      const top2 = length(clip[1], 0);
+      const right2 = length(clip[2], box.width);
+      const bottom2 = length(clip[3], box.height);
+      const left2 = length(clip[4], 0);
+      if (right2 <= left2 || bottom2 <= top2) {
+        return true;
+      }
+    }
+    const clipPath = style.clipPath;
+    if (/^(circle|ellipse)\(0(?:px|%)?(?:\s|\))/i.test(clipPath)) {
+      return true;
+    }
+    const inset = clipPath.match(/^inset\(([^)]+)\)/i);
+    if (!inset) {
+      return false;
+    }
+    const values = inset[1].split(/\s+/).slice(0, 4).map(
+      (value, index) => insetLength(value, index % 2 ? box.width : box.height)
+    );
+    if (values.some((value) => value === void 0)) {
+      return false;
+    }
+    const top = values[0];
+    const right = values.length === 1 ? top : values[1];
+    const bottom = values.length < 3 ? top : values[2];
+    const left = values.length < 4 ? right : values[3];
+    return top + bottom >= box.height || right + left >= box.width;
+  }
+  function length(value, fallback) {
+    return value === "auto" || value === void 0 ? fallback : Number.parseFloat(value);
+  }
+  function insetLength(value, dimension) {
+    if (value.endsWith("%")) {
+      return Number.parseFloat(value) / 100 * dimension;
+    }
+    if (value.endsWith("px") || value === "0") {
+      return Number.parseFloat(value);
+    }
+    return void 0;
+  }
+}
+
+// src/checks/shown-item.ts
+async function findShownItem(page, candidates, prepare = async () => {
+}) {
+  const looked = [];
+  if (candidates.length === 0) {
+    return { looked };
+  }
+  const first = await readShown(page, candidates);
+  looked.push(first.path);
+  if (first.shown || first.next === void 0) {
+    return { ...first.shown ? { shown: first.shown } : {}, looked };
+  }
+  await open(page, first.next);
+  await prepare();
+  const second = await readShown(page, candidates);
+  looked.push(second.path);
+  return { ...second.shown ? { shown: second.shown } : {}, looked };
+}
+async function readShown(page, candidates) {
+  await page.locator("[data-zappie-item]").first().waitFor({ state: "attached", timeout: RENDER_WAIT_MS }).catch(() => void 0);
+  const view = await page.evaluate(readPageView);
+  const visible = new Set(view.cards.map((card) => card.id));
+  const item = view.markers === 0 ? candidates[0] : candidates.find((candidate) => visible.has(candidate.id));
+  return {
+    path: view.path,
+    next: view.next,
+    shown: item ? { item, path: view.path } : void 0
+  };
 }
 
 // src/checks/v04-add-simple.ts
@@ -1915,9 +2340,27 @@ var v04 = {
   async run({ page, options, fault }, viewport) {
     await page.setViewportSize(viewport);
     const menu = await readMenu(options);
-    const item = simpleItem(menu);
-    await open(page, itemPath(options, menu, item?.id));
+    const candidates = simpleItems(menu);
+    await open(page, itemPath(options, menu, candidates[0]?.id));
     await applyPageFault(page, fault);
+    assertion(
+      candidates.length > 0,
+      "simple_item_missing",
+      "The test menu has no available item without required options",
+      "Keep one available item without required options in the test menu."
+    );
+    const { shown, looked } = await findShownItem(
+      page,
+      candidates,
+      () => applyPageFault(page, fault)
+    );
+    assertion(
+      shown,
+      "simple_item_not_shown",
+      `No available item without required options shows on ${looked.join(" or ")}`,
+      'Show an available item without required options on the first catalogue page, or on the page its rel="next" link opens.'
+    );
+    const item = shown.item;
     const before = await debugValue(page, () => window.__zappie.cart().count);
     await page.evaluate(() => {
       window.__zappieV04Events = [];
@@ -1927,12 +2370,6 @@ var v04 = {
         );
       });
     });
-    assertion(
-      item,
-      "simple_item_missing",
-      "The test menu has no available item without required options",
-      "Keep one available item without required options in the test menu."
-    );
     let openedItem = false;
     let simple = page.locator(`[data-zappie-item="${item.id}"]`).locator('[data-zappie-action="add-to-cart"]');
     if (!await simple.count()) {
@@ -2004,14 +2441,22 @@ var v05 = {
   async run({ page, options }, viewport) {
     await page.setViewportSize(viewport);
     const menu = await readMenu(options);
-    const selected = configurableItem(menu);
-    await open(page, itemPath(options, menu, selected?.id));
+    const candidates = configurableItems(menu);
+    await open(page, itemPath(options, menu, candidates[0]?.id));
     assertion(
-      selected,
+      candidates.length > 0,
       "required_item_missing",
       "The test menu has no available item with required options",
       "Keep one available configurable item in the test menu."
     );
+    const { shown, looked } = await findShownItem(page, candidates);
+    assertion(
+      shown,
+      "required_item_not_shown",
+      `No available item with required options shows on ${looked.join(" or ")}`,
+      'Show an available item with required options on the first catalogue page, or on the page its rel="next" link opens.'
+    );
+    const selected = shown.item;
     await openItem(page, selected.id);
     const dialog = page.getByRole("dialog");
     await dialog.waitFor();
@@ -2915,8 +3360,8 @@ var v13 = {
       page: true,
       phone: viewport.width < 768
     });
-    const item = sortedItems(menu).find((entry) => entry.isAvailable);
-    const itemPage = itemPath(options, menu, item?.id);
+    const available = sortedItems(menu).filter((entry) => entry.isAvailable);
+    const itemPage = itemPath(options, menu, available[0]?.id);
     if (itemPage !== start) {
       await open(page, itemPage);
       await applyPageFault(page, fault);
@@ -2929,11 +3374,23 @@ var v13 = {
       );
     }
     assertion(
-      item,
+      available.length > 0,
       "available_item_missing",
       "No available item can be opened for accessibility checks",
       "Keep one available item in the test menu."
     );
+    const { shown, looked } = await findShownItem(
+      page,
+      available,
+      () => applyPageFault(page, fault)
+    );
+    assertion(
+      shown,
+      "available_item_not_shown",
+      `No available item shows on ${looked.join(" or ")}`,
+      'Show an available item on the first catalogue page, or on the page its rel="next" link opens.'
+    );
+    const item = shown.item;
     const { focusTarget: card } = await openItem(page, item.id);
     violations.push(...await severeViolations(page));
     semantics.push(
@@ -2995,9 +3452,11 @@ var v13 = {
       order.map((entry) => entry.id).join(", ") || "Order page has a serious axe violation",
       "Fix serious and critical axe findings on the order page."
     );
-    const simple = simpleItem(menu)?.id;
-    const simplePage = itemPath(options, menu, simple);
-    await open(page, simplePage);
+    const simples = simpleItems(menu);
+    await open(page, itemPath(options, menu, simples[0]?.id));
+    const simpleShown = (await findShownItem(page, simples)).shown;
+    const simple = simpleShown?.item.id ?? simples[0]?.id;
+    const simplePage = simpleShown?.path ?? itemPath(options, menu, simple);
     assertion(
       await keyboardReachesAddAndCart(page, simple, simplePage, cartInColumn),
       "keyboard_marker_unreachable",
@@ -3204,12 +3663,21 @@ async function revealBagTrigger(page, start, item) {
   if (!item || await bag.count()) {
     return;
   }
-  const itemId = item.id;
-  const marked = page.locator(`[data-zappie-item="${itemId}"]`);
+  const marked = page.locator(
+    item.ids.map((id) => `[data-zappie-item="${id}"]`).join(", ")
+  );
   if (item.path !== start && !await marked.count()) {
     await page.goto(item.path, { waitUntil: "domcontentloaded" });
     await marked.first().waitFor({ timeout: 5e3 }).catch(() => void 0);
   }
+  const found = await findShownItem(
+    page,
+    item.ids.map((id) => ({ id }))
+  ).catch(() => void 0);
+  const itemId = found?.shown?.item.id;
+  if (itemId === void 0) {
+    return;
+  }
   const before = await page.evaluate(() => window.__zappie?.cart().count ?? 0).catch(() => 0);
   const add = '[data-zappie-action="add-to-cart"]';
   const quick = page.locator(`[data-zappie-item="${itemId}"] ${add}`).filter({ visible: true }).first();
@@ -3241,10 +3709,10 @@ async function revealBagTrigger(page, start, item) {
   await bag.waitFor({ timeout: 5e3 }).catch(() => void 0);
 }
 function bagItem(options, menu) {
-  const id = simpleItem(menu)?.id;
+  const ids = simpleItems(menu).map((entry) => entry.id);
   return {
     start: startPath(options),
-    item: id ? { id, path: itemPath(options, menu, id) } : void 0
+    item: ids.length ? { ids, path: itemPath(options, menu, ids[0]) } : void 0
   };
 }
 
@@ -3549,7 +4017,7 @@ var v16 = {
       const opens = [];
       const opensRates = [];
       let opened = true;
-      for (let sample = 0; sample < OVERLAY_OPEN_SAMPLES && undecided(opens); sample++) {
+      for (let sample2 = 0; sample2 < OVERLAY_OPEN_SAMPLES && undecided(opens); sample2++) {
         const open2 = await firstOpen(
           await freshPage(),
           viewport,
@@ -3980,7 +4448,7 @@ async function reset(options) {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = true ? "0.3.3" : "0.0.0-development";
+var PACKAGE_VERSION = true ? "0.3.5" : "0.0.0-development";
 
 // src/runner.ts
 var VERSION = PACKAGE_VERSION;
@@ -4006,10 +4474,14 @@ async function execute(check, run2) {
   const started = performance.now();
   const viewports = selectedViewports(check, run2.options);
   const warnings = /* @__PURE__ */ new Map();
+  let catalogue;
   const checkRun = {
     ...run2,
     warn(code, message) {
       warnings.set(code, message);
+    },
+    recordCatalogue(details) {
+      catalogue = details;
     }
   };
   let retried = false;
@@ -4034,7 +4506,8 @@ async function execute(check, run2) {
           code,
           message
         }))
-      } : {}
+      } : {},
+      ...catalogue ? { catalogue } : {}
     };
   } catch (failure) {
     const error = failure instanceof VerifyError ? { code: failure.code, message: failure.message, hint: failure.hint } : {
@@ -4069,7 +4542,8 @@ async function execute(check, run2) {
       viewport: viewports.map(label).join(","),
       ...retried ? { retried } : {},
       error,
-      artifacts: { screenshot, trace }
+      artifacts: { screenshot, trace },
+      ...catalogue ? { catalogue } : {}
     };
   }
 }
@@ -4241,6 +4715,7 @@ async function verifyProject(options) {
       ...startPath2 !== void 0 ? { startPath: startPath2 } : {},
       ...cataloguePath !== void 0 ? { cataloguePath } : {},
       ...tappableMs !== void 0 ? { tappableMs } : {},
+      ...options.catalogueSeed !== void 0 ? { catalogueSeed: options.catalogueSeed } : {},
       ...warnings.length ? { warnings } : {},
       ...options.viewports ? { viewports: options.viewports } : {},
       ...options.artifactsDir ? { artifactsDir: options.artifactsDir } : {},