@tokenoftrust/storefront-runner 4.6.4 → 4.7.1

package/agency-kit/tools/lib/page-slugs.mjs

@@ -0,0 +1,113 @@
+// @ts-check
+/**
+ * Which editorial page slugs the hosted storefront router can serve.
+ *
+ * A page under `content/pages/<file>.json` is served at `/<slug>/`, where `<slug>` is the page's
+ * own JSON `slug` (never the file name), and a raw page `content/pages-html/<path>.html` is served
+ * at `/<path>/`. Both reach the platform's catch-all route, which every first-class platform route
+ * outranks. So a slug is servable only when:
+ *
+ *   - it is a string of one or more `/`-separated segments, each starting with a letter or digit
+ *     and holding only letters, digits, `-` and `_` (no leading/trailing or doubled slash, no `.`:
+ *     both CDNs treat a dotted last segment as a file, never a page);
+ *   - its first segment is not a route root the platform owns (`products`, `collections`, `blog`,
+ *     `api`, …) — the platform route answers first and the page is never reached;
+ *   - no other page, JSON or raw, claims the same slug — the router serves one of them.
+ *
+ * Pure: callers pass what they read, so the kit validator and `tot validate` apply one rule.
+ * `packages/cli/src/page-slugs.mjs` is a byte-identical copy (a test pins it).
+ */
+
+/**
+ * First path segments the platform's own routes answer before the editorial catch-all.
+ * Pinned against the storefront's route tree by scripts/lib/page-slug-reserved.test.mjs.
+ */
+export const RESERVED_PAGE_ROOTS = Object.freeze([
+  "_sitemap",
+  "account",
+  "admin",
+  "api",
+  "auth",
+  "blog",
+  "capabilities",
+  "cart",
+  "cockpit",
+  "collections",
+  "dashboard",
+  "diag",
+  "preview",
+  "products",
+  "saved",
+  "search",
+  "shared",
+  "style-guide",
+  "tenants",
+  "the-build",
+]);
+
+const SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Why `slug` cannot be served by the hosted router, or null when it can.
+ * @param {unknown} slug
+ * @returns {string | null}
+ */
+export function unservableSlugReason(slug) {
+  if (typeof slug !== "string" || slug.length === 0) return "has no string `slug`";
+  const segments = slug.split("/");
+  if (segments.some((segment) => !SEGMENT_RE.test(segment))) {
+    return `slug "${slug}" is not a page path: each "/"-separated segment must start with a letter or digit and hold only letters, digits, "-" and "_" (no leading, trailing or doubled "/", no ".")`;
+  }
+  const root = /** @type {string} */ (segments[0]);
+  if (RESERVED_PAGE_ROOTS.includes(root)) {
+    return `slug "${slug}" starts with "${root}/", a route the platform serves itself — the page is never reached`;
+  }
+  return null;
+}
+
+/**
+ * @typedef {Object} PageSlugFinding
+ * @property {string} code     `page-slug-unservable` | `page-slug-duplicate`
+ * @property {string} path     the declaring file, store-relative
+ * @property {string} message
+ * @property {string} remedy
+ */
+
+/**
+ * Every slug the hosted router cannot serve, across a store's JSON and raw pages.
+ * @param {{ pages?: ReadonlyArray<{ path: string, slug: unknown }>, rawPages?: ReadonlyArray<{ path: string, slug: string }> }} input
+ *   `pages`: each `content/pages/*.json` with its parsed `slug`; `rawPages`: each
+ *   `content/pages-html/**.html` with the slug its path encodes.
+ * @returns {PageSlugFinding[]}
+ */
+export function pageSlugFindings({ pages = [], rawPages = [] }) {
+  /** @type {PageSlugFinding[]} */
+  const findings = [];
+  /** @type {Map<string, string>} */
+  const claimed = new Map();
+  for (const { path, slug } of [...pages, ...rawPages]) {
+    const reason = unservableSlugReason(slug);
+    if (reason) {
+      findings.push({
+        code: "page-slug-unservable",
+        path,
+        message: `${reason}, so the hosted store answers 404 for it`,
+        remedy: "give the page a slug of plain path segments outside the platform's routes, and add a content/redirects.json entry from any old URL",
+      });
+      continue;
+    }
+    const key = /** @type {string} */ (slug);
+    const first = claimed.get(key);
+    if (first !== undefined) {
+      findings.push({
+        code: "page-slug-duplicate",
+        path,
+        message: `slug "${slug}" is also claimed by ${first} — the hosted store serves only one of them`,
+        remedy: "give each page its own slug",
+      });
+      continue;
+    }
+    claimed.set(key, path);
+  }
+  return findings;
+}

package/apps/storefront/src/lib/content/storyblok/provider.ts

@@ -261,6 +261,23 @@ async function readRawDevFile(scope: string, relative: string): Promise<string |
   }
 }
 
