@tokenoftrust/storefront-runner 2.5.6 → 3.0.0

package/apps/storefront/src/pages/collections/_CollectionView.astro

@@ -0,0 +1,251 @@
+---
+/**
+ * PLP / collection view (brief §5), shared by `/collections/<h>/` (page 1) and
+ * `/collections/<h>/page/<n>/` so the two can't drift. Responsive grid,
+ * collection hero, sort, URL-addressable facets, numbered pagination + load-more.
+ * Hero copy from the collection record (Storyblok could override later —
+ * documented seam).
+ *
+ * The rendered results carry the key of the query they applied
+ * (`data-applied-query`). A static host serves this page for any query, so
+ * `CatalogQueryView` re-applies the URL's own query client-side whenever it
+ * differs from that key (lib/publication/shared/staticQuery.ts).
+ */
+import type { ListProductsQuery, ListProductsResponse, CatalogCollection } from "@tot/public-runtime";
+import Layout from "@/layouts/Layout.astro";
+import Breadcrumbs from "@/components/content/storefront/Breadcrumbs.astro";
+import { homeCrumbLabel, siteTrail } from "@/lib/content/shared/breadcrumbs";
+import ProductCard from "@/components/catalog/storefront/ProductCard.astro";
+import EmptyState from "@/components/content/storefront/EmptyState.astro";
+import FacetSidebar from "@/components/catalog/storefront/plp/FacetSidebar.astro";
+import ActiveFilters from "@/components/catalog/storefront/plp/ActiveFilters.astro";
+import SortSelect from "@/components/catalog/storefront/plp/SortSelect.astro";
+import Pagination from "@/components/catalog/storefront/plp/Pagination.astro";
+import CatalogQueryView from "@/components/publication/storefront/islands/CatalogQueryView.tsx";
+import Img from "@/components/assets/storefront/Img.astro";
+import { buildQueryString } from "@/lib/publication/shared/url";
+import { collectionPageCount, collectionPagePath, isPathPageable } from "@/lib/catalog/shared/collectionPaging";
+import { listQueryKey } from "@/lib/publication/shared/staticQuery";
+import { breadcrumbLd, itemListLd } from "@/lib/content/shared/jsonld";
+import { truncate } from "@/lib/content/shared/format";
+import { pageUrlForm } from "@/lib/content/seo/urlForm";
+import { sourceSeoTitle } from "@/lib/content/seo/documentTitle";
+import { withBase } from "@/lib/publication/shared/basePath";
+import { isBlankDescriptionHtml, sanitizeDescriptionHtml } from "@/lib/content/sanitizeDescriptionHtml";
+
+interface Props {
+  collection: CatalogCollection;
+  query: ListProductsQuery;
+  result: ListProductsResponse;
+  memberTotal: number;
+  /** The page the route's PATH names (1 for the bare collection path). */
+  pathPage: number;
+}
+
+const { collection, query, result, memberTotal, pathPage } = Astro.props;
+const { tenant, canonicalBase } = Astro.locals;
+const { handle } = collection;
+const { products, page, pageSize, total, facets } = result;
+
+// A synthesized-EMPTY collection (zero active members overall — not merely
+// zero under the current facet/price/q filters) still resolves 200 for a direct
+// link, but must not be indexed: it's a crawlable dead end, kept out of the
+// sitemap + directory too. Detect it via the UNFILTERED membership total.
+const isEmptyCollection = memberTotal === 0;
+const basePath = pageUrlForm(collectionPagePath(handle, 1), tenant.seo);
+// Tenant-prefixed page path for facet/sort/pagination, which build links by
+// string-concatenating onto this base (so they stay inside a path-routed
+// tenant). `basePath` itself stays unprefixed for the SEO canonical `path`,
+// breadcrumbs, and EmptyState — those prefix on their own via withBase.
+const linkBase = withBase(Astro.locals.basePath, basePath);
+
+// Page N of the default view is its own indexable path variant; every other view
+// keeps its query (noindex territory) and canonicalizes to the collection.
+const pathPaged = isPathPageable(query);
+const pagePath = (n: number) => pageUrlForm(collectionPagePath(handle, n), tenant.seo);
+const pageCount = collectionPageCount(total, pageSize);
+const path = pathPaged ? pagePath(page) : basePath;
+const pagination = pathPaged
+  ? {
+      ...(page > 1 ? { prev: pagePath(page - 1) } : {}),
+      ...(page < pageCount ? { next: pagePath(page + 1) } : {}),
+    }
+  : undefined;
+const pageHref = pathPaged ? (n: number) => withBase(Astro.locals.basePath, pagePath(n)) : undefined;
+
+const crumbs = siteTrail(
+  homeCrumbLabel(await Astro.locals.content.getChrome()),
+  { label: collection.title, href: basePath },
+);
+
+const heroImg = collection.image;
+const desc = collection.description_text || collection.description_html?.replace(/<[^>]+>/g, "");
+// Full-fidelity body (brands/how-it-works/ingredients/FAQ sections on the merchant's
+// live collection pages), sanitized for render-time defense-in-depth on top of the
+// migration pipeline's own sanitize-html pass at ingestion (see
+// sanitizeDescriptionHtml.ts). Rendered as its own block BELOW the product grid,
+// matching the live site's layout — `desc` above stays the short hero excerpt.
+const contentBlockHtml = sanitizeDescriptionHtml(collection.description_html);
+const hasContentBlock = contentBlockHtml.length > 0 && !isBlankDescriptionHtml(contentBlockHtml);
+
+// Zero-results recovery: differentiate the cause (search term vs. facet/price
+// filters) and offer targeted "undo just this" links alongside the existing
+// "clear everything" CTA, instead of one generic message + one broad reset.
+const hasFacetOrPriceFilters =
+  !!query.filters ||
+  query.priceMin != null ||
+  query.priceMax != null ||
+  query.availability === "in-stock";
+const zeroResultsTitle = query.q ? `No matches for "${query.q}"` : "Nothing matches — yet";
+const zeroResultsBody = query.q
+  ? "Try a broader search term, or clear your filters to browse the full collection."
+  : "No pieces fit these filters. Loosen a filter or clear them to see the full collection.";
+const zeroResultsActions: { label: string; href: string }[] = [];
+if (query.q && hasFacetOrPriceFilters) {
+  const { q: _q, ...rest } = query;
+  zeroResultsActions.push({ label: "Clear search, keep filters", href: basePath + buildQueryString(rest) });
+}
+if (query.priceMin != null || query.priceMax != null) {
+  const { priceMin: _priceMin, priceMax: _priceMax, ...rest } = query;
+  zeroResultsActions.push({ label: "Remove price range", href: basePath + buildQueryString(rest) });
+}
+
+const baseTitle = collection.seo.title || collection.title;
+const documentTitle = pathPaged && page > 1 ? `${baseTitle} — Page ${page}` : baseTitle;
+const seoTitle = sourceSeoTitle(tenant.seo, collection.seo.title);
+---
+
+<Layout
+  title={documentTitle}
+  seoTitle={seoTitle && pathPaged && page > 1 ? `${seoTitle} — Page ${page}` : seoTitle}
+  description={collection.seo.description || (desc ? truncate(desc, 160) : `Shop ${collection.title} at ${tenant.displayName}.`)}
+  path={path}
+  noindex={isEmptyCollection}
+  pagination={pagination}
+  jsonLd={[
+    breadcrumbLd(crumbs, canonicalBase),
+    itemListLd(products, canonicalBase, (page - 1) * pageSize),
+  ]}
+  structuredData={{
+    pageType: "collection",
+    description: collection.seo.description || undefined,
+    crumbs,
+    items: products.map((p) => ({ title: p.title, url: new URL(`/products/${p.handle}`, canonicalBase + "/").toString() })),
+  }}
+>
+  {/* Collection hero */}
+  <header class="bg-[var(--color-primary)] text-[var(--color-primary-contrast)]">
+    <div class="container-prose grid gap-6 py-[clamp(2.5rem,6vw,4.5rem)] md:grid-cols-[1fr_auto] md:items-end">
+      <div data-reveal>
+        <p class="eyebrow mb-3 text-[color-mix(in_srgb,var(--color-primary-contrast)_70%,transparent)]">
+          Collection
+        </p>
+        <h1 class="display-xl">
+          {collection.title}
+        </h1>
+        {desc && (
+          <p class="mt-4 max-w-prose text-[1.05rem] text-[color-mix(in_srgb,var(--color-primary-contrast)_82%,transparent)]">
+            {truncate(desc, 220)}
+          </p>
+        )}
+      </div>
+      {heroImg && (
+        <div class="hidden w-48 overflow-hidden rounded-[var(--radius-md)] md:block" data-reveal>
+          <Img
+            src={heroImg.url}
+            rehosted={heroImg.rehosted}
+            seed={heroImg.id ?? collection.handle}
+            label={collection.title}
+            alt={heroImg.alt ?? collection.title}
+            width={heroImg.width ?? 400}
+            height={heroImg.height ?? 300}
+          />
+        </div>
+      )}
+    </div>
+  </header>
+
+  <div class="container-prose py-4">
+    <Breadcrumbs crumbs={crumbs} />
+  </div>
+
+  <div
+    class="container-prose grid gap-10 pb-16 lg:grid-cols-[230px_1fr]"
+    data-catalog-query-rendered
+    data-applied-query={listQueryKey(query)}
+  >
+    {/* Facets — sticky on desktop; a <details> drawer on mobile. */}
+    <div class="lg:sticky lg:top-24 lg:self-start">
+      <details class="lg:hidden">
+        <summary class="cursor-pointer rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-2.5 font-display text-sm font-medium">
+          Filters & sort
+        </summary>
+        <div class="mt-4">
+          <FacetSidebar facets={facets} query={query} basePath={linkBase} />
+        </div>
+      </details>
+      <div class="hidden lg:block">
+        <FacetSidebar facets={facets} query={query} basePath={linkBase} />
+      </div>
+    </div>
+
+    <div>
+      <div class="mb-5 flex flex-wrap items-center justify-between gap-3 border-b border-[var(--color-border)] pb-4">
+        <p class="text-sm text-[var(--color-muted)]">
+          {total} {total === 1 ? "item" : "items"}
+        </p>
+        <SortSelect query={query} basePath={linkBase} />
+      </div>
+
+      <ActiveFilters query={query} basePath={linkBase} />
+
+      {products.length === 0 ? (
+        <EmptyState
+          title={zeroResultsTitle}
+          body={zeroResultsBody}
+          ctaLabel="Clear all filters"
+          ctaHref={basePath}
+          secondaryActions={zeroResultsActions}
+        />
+      ) : (
+        <>
+          <div class="grid grid-cols-2 gap-5 sm:grid-cols-2 lg:grid-cols-3">
+            {products.map((p, i) => (
+              <ProductCard
+                product={p}
+                position={(page - 1) * pageSize + i}
+                list={collection.handle}
+                priority={i < 3 && page === 1}
+              />
+            ))}
+          </div>
+          <Pagination
+            query={query}
+            basePath={linkBase}
+            page={page}
+            pageSize={pageSize}
+            total={total}
+            pageHref={pageHref}
+          />
+        </>
+      )}
+    </div>
+  </div>
+
+  <CatalogQueryView
+    client:only="preact"
+    mode="collection"
+    collection={handle}
+    pathPage={pathPage}
+    linkBase={linkBase}
+    pageBase={withBase(Astro.locals.basePath, collectionPagePath(handle, 1))}
+    trailingSlash={!!tenant.seo?.trailingSlash}
+    locale={tenant.locale}
+  />
+
+  {hasContentBlock && (
+    <section class="container-prose pb-16">
+      <div class="rte mx-auto max-w-[68ch] text-[var(--color-text)]" set:html={contentBlockHtml} />
+    </section>
+  )}
+</Layout>