+/**
+ * An editorial page is routed by its JSON `slug`, never by its file name (`pages/<name>.json`
+ * may hold `"slug": "policies/terms-of-service"`). The file named after the slug is read first
+ * because it is the common layout; any other match needs the enumeration.
+ */
+async function pageBySlug(
+  slug: string,
+  read: (relative: string) => Promise<EditorialPage | null>,
+  list: () => Promise<EditorialPage[]>,
+): Promise<EditorialPage | null> {
+  const wanted = slug.replace(/^\/+|\/+$/g, "");
+  if (!wanted) return null;
+  const named = await read(`pages/${wanted}.json`);
+  if (named?.slug === wanted) return named;
+  return (await list()).find((page) => page.slug === wanted) ?? null;
+}
+
 export class LocalContentProvider implements ContentProvider {
   constructor(private readonly scope: string = DEFAULT_SCOPE) {}
 
@@ -714,8 +731,11 @@ export class PublishedContentProvider implements ContentProvider {
     return config ?? ((await this.usesVersionedContent()) ? EMPTY_CHROME_CONFIG : this.base.getChrome());
   }
   async getPage(slug: string): Promise<EditorialPage | null> {
-    const page = await this.published<EditorialPage>(`pages/${slug}.json`);
-    return page ?? ((await this.usesVersionedContent()) ? null : this.base.getPage(slug));
+    if (!(await this.usesVersionedContent())) {
+      const legacy = await this.published<EditorialPage>(`pages/${slug}.json`);
+      return legacy?.slug === slug ? legacy : this.base.getPage(slug);
+    }
+    return pageBySlug(slug, (relative) => this.published<EditorialPage>(relative), () => this.listPages());
   }
   async listPages(): Promise<EditorialPage[]> {
     // Editorial enumeration follows its source, not the generic artifact fallback.
@@ -824,7 +844,7 @@ export class VersionPinnedContentProvider implements ContentProvider {
     return config ?? EMPTY_CHROME_CONFIG;
   }
   async getPage(slug: string): Promise<EditorialPage | null> {
-    return this.pinned<EditorialPage>(`pages/${slug}.json`);
+    return pageBySlug(slug, (relative) => this.pinned<EditorialPage>(relative), () => this.listPages());
   }
   async listPages(): Promise<EditorialPage[]> {
     const paths = await this.listArtifactPaths("pages/");

package/apps/storefront/src/middleware/renderChain.ts

@@ -70,6 +70,7 @@ import {
   MATERIALIZE_MODE_BINDING,
   verifyConsentSnapshotSig,
   resolveNativeGa4SandboxUrl,
+  CANDIDATE_CONTENT_PIN_PARAM,
 } from "@tot/public-runtime";
 import { readBakedManagedInstalls } from "@/lib/integrations/integration/bakedManagedInstalls";
 import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
@@ -274,13 +275,22 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // The owning space's content-declared redirects answer before anything renders, as the CloudFront
   // redirect plane does for the same declarations: a same-origin target keeps the path-routing prefix
   // and the query; an off-site target (the root space only) is sent as declared.
+  // A pinned render (staged/candidate revision) redirects inside the revision it reviews, and its
+  // one-shot pin token never reaches the browser.
+  const declaredRedirectHeaders = (location: string): HeadersInit => {
+    if (!location.startsWith("/")) return { location };
+    let search = url.search;
+    if (url.searchParams.has(CANDIDATE_CONTENT_PIN_PARAM)) {
+      const query = new URLSearchParams(url.search);
+      query.delete(CANDIDATE_CONTENT_PIN_PARAM);
+      search = query.toString() ? `?${query.toString()}` : "";
+    }
+    return { location: `${url.origin}${candidatePin ? candidatePin.basePath : basePath}${location}${search}` };
+  };
   if (publicationSource.status === "selected") {
     const location = publicationContentRedirectLocationV1(publicationSource.artifact, input.publicationRequestPath);
     if (location) {
-      const response = new Response(null, {
-        status: 308,
-        headers: { location: location.startsWith("/") ? `${url.origin}${basePath}${location}${url.search}` : location },
-      });
+      const response = new Response(null, { status: 308, headers: declaredRedirectHeaders(location) });
       applySecurityHeaders(response.headers);
       if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
       return response;
@@ -355,10 +365,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   if (publicationSource.status === "legacy-root") {
     const location = await contentRedirectLocation(locals.content, renderPath);
     if (location) {
-      const response = new Response(null, {
-        status: 308,
-        headers: { location: location.startsWith("/") ? `${url.origin}${basePath}${location}${url.search}` : location },
-      });
+      const response = new Response(null, { status: 308, headers: declaredRedirectHeaders(location) });
       applySecurityHeaders(response.headers);
       return response;
     }

package/apps/storefront/src/middleware/routeBranch.ts

@@ -33,6 +33,7 @@ import {
   type RouteTierIndexV1,
   type ResolvedRouteTierV1,
 } from "@tot/public-runtime";
+import { parseSitemapChildPathV1 } from "@tot/public-runtime/sitemap-index";
 
 /**
  * The three serving shapes.
@@ -103,9 +104,11 @@ export function isPlatformStaticAssetPath(renderPath: string): boolean {
   return PLATFORM_STATIC_ASSET_PREFIXES.some((entry) => matchesPathOrPrefix(renderPath, entry));
 }
 
+/** Discovery documents, child sitemaps (`/sitemap-<group>-<page>.xml`) included. */
 export function isPlatformPublicDiscoveryPath(renderPath: string): boolean {
   const caseFolded = renderPath.toLowerCase();
-  return PLATFORM_PUBLIC_DISCOVERY_PATHS.some((entry) => caseFolded === entry);
+  return PLATFORM_PUBLIC_DISCOVERY_PATHS.some((entry) => caseFolded === entry) ||
+    parseSitemapChildPathV1(caseFolded) !== null;
 }
 
 export function isPlatformPublicAppRoutePath(renderPath: string): boolean {

package/apps/storefront/src/pages/_sitemap.ts

@@ -0,0 +1,180 @@
+/**
+ * Per-tenant XML sitemap: `/sitemap.xml` is an index of typed, paged child sitemaps
+ * (`/sitemap-<group>-<page>.xml`, the shared contract in `@tot/public-runtime/sitemap-index`).
+ *
+ * Built from the resolved tenant's canonical base + catalog. ACTIVE products only —
+ * getAllActiveProducts() excludes the draft canary (`trail-cap`), so drafts never leak into the
+ * sitemap. Collections are filtered to those with at least one active product
+ * (nonEmptyCollections), so empty synthesized collection shells never become crawlable dead ends.
+ * Editorial slugs come from the ContentProvider. The canonical base is resolved per-request (prod
+ * domain OR path-prefixed preview host), so every emitted loc, index and child alike, is
+ * prefix-correct without special-casing here.
+ *
+ * Static publication fetches the index, follows it to every child, materializes each child as a
+ * file at its own path, and takes the page set from the children (withSitemapRoutes in
+ * scripts/publish/lib/routes.mjs) — so listing a page here is what makes it exist on BOTH serving
+ * planes, not just the SSR Worker.
+ */
+import type { APIContext } from "astro";
+import {
+  chunkSitemapGroupsV1,
+  parseSitemapChildPathV1,
+  renderSitemapIndexV1,
+  renderSitemapUrlsetV1,
+  type SitemapChildV1,
+  type SitemapGroupV1,
+  type SitemapUrlV1,
+} from "@tot/public-runtime/sitemap-index";
+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";
+import { getTheBuildSettings, listBuildPosts } from "@/lib/content/the-build/provider.js";
+import { resolveTheBuildIndexCopy } from "@/lib/content/the-build/pagination.js";
+import { isIndexableHtml, rawPageCanonicalUrl } from "@/lib/content/shared/rawMarketingHtml.js";
+import { compileRouteTierIndexV1 } from "@tot/public-runtime";
+import { readKv } from "@/lib/publication/shared/runtimeEnv.js";
+import {
+  declaresMountedSpacesV1,
+  mountedDiscoveryUrlV1,
+  readMountedPublicationDiscoveryV1,
+  rootOwnsDiscoveryPathV1,
+} from "@/lib/publication/mountedDiscovery.js";
+import { collectionPathsV1, blogPathOptsV1 } from "@/lib/content/blog/collectionPaths.js";
+import { pageUrlForm } from "@/lib/content/seo/urlForm.js";
+
+type SitemapGroups = Record<SitemapGroupV1, SitemapUrlV1[]>;
+
+const XML_HEADERS = {
+  "content-type": "application/xml; charset=utf-8",
+  "cache-control": "public, max-age=300, s-maxage=3600",
+} as const;
+
+/** Every indexable URL the tenant serves, sorted into the sitemap groups. */
+async function collectSitemapGroups(locals: APIContext["locals"]): Promise<SitemapGroups> {
+  const { tot, tenant, canonicalBase, content, features, publicationTimestamp } = locals;
+  const base = canonicalBase.replace(/\/$/, "");
+  const blogSettings = await getBlogSettings(tenant.tenant_id, content);
+  const blogPaths = collectionPathsV1(locals, "blog", blogPathOptsV1(blogSettings));
+  const buildPaths = collectionPathsV1(locals, "the-build");
+  const groups: SitemapGroups = { pages: [], collections: [], products: [], blogs: [], build: [], spaces: [] };
+
+  groups.pages.push({ loc: `${base}/` });
+
+  // Commerce URLs only for tenants with a catalog sitemap. Marketing tenants
+  // emit homepage + content pages, keeping product/collection routes out.
+  if (features.commerceSitemap) {
+    const [products, allCollections] = await Promise.all([
+      tot.getAllActiveProducts(),
+      tot.listCollections(),
+    ]);
+    // Only collections with at least one active product — empty synthesized
+    // shells (all-draft/dropped membership) stay out of the sitemap.
+    const collections = nonEmptyCollections(allCollections, products);
+    groups.collections.push({ loc: `${base}/collections` });
+    for (const c of collections) {
+      groups.collections.push({ loc: `${base}/collections/${c.handle}` });
+      // Paginated pages (N≥2): 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++) groups.collections.push({ loc: `${base}${collectionPagePath(c.handle, n)}` });
+    }
+    for (const p of products) {
+      const entry: SitemapUrlV1 = { loc: `${base}/products/${p.handle}` };
+      if (p.updated_at) entry.lastmod = p.updated_at;
+      groups.products.push(entry);
+    }
+  }
+
+  // Raw tenant-authored marketing subpages (content/<tenant>/pages-html/*.html).
+  const rawPageSlugs = await content.listPageHtmlSlugs();
+  const rawPages = await Promise.all(
+    rawPageSlugs.map(async (slug) => ({ slug, html: await content.getPageHtml(slug) })),
+  );
+  for (const { slug, html } of rawPages) {
+    if (html && isIndexableHtml(html)) groups.pages.push({ loc: rawPageCanonicalUrl(canonicalBase, slug) });
+  }
+
+  for (const page of await content.listPages()) groups.pages.push({ loc: `${base}/${page.slug}` });
+
+  const blogPosts = await listBlogPosts(tenant.tenant_id, content, publicationTimestamp);
+  if (blogPosts.length > 0) {
+    groups.blogs.push({ loc: `${base}${blogPaths.index}` });
+    // Paginated pages (N≥2) — the static materializer discovers these routes off this list.
+    const { pageSize } = resolveBlogIndexCopy(blogSettings, tenant.displayName);
+    const totalBlogPages = Math.max(1, Math.ceil(blogPosts.length / pageSize));
+    for (let n = 2; n <= totalBlogPages; n++) groups.blogs.push({ loc: `${base}${blogPaths.page(n)}` });
+    for (const post of blogPosts) {
+      groups.blogs.push({ loc: `${base}${blogPaths.post(post.slug)}`, lastmod: post.modifiedAt || post.publishedAt });
+    }
+    // Author archives (blog/author/[author].astro): one per distinct byline, same source as
+    // the pages themselves so the sitemap never lists an archive that would 404 (and vice
+    // versa — the static publish's T3 gate requires every rendered route to appear here).
+    const authorSlugs = [...new Set(blogPosts.map((post) => authorSlug(post.author)).filter(Boolean))].sort();
+    for (const slug of authorSlugs) groups.blogs.push({ loc: `${base}${blogPaths.author(slug)}` });
+    const categorySlugs = [...new Set(blogPosts.flatMap((post) => post.categories.map(categorySlug)).filter(Boolean))].sort();
+    const tagSlugs = [...new Set(blogPosts.flatMap((post) => post.tags.map(categorySlug)).filter(Boolean))].sort();
+    for (const slug of categorySlugs) groups.blogs.push({ loc: `${base}${blogPaths.category(slug)}` });
+    for (const slug of tagSlugs) groups.blogs.push({ loc: `${base}${blogPaths.tag(slug)}` });
+  }
+
+  const buildPosts = await listBuildPosts(tenant.tenant_id, { content, now: publicationTimestamp });
+  if (buildPosts.length > 0) {
+    groups.build.push({ loc: `${base}${buildPaths.index}` });
+    const buildSettings = await getTheBuildSettings(tenant.tenant_id, content);
+    const { pageSize } = resolveTheBuildIndexCopy(buildSettings, tenant.displayName);
+    const totalBuildPages = Math.max(1, Math.ceil(buildPosts.length / pageSize));
+    for (let n = 2; n <= totalBuildPages; n++) groups.build.push({ loc: `${base}${buildPaths.page(n)}` });
+    for (const post of buildPosts) {
+      groups.build.push({ loc: `${base}${buildPaths.post(post.slug)}`, lastmod: post.modifiedAt || post.publishedAt });
+    }
+  }
+
+  // Mounted publication spaces: root rows never list into a mount, and each
+  // public mount lists its own entries (an internal mount lists nothing).
+  if (declaresMountedSpacesV1(tenant)) {
+    const index = compileRouteTierIndexV1(tenant);
+    const listed = new Set<string>();
+    for (const group of Object.keys(groups) as SitemapGroupV1[]) {
+      groups[group] = groups[group].filter((u) => rootOwnsDiscoveryPathV1(index, u.loc.slice(base.length) || "/"));
+      for (const u of groups[group]) listed.add(u.loc);
+    }
+    const mounted = await readMountedPublicationDiscoveryV1({ tenant, store: await readKv("TENANT_CACHE"), index });
+    for (const entry of mounted) {
+      if (!entry.surfaces.sitemap) continue;
+      const loc = mountedDiscoveryUrlV1(canonicalBase, entry);
+      if (listed.has(loc)) continue;
+      listed.add(loc);
+      const lastmod = entry.updatedAt ?? entry.publishedAt;
+      groups.spaces.push(lastmod ? { loc, lastmod } : { loc });
+    }
+  }
+
+  for (const group of Object.keys(groups) as SitemapGroupV1[]) {
+    groups[group] = groups[group].map((u) => ({ ...u, loc: pageUrlForm(u.loc, tenant.seo) }));
+  }
+  return groups;
+}
+
+/** The tenant's child sitemaps, in index order; empty groups have none. */
+export async function tenantSitemapChildren(locals: APIContext["locals"]): Promise<SitemapChildV1[]> {
+  const groups = await collectSitemapGroups(locals);
+  return chunkSitemapGroupsV1((Object.keys(groups) as SitemapGroupV1[]).map((group) => ({ group, urls: groups[group] })));
+}
+
+/** `/sitemap.xml`: the index of every child sitemap. */
+export async function sitemapIndexResponse(context: APIContext): Promise<Response> {
+  const children = await tenantSitemapChildren(context.locals);
+  return new Response(renderSitemapIndexV1(context.locals.canonicalBase, children), { headers: XML_HEADERS });
+}
+
+/** `/sitemap-<group>-<page>.xml`: one child's `<urlset>`, or 404 when the index names no such child. */
+export async function sitemapChildResponse(context: APIContext, childPath: string): Promise<Response> {
+  const named = parseSitemapChildPathV1(childPath);
+  if (!named) return new Response("Not found", { status: 404, headers: { "content-type": "text/plain; charset=utf-8" } });
+  const children = await tenantSitemapChildren(context.locals);
+  const child = children.find((c) => c.group === named.group && c.page === named.page);
+  if (!child) return new Response("Not found", { status: 404, headers: { "content-type": "text/plain; charset=utf-8" } });
+  return new Response(renderSitemapUrlsetV1(child.urls), { headers: XML_HEADERS });
+}

package/apps/storefront/src/pages/sitemap-[child].xml.ts

@@ -0,0 +1,10 @@
+/**
+ * One typed, paged child sitemap (`/sitemap-<group>-<page>.xml`) named by `/sitemap.xml`.
+ * A path the index does not name answers 404.
+ */
+import type { APIContext } from "astro";
+import { sitemapChildResponse } from "./_sitemap.js";
+
+export function GET(context: APIContext): Promise<Response> {
+  return sitemapChildResponse(context, `/sitemap-${String(context.params.child ?? "")}.xml`);
+}

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

@@ -1,178 +1,11 @@
 /**
- * Per-tenant XML sitemap. Built from the resolved tenant's canonical base +
- * catalog. ACTIVE products only — getAllActiveProducts() excludes the draft
- * canary (`trail-cap`), so drafts never leak into the sitemap. Collections are
- * filtered to those with at least one active product (nonEmptyCollections), so
- * empty synthesized collection shells never become crawlable dead ends.
- * Editorial slugs come from the ContentProvider. The canonical base is resolved
- * per-request (prod domain OR path-prefixed preview host), so every emitted
- * loc is prefix-correct without special-casing here.
+ * Per-tenant sitemap index. The children it names render from `sitemap-[child].xml.ts`; both
+ * come from one builder (`./_sitemap.ts`), so the index can never name a child that does not
+ * render.
  */
 import type { APIContext } from "astro";
-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";
-import { getTheBuildSettings, listBuildPosts } from "@/lib/content/the-build/provider.js";
-import { resolveTheBuildIndexCopy } from "@/lib/content/the-build/pagination.js";
-import { isIndexableHtml, rawPageCanonicalUrl } from "@/lib/content/shared/rawMarketingHtml.js";
-import { compileRouteTierIndexV1 } from "@tot/public-runtime";
-import { readKv } from "@/lib/publication/shared/runtimeEnv.js";
-import {
-  declaresMountedSpacesV1,
-  mountedDiscoveryUrlV1,
-  readMountedPublicationDiscoveryV1,
-  rootOwnsDiscoveryPathV1,
-} from "@/lib/publication/mountedDiscovery.js";
-import { collectionPathsV1, blogPathOptsV1 } from "@/lib/content/blog/collectionPaths.js";
-import { pageUrlForm } from "@/lib/content/seo/urlForm.js";
+import { sitemapIndexResponse } from "./_sitemap.js";
 
-interface SitemapUrl {
-  loc: string;
-  lastmod?: string;
-}
-
-/** XML-escape text inside a tag (URLs may contain & in query, etc.). */
-function escapeXml(value: string): string {
-  return value
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-export async function GET(context: APIContext): Promise<Response> {
-  const { tot, tenant, canonicalBase, content, features, publicationTimestamp } = context.locals;
-  const base = canonicalBase.replace(/\/$/, "");
-  const blogSettings = await getBlogSettings(tenant.tenant_id, content);
-  const blogPaths = collectionPathsV1(context.locals, "blog", blogPathOptsV1(blogSettings));
-  const buildPaths = collectionPathsV1(context.locals, "the-build");
-
-  const urls: SitemapUrl[] = [{ loc: `${base}/` }];
-
-  // Commerce URLs only for tenants with a catalog sitemap. Marketing tenants
-  // emit homepage + content pages, keeping product/collection routes out.
-  if (features.commerceSitemap) {
-    const [products, allCollections] = await Promise.all([
-      tot.getAllActiveProducts(),
-      tot.listCollections(),
-    ]);
-    // Only collections with at least one active product — empty synthesized
-    // shells (all-draft/dropped membership) stay out of the sitemap.
-    const collections = nonEmptyCollections(allCollections, products);
-    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}` };
-      if (p.updated_at) entry.lastmod = p.updated_at;
-      urls.push(entry);
-    }
-  }
-
-  // Raw tenant-authored marketing subpages (content/<tenant>/pages-html/*.html).
-  const rawPageSlugs = await content.listPageHtmlSlugs();
-  const rawPages = await Promise.all(
-    rawPageSlugs.map(async (slug) => ({ slug, html: await content.getPageHtml(slug) })),
-  );
-  for (const { slug, html } of rawPages) {
-    if (html && isIndexableHtml(html)) {
-      urls.push({ loc: rawPageCanonicalUrl(canonicalBase, slug) });
-    }
-  }
-
-  const pages = await content.listPages();
-  for (const page of pages) {
-    urls.push({ loc: `${base}/${page.slug}` });
-  }
-
-  const blogPosts = await listBlogPosts(tenant.tenant_id, content, publicationTimestamp);
-  if (blogPosts.length > 0) {
-    urls.push({ loc: `${base}${blogPaths.index}` });
-    // Paginated pages (N≥2) — the static materializer discovers these new routes
-    // straight off this list (withSitemapRoutes in scripts/publish/lib/routes.mjs),
-    // so listing them here is what makes /blog/page/N/ exist in BOTH serving
-    // planes, not just the SSR Worker.
-    const { pageSize } = resolveBlogIndexCopy(blogSettings, tenant.displayName);
-    const totalBlogPages = Math.max(1, Math.ceil(blogPosts.length / pageSize));
-    for (let n = 2; n <= totalBlogPages; n++) urls.push({ loc: `${base}${blogPaths.page(n)}` });
-    for (const post of blogPosts) {
-      urls.push({ loc: `${base}${blogPaths.post(post.slug)}`, lastmod: post.modifiedAt || post.publishedAt });
-    }
-    // Author archives (blog/author/[author].astro): one per distinct byline,
-    // same source as the pages themselves so the sitemap never lists an
-    // archive that would 404 (and vice versa — the static publish's T3 gate
-    // requires every rendered route to appear here).
-    const authorSlugs = [
-      ...new Set(blogPosts.map((post) => authorSlug(post.author)).filter(Boolean)),
-    ].sort();
-    for (const slug of authorSlugs) {
-      urls.push({ loc: `${base}${blogPaths.author(slug)}` });
-    }
-    const categorySlugs = [...new Set(blogPosts.flatMap((post) => post.categories.map(categorySlug)).filter(Boolean))].sort();
-    const tagSlugs = [...new Set(blogPosts.flatMap((post) => post.tags.map(categorySlug)).filter(Boolean))].sort();
-    for (const slug of categorySlugs) urls.push({ loc: `${base}${blogPaths.category(slug)}` });
-    for (const slug of tagSlugs) urls.push({ loc: `${base}${blogPaths.tag(slug)}` });
-  }
-
-  const buildPosts = await listBuildPosts(tenant.tenant_id, { content, now: publicationTimestamp });
-  if (buildPosts.length > 0) {
-    urls.push({ loc: `${base}${buildPaths.index}` });
-    // Paginated pages (N≥2), same reasoning as /blog/page/N/ above: the static
-    // materializer discovers these new routes straight off this list.
-    const buildSettings = await getTheBuildSettings(tenant.tenant_id, content);
-    const { pageSize } = resolveTheBuildIndexCopy(buildSettings, tenant.displayName);
-    const totalBuildPages = Math.max(1, Math.ceil(buildPosts.length / pageSize));
-    for (let n = 2; n <= totalBuildPages; n++) urls.push({ loc: `${base}${buildPaths.page(n)}` });
-    for (const post of buildPosts) {
-      urls.push({ loc: `${base}${buildPaths.post(post.slug)}`, lastmod: post.modifiedAt || post.publishedAt });
-    }
-  }
-
-  // Mounted publication spaces: root rows never list into a mount, and each
-  // public mount lists its own entries (an internal mount lists nothing).
-  if (declaresMountedSpacesV1(tenant)) {
-    const index = compileRouteTierIndexV1(tenant);
-    const rootRows = urls.filter((u) => rootOwnsDiscoveryPathV1(index, u.loc.slice(base.length) || "/"));
-    urls.length = 0;
-    urls.push(...rootRows);
-    const listed = new Set(urls.map((u) => u.loc));
-    const mounted = await readMountedPublicationDiscoveryV1({ tenant, store: await readKv("TENANT_CACHE"), index });
-    for (const entry of mounted) {
-      if (!entry.surfaces.sitemap) continue;
-      const loc = mountedDiscoveryUrlV1(canonicalBase, entry);
-      if (listed.has(loc)) continue;
-      listed.add(loc);
-      const lastmod = entry.updatedAt ?? entry.publishedAt;
-      urls.push(lastmod ? { loc, lastmod } : { loc });
-    }
-  }
-
-  const body = `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${urls
-  .map(
-    (u) =>
-      `  <url>\n    <loc>${escapeXml(pageUrlForm(u.loc, tenant.seo))}</loc>${
-        u.lastmod ? `\n    <lastmod>${escapeXml(u.lastmod)}</lastmod>` : ""
-      }\n  </url>`,
-  )
-  .join("\n")}
-</urlset>
-`;
-
-  return new Response(body, {
-    headers: {
-      "content-type": "application/xml; charset=utf-8",
-      "cache-control": "public, max-age=300, s-maxage=3600",
-    },
-  });
+export function GET(context: APIContext): Promise<Response> {
+  return sitemapIndexResponse(context);
 }

package/package.json

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

package/packages/public-runtime/package.json

@@ -10,6 +10,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./blog-visibility": "./src/blog-visibility.mjs",
+    "./sitemap-index": "./src/sitemap-index.mjs",
     "./preview-url": "./src/preview-url.mjs",
     "./publication-redirects": "./src/publication-redirects.mjs",
     "./image-dependencies": "./src/image-dependencies.ts",

package/packages/public-runtime/src/publication-space.ts

@@ -13,6 +13,7 @@ import {
   type PublicationCollectionV1,
 } from "./blog-visibility.mjs";
 import { normalizeRedirectPath } from "./publication-redirects.mjs";
+import { parseSitemapChildPathV1 } from "./sitemap-index.mjs";
 import {
   ANNOTATION_KEYS,
   type ContractResult,
@@ -337,7 +338,8 @@ function validateIdentifier(value: string | undefined, v: Violations, path: stri
 
 function isReservedMount(mount: string): boolean {
   const caseFolded = mount.toLowerCase();
-  return PUBLICATION_SPACE_RESERVED_MOUNTS.some((reserved) => publicationMountMatchesPath(reserved, caseFolded));
+  return PUBLICATION_SPACE_RESERVED_MOUNTS.some((reserved) => publicationMountMatchesPath(reserved, caseFolded)) ||
+    parseSitemapChildPathV1(caseFolded) !== null;
 }
 
 function validateSource(raw: unknown, v: Violations, path: string): PublicationSpaceSourceV1 | undefined {

package/packages/public-runtime/src/route-tier.ts

@@ -16,6 +16,7 @@
  */
 import type { TenantConfig } from "./tenant.js";
 import type { ContractViolation } from "./integration/result.js";
+import { parseSitemapChildPathV1 } from "./sitemap-index.mjs";
 import {
   PUBLICATION_SPACE_RESERVED_MOUNTS,
   type NormalizedPublicationMountEntryV1,
@@ -134,7 +135,7 @@ function isPlatformReserved(normalizedPath: string): boolean {
   const caseFolded = normalizedPath.toLowerCase();
   return PUBLICATION_SPACE_RESERVED_MOUNTS.some((reserved) =>
     publicationMountMatchesPath(reserved, caseFolded),
-  );
+  ) || parseSitemapChildPathV1(caseFolded) !== null;
 }
 
 /**

package/packages/public-runtime/src/sitemap-index.d.mts

@@ -0,0 +1,33 @@
+export type SitemapGroupV1 = "pages" | "collections" | "products" | "blogs" | "build" | "spaces";
+
+export interface SitemapUrlV1 {
+  loc: string;
+  lastmod?: string;
+}
+
+export interface SitemapChildV1 {
+  group: SitemapGroupV1;
+  page: number;
+  path: string;
+  urls: SitemapUrlV1[];
+}
+
+export declare const SITEMAP_INDEX_PATH_V1: "/sitemap.xml";
+export declare const SITEMAP_MAX_URLS_PER_CHILD_V1: number;
+export declare const SITEMAP_GROUPS_V1: readonly SitemapGroupV1[];
+export declare function sitemapChildPathV1(group: SitemapGroupV1, page: number): string;
+export declare function parseSitemapChildPathV1(path: unknown): { group: SitemapGroupV1; page: number } | null;
+export declare function isSitemapDocumentPathV1(path: string): boolean;
+export declare function chunkSitemapGroupsV1(
+  groups: ReadonlyArray<{ group: SitemapGroupV1; urls: readonly SitemapUrlV1[] }>,
+  maxPerChild?: number,
+): SitemapChildV1[];
+export declare function newestLastmodV1(urls: readonly SitemapUrlV1[]): string | undefined;
+export declare function renderSitemapUrlsetV1(urls: readonly SitemapUrlV1[]): string;
+export declare function renderSitemapIndexV1(base: string, children: readonly SitemapChildV1[]): string;
+export declare function isSitemapIndexXmlV1(xml: string): boolean;
+export declare function sitemapIndexLocsV1(xml: string): string[];
+export declare function countSitemapUrlsV1(
+  xml: string,
+  readChild: (loc: string) => Promise<string | null>,
+): Promise<number>;

package/packages/public-runtime/src/sitemap-index.mjs

@@ -0,0 +1,156 @@
+// @ts-check
+/**
+ * The tenant sitemap contract, shared by the Worker that renders it and the publish tooling
+ * that materializes and validates it on both serving substrates.
+ *
+ * `/sitemap.xml` is a `<sitemapindex>`. Its entries are typed, paged child sitemaps at
+ * `/sitemap-<group>-<page>.xml`, each a `<urlset>` of at most {@link SITEMAP_MAX_URLS_PER_CHILD_V1}
+ * URLs. A child path ends in `.xml`, so S3/CloudFront and the Cloudflare static bundle both serve
+ * it as a plain file with no rewrite, and the materializer writes it at the same bundle path.
+ *
+ * Pure: no I/O, no platform imports.
+ */
+
+/** @typedef {{loc: string, lastmod?: string}} SitemapUrl */
+
+/** The one discovery entry point robots.txt advertises. */
+export const SITEMAP_INDEX_PATH_V1 = "/sitemap.xml";
+
+/**
+ * URLs per child sitemap. The protocol allows 50,000; 5,000 keeps each child a small, fast,
+ * individually cacheable document and matches the paging large commerce platforms use.
+ */
+export const SITEMAP_MAX_URLS_PER_CHILD_V1 = 5000;
+
+/** Child sitemap groups, in the order the index lists them. */
+export const SITEMAP_GROUPS_V1 = Object.freeze(["pages", "collections", "products", "blogs", "build", "spaces"]);
+
+const CHILD_PATH = /^\/sitemap-([a-z]+)-([1-9][0-9]{0,5})\.xml$/;
+
+/**
+ * `/sitemap-<group>-<page>.xml` for a declared group and a 1-based page.
+ * @param {string} group @param {number} page @returns {string}
+ */
+export function sitemapChildPathV1(group, page) {
+  if (!SITEMAP_GROUPS_V1.includes(group)) throw new Error(`unknown sitemap group ${JSON.stringify(group)}`);
+  if (!Number.isInteger(page) || page < 1) throw new Error(`sitemap page must be a positive integer, got ${page}`);
+  return `/sitemap-${group}-${page}.xml`;
+}
+
+/**
+ * The group and page a child sitemap path names, or null when it names none.
+ * @param {unknown} path @returns {{group: string, page: number} | null}
+ */
+export function parseSitemapChildPathV1(path) {
+  if (typeof path !== "string") return null;
+  const match = CHILD_PATH.exec(path);
+  if (!match || !SITEMAP_GROUPS_V1.includes(match[1])) return null;
+  return { group: match[1], page: Number(match[2]) };
+}
+
+/** True for `/sitemap.xml` and for every well-formed child sitemap path. @param {string} path */
+export function isSitemapDocumentPathV1(path) {
+  return path === SITEMAP_INDEX_PATH_V1 || parseSitemapChildPathV1(path) !== null;
+}
+
+/**
+ * Page each group into children of at most {@link SITEMAP_MAX_URLS_PER_CHILD_V1} URLs, in
+ * {@link SITEMAP_GROUPS_V1} order. An empty group yields no child.
+ * @param {ReadonlyArray<{group: string, urls: readonly SitemapUrl[]}>} groups
+ * @param {number} [maxPerChild]
+ * @returns {{group: string, page: number, path: string, urls: SitemapUrl[]}[]}
+ */
+export function chunkSitemapGroupsV1(groups, maxPerChild = SITEMAP_MAX_URLS_PER_CHILD_V1) {
+  /** @type {Map<string, SitemapUrl[]>} */
+  const byGroup = new Map();
+  for (const { group, urls } of groups) {
+    if (!SITEMAP_GROUPS_V1.includes(group)) throw new Error(`unknown sitemap group ${JSON.stringify(group)}`);
+    byGroup.set(group, [...(byGroup.get(group) ?? []), ...urls]);
+  }
+  /** @type {{group: string, page: number, path: string, urls: SitemapUrl[]}[]} */
+  const children = [];
+  for (const group of SITEMAP_GROUPS_V1) {
+    const urls = byGroup.get(group) ?? [];
+    for (let start = 0, page = 1; start < urls.length; start += maxPerChild, page += 1) {
+      children.push({ group, page, path: sitemapChildPathV1(group, page), urls: urls.slice(start, start + maxPerChild) });
+    }
+  }
+  return children;
+}
+
+/** @param {string} value */
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * The newest `lastmod` among `urls`, spelled as its source spelled it; undefined when none parses.
+ * @param {readonly SitemapUrl[]} urls @returns {string | undefined}
+ */
+export function newestLastmodV1(urls) {
+  /** @type {string | undefined} */
+  let newest;
+  let newestTime = -Infinity;
+  for (const { lastmod } of urls) {
+    const time = lastmod ? Date.parse(lastmod) : NaN;
+    if (Number.isFinite(time) && time > newestTime) {
+      newest = lastmod;
+      newestTime = time;
+    }
+  }
+  return newest;
+}
+
+/** A `<urlset>` document. Locs are written exactly as given. @param {readonly SitemapUrl[]} urls */
+export function renderSitemapUrlsetV1(urls) {
+  const rows = urls.map((u) =>
+    `  <url>\n    <loc>${escapeXml(u.loc)}</loc>${u.lastmod ? `\n    <lastmod>${escapeXml(u.lastmod)}</lastmod>` : ""}\n  </url>`);
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${rows.join("\n")}\n</urlset>\n`;
+}
+
+/**
+ * A `<sitemapindex>` naming each child at `base` + its path. `base` is the tenant's canonical
+ * base without a trailing slash, path prefix included, so every loc keeps the prefix the page
+ * locs carry. Each entry's lastmod is the newest lastmod inside that child, when it has one.
+ * @param {string} base @param {readonly {path: string, urls: readonly SitemapUrl[]}[]} children
+ */
+export function renderSitemapIndexV1(base, children) {
+  const root = base.replace(/\/+$/, "");
+  const rows = children.map((child) => {
+    const lastmod = newestLastmodV1(child.urls);
+    return `  <sitemap>\n    <loc>${escapeXml(`${root}${child.path}`)}</loc>${lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ""}\n  </sitemap>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${rows.join("\n")}\n</sitemapindex>\n`;
+}
+
+/** True when `xml` is a `<sitemapindex>` rather than a `<urlset>`. @param {string} xml */
+export function isSitemapIndexXmlV1(xml) {
+  return /<sitemapindex[\s>]/.test(xml);
+}
+
+/**
+ * The child sitemap locs a `<sitemapindex>` names, exactly as spelled; empty for a `<urlset>`.
+ * @param {string} xml @returns {string[]}
+ */
+export function sitemapIndexLocsV1(xml) {
+  if (!isSitemapIndexXmlV1(xml)) return [];
+  return [...xml.matchAll(/<sitemap>\s*<loc>([^<]*)<\/loc>/g)].map((match) => match[1].trim());
+}
+
+/**
+ * Page URLs a sitemap lists, following an index to its children. `readChild` returns a child's
+ * body, or null when it cannot be read (which contributes nothing).
+ * @param {string} xml @param {(loc: string) => Promise<string | null>} readChild @returns {Promise<number>}
+ */
+export async function countSitemapUrlsV1(xml, readChild) {
+  /** @param {string} body */
+  const urls = (body) => (body.match(/<url>/g) ?? []).length;
+  if (!isSitemapIndexXmlV1(xml)) return urls(xml);
+  const bodies = await Promise.all(sitemapIndexLocsV1(xml).map(readChild));
+  return bodies.reduce((count, body) => count + urls(body ?? ""), 0);
+}

package/scripts/tenant/validate.mjs

@@ -46,6 +46,7 @@ import {
   workspacePathForTenantRelative,
 } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "../../agency-kit/tools/lib/public-binaries.mjs";
+import { pageSlugFindings } from "../../agency-kit/tools/lib/page-slugs.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
 import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
@@ -1200,6 +1201,18 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 3b. editorial page slugs — every page must be reachable at its slug on the hosted router
+  // (agency-kit/tools/lib/page-slugs.mjs, the rule `tot validate` applies).
+  {
+    const pages = walk(join(contentDir, "pages"), (x) => x.endsWith(".json")).sort().map((p) => {
+      const { value, error } = readJsonSafe(p);
+      return { path: rel(p), slug: error ? undefined : value?.slug };
+    });
+    const rawPages = walk(pagesDir, (x) => x.endsWith(".html")).sort()
+      .map((p) => ({ path: rel(p), slug: relative(pagesDir, p).split("\\").join("/").replace(/\.html$/, "") }));
+    for (const f of pageSlugFindings({ pages, rawPages })) findings.push(mk(ERROR, f.code, f.path, f.message, f.remedy));
+  }
+
   // 4. raw HTML documents — validate + portability + resolution
   const hasChrome = providesChrome(contentDir);
   const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));