package/apps/storefront/src/pages/collections/index.astro

@@ -34,7 +34,7 @@ const crumbs = siteTrail(
   description={`Browse every collection at ${tenant.displayName}.`}
   path="/collections"
   jsonLd={breadcrumbLd(crumbs, canonicalBase)}
-  structuredData={{ pageType: "collection" }}
+  structuredData={{ pageType: "collection", crumbs }}
 >
   <div class="container-prose pt-6">
     <Breadcrumbs crumbs={crumbs} />

package/apps/storefront/src/pages/products/[handle].astro

@@ -44,6 +44,7 @@ import type {
 import { resolveCartSigning, shopperCheckoutUnavailableHtml } from "@/lib/checkout/shared/checkoutCommerce";
 import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
 import { isRegulatedTenant } from "@/lib/compliance/enforcement";
+import { checkoutComplianceGateRequired } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { resolveMemberContext } from "@/lib/membership/eligibility";
 import { truncate } from "@/lib/content/shared/format";
 import { productLd, breadcrumbLd, reviewLd } from "@/lib/content/shared/jsonld";
@@ -232,12 +233,14 @@ const cartApiPath = workerCartApiPath({
 let checkoutCart:
   | {
       action: string;
+      method: "get" | "post";
       purchaseOptions: ProductPurchaseOption[];
       byVariantId: Record<string, Record<string, VariantCartPayload>>;
     }
   | undefined;
 let checkoutUnavailable = false;
 const sampleHandoff = isLocalSampleCheckout(tenant.tenant_id);
+const complianceGateRequired = await checkoutComplianceGateRequired(tenant, commerce, Astro.locals.customizationEnv);
 if (commerce || sampleHandoff) {
   // Fail closed for production signed checkout: a signed tenant with no
   // cart-validation secret builds NO cart (never a tamperable form). See
@@ -265,6 +268,7 @@ if (commerce || sampleHandoff) {
                     pricing: pricingCtx,
                     autopilotEnabled,
                     tenantId: commerceTenantId(tenant),
+                    currency: tenant.currency,
                   }),
                 ] as const;
               }),
@@ -275,6 +279,7 @@ if (commerce || sampleHandoff) {
       );
       checkoutCart = {
         action: sampleHandoff ? SAMPLE_CART_HANDOFF_URL : cartApiPath,
+        method: sampleHandoff ? "get" : "post",
         purchaseOptions,
         byVariantId: Object.fromEntries(entries),
       };
@@ -354,8 +359,8 @@ const structuredData = {
     {/* Buy column */}
     <div class="md:pt-2">
       <div class="flex flex-wrap items-center gap-2">
-        {onSale && <Badge variant="sale" label="Sale" />}
-        {!onSale && isNew(product) && <Badge variant="new" label="New" />}
+        {Astro.locals.features.productBadges && onSale && <Badge variant="sale" label="Sale" />}
+        {Astro.locals.features.productBadges && !onSale && isNew(product) && <Badge variant="new" label="New" />}
         {!available && <Badge variant="soldout" label="Sold out" />}
       </div>
 
@@ -429,9 +434,9 @@ const structuredData = {
         />
         {/* Regulated-tenant checkout ENFORCEMENT gate. Intercepts the
             managed-cart handoff to clear age + ship-to compliance server-side
-            before the external checkout. Only mounts when a store is wired AND
-            the tenant is regulated. */}
-        {checkoutCart && !sampleHandoff && isRegulatedTenant(tenant) && compliance?.minAge && (
+            before the external checkout. Only mounts when a store is wired, the
+            tenant is regulated, and that store's policy requires a check. */}
+        {checkoutCart && !sampleHandoff && isRegulatedTenant(tenant) && compliance?.minAge && complianceGateRequired && (
           <CheckoutComplianceGate
             client:load
             preflightUrl={withBase(apiBasePath, "/api/compliance/preflight")}

package/apps/storefront/src/pages/search.astro

@@ -1,13 +1,15 @@
 ---
 /**
- * /search — dual-purpose route (brief §5 Search).
+ * /search — the full results page: a no-JS <form>, the echoed query, a result
+ * count, and a product grid. Search runs through the ToTClient (D1 FTS5 when
+ * bound, else a Fuse index over the snapshot) over ACTIVE products only (drafts
+ * never surface). Results pages are `noindex` (standard practice — thin,
+ * parameterized, duplicative).
  *
- * 1. `?format=json` — returns `{ products: TypeaheadDoc[] }` for the header
- *    typeahead island. Search runs through the ToTClient (D1 FTS5 when bound, else
- *    a Fuse index over the snapshot) over ACTIVE products only (drafts never surface).
- * 2. Otherwise — the full results page: a no-JS <form>, the echoed query, a
- *    result count, and a product grid. Results pages are `noindex` (standard
- *    practice — thin, parameterized, duplicative).
+ * A static host serves this page without its `?q=`, so the rendered results
+ * carry the query they applied (`data-applied-query`) and CatalogQueryView
+ * searches the static catalog index in the browser whenever the URL asks for a
+ * different one. The header typeahead searches that same index.
  */
 import Layout from "@/layouts/Layout.astro";
 import Breadcrumbs from "@/components/content/storefront/Breadcrumbs.astro";
@@ -15,32 +17,21 @@ import { homeCrumbLabel, siteTrail } from "@/lib/content/shared/breadcrumbs";
 import ProductCard from "@/components/catalog/storefront/ProductCard.astro";
 import EmptyState from "@/components/content/storefront/EmptyState.astro";
 import Section from "@/components/content/storefront/Section.astro";
-import { toTypeaheadDoc } from "@/lib/catalog/search/index";
+import CatalogQueryView from "@/components/publication/storefront/islands/CatalogQueryView.tsx";
+import { SEARCH_RESULT_LIMIT } from "@/lib/catalog/shared/catalogQueryView";
+import { searchQueryFromUrl } from "@/lib/publication/shared/staticQuery";
 import { breadcrumbLd } from "@/lib/content/shared/jsonld";
 import { withBase } from "@/lib/publication/shared/basePath";
 
+// `?q=` never reaches a renderer on a static host: CatalogQueryView applies it there.
+export const STATIC_QUERY = "client-applied";
+
 const { tenant, tot, canonicalBase, basePath } = Astro.locals;
-// Commerce-only route (page + typeahead JSON): off for marketing tenants.
+// Commerce-only route: off for marketing tenants.
 if (!Astro.locals.features.productSearch) return new Response(null, { status: 404 });
-const url = new URL(Astro.request.url);
-const q = (url.searchParams.get("q") ?? "").trim();
-const isJson = url.searchParams.get("format") === "json";
-
-// Search goes through the ToTClient: D1 FTS5 when a D1 binding is wired, else a
-// Fuse index over the bundled snapshot (FixtureToTClient). It returns full
-// products, so the HTML grid renders directly and the typeahead just projects to
-// the compact shape.
-
-// --- JSON path: powers the header typeahead island. Must return BEFORE render.
-if (isJson) {
-  const docs = (await tot.search(q, 8)).map(toTypeaheadDoc);
-  return new Response(JSON.stringify({ products: docs }), {
-    headers: { "content-type": "application/json" },
-  });
-}
+const q = searchQueryFromUrl(Astro.url);
 
-// --- HTML path.
-const results = q ? await tot.search(q, 24) : [];
+const results = q ? await tot.search(q, SEARCH_RESULT_LIMIT) : [];
 const featured = q ? [] : await tot.getFeatured(8);
 
 const crumbs = siteTrail(
@@ -63,7 +54,7 @@ const crumbs = siteTrail(
   {/* Search hero + no-JS form (works without the island). */}
   <header class="container-prose pb-2 pt-8">
     <p class="eyebrow eyebrow--tick mb-3">Search</p>
-    <h1 class="display-xl">
+    <h1 class="display-xl" data-search-heading>
       {q ? <>Results for “{q}”</> : "What are you after?"}
     </h1>
     <form
@@ -103,13 +94,14 @@ const crumbs = siteTrail(
         Search
       </button>
     </form>
-    {q && (
-      <p class="mt-4 text-sm text-[var(--color-muted)]">
-        {results.length} {results.length === 1 ? "result" : "results"}
-      </p>
-    )}
   </header>
 
+  <div data-catalog-query-rendered data-applied-query={q}>
+  {q && (
+    <p class="container-prose mt-4 text-sm text-[var(--color-muted)]">
+      {results.length} {results.length === 1 ? "result" : "results"}
+    </p>
+  )}
   {q ? (
     results.length === 0 ? (
       <EmptyState
@@ -148,4 +140,12 @@ const crumbs = siteTrail(
       )}
     </>
   )}
+  </div>
+
+  <CatalogQueryView
+    client:only="preact"
+    mode="search"
+    trailingSlash={!!tenant.seo?.trailingSlash}
+    locale={tenant.locale}
+  />
 </Layout>

package/apps/storefront/src/pages/sitemap.xml.ts

@@ -9,7 +9,8 @@
  * loc is prefix-correct without special-casing here.
  */
 import type { APIContext } from "astro";
-import { nonEmptyCollections } from "@/lib/catalog/tot/query.js";
+import { activeMemberCount, nonEmptyCollections } from "@/lib/catalog/tot/query.js";
+import { collectionPageCount, collectionPagePath } from "@/lib/catalog/shared/collectionPaging.js";
 import { getBlogSettings, listBlogPosts } from "@/lib/content/blog/provider.js";
 import { authorSlug, categorySlug } from "@/lib/content/blog/collection.js";
 import { resolveBlogIndexCopy } from "@/lib/content/blog/pagination.js";
@@ -64,6 +65,11 @@ export async function GET(context: APIContext): Promise<Response> {
     urls.push({ loc: `${base}/collections` });
     for (const c of collections) {
       urls.push({ loc: `${base}/collections/${c.handle}` });
+      // Paginated pages (N≥2), same reasoning as /blog/page/N/ below: listing them
+      // is what makes every product of a large collection reachable on both
+      // serving planes, which publish one document per path.
+      const pages = collectionPageCount(activeMemberCount(c, products));
+      for (let n = 2; n <= pages; n++) urls.push({ loc: `${base}${collectionPagePath(c.handle, n)}` });
     }
     for (const p of products) {
       const entry: SitemapUrl = { loc: `${base}/products/${p.handle}` };

package/apps/storefront/vitest.config.cts

@@ -31,5 +31,8 @@ module.exports = defineConfig({
     include: ["src/**/*.test.ts", "e2e/a11y/**/*.test.ts"],
     environment: "node",
     cache: false,
+    // Folds and CI run many suites at once; a fixture-heavy test that takes 2s alone can pass 5s
+    // under that load. A genuinely hung test still fails, only later.
+    testTimeout: 30_000,
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.5.6",
+  "version": "3.0.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",