@forgecart/cli 2.202608300703.0 → 2.202609190800.0

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -1,18 +1,104 @@
-import Link from 'next/link';
-import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { notFound, permanentRedirect } from 'next/navigation';
 import { connection } from 'next/server';
-import { Suspense } from 'react';
+import { Suspense, cache } from 'react';
 
 import { ProductPurchase } from '../../../components/ProductPurchase';
+import { LocaleLink } from '../../../components/LocaleLink';
+import { getAssetAlt } from '../../../lib/asset-alt';
 import {
   getProductBySlug,
   getSellingPlanGroupsForVariant,
+  type ProductWithSeo,
   type SellingPlanGroup,
 } from '../../../lib/forgecart';
+import type { LocaleBinding } from '../../../lib/locale/localized-path';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+import { buildAlternates } from '../../../lib/seo/alternates';
+import {
+  breadcrumbJsonLd,
+  productJsonLd,
+  serializeJsonLd,
+  type JsonLdNode,
+} from '../../../lib/seo/json-ld';
+import { entityMetadata, routeMetadata } from '../../../lib/seo/metadata';
+import { routeRobots, type RouteSearchParams } from '../../../lib/seo/noindex';
+import { getPublicOrigin } from '../../../lib/seo/public-origin';
+import { productPathsByLocale, resolveProductPath } from '../../../lib/seo/resolve-path';
+
+/**
+ * The trail, once — rendered as the visible breadcrumbs AND as the
+ * `BreadcrumbList` a crawler reads. Two lists would be two claims about where
+ * this page sits, and nothing in the template would notice them diverging.
+ */
+const BREADCRUMB_TRAIL: readonly { name: string; path: string }[] = [
+  { name: 'Home', path: '/' },
+  { name: 'Products', path: '/products' },
+];
+
+/**
+ * One product read per request, shared by `generateMetadata` and the page.
+ *
+ * Next invokes them as separate calls, so without React's request cache the
+ * slug law would run against two independent fetches — and a product renamed
+ * between them would emit metadata for one address while redirecting to
+ * another.
+ */
+const productForRequest = cache(async (slug: string) => getProductBySlug(slug));
 
 // PROGRESSIVE PRE-RENDERING: static shell; the data sections below are
 // per-request holes streamed inside their Suspense boundaries
-// (cacheComponents — see next.config.js).
+// (see next.config.js for why every route is request-rendered).
+
+/**
+ * Indexability for a product URL comes from the same resolution the page acts
+ * on, through the shared request cache — so the tag and the status can never
+ * disagree about what this URL is.
+ *
+ * Two content-level refusals ride here that no route rule could know: a
+ * FALLBACK copy (this language has no real content, so indexing it would put
+ * near-duplicate text in competition with the language that does) and the
+ * merchant's own `indexable: false`. Redirect and notFound need no directive —
+ * their metadata is discarded with the response body.
+ *
+ * This is the one route whose title, description and social image are the
+ * MERCHANT's rather than the template's: they come from the per-language SEO
+ * sidecar through `entityMetadata`, already resolved into the request's
+ * language by the shop API, so a German product page carries a German title
+ * without this file knowing anything about translation.
+ */
+export async function generateMetadata({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [{ slug }, resolvedSearchParams] = await Promise.all([params, searchParams]);
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  const product = await productForRequest(slug);
+  const resolution = resolveProductPath({ requestedSlug: slug, product, binding });
+  const entity = product ? entityMetadata(product, binding.locale) : null;
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: `/products/${slug}`,
+    searchParams: resolvedSearchParams,
+    // Unlike a structural route, a product earns its alternates per language:
+    // the map is the intersection of "has a slug" and "has content", so an
+    // untranslated language never appears. `buildAlternates` then returns
+    // undefined for a fallback copy — no canonical, no hreflang — because a
+    // derived page has no address of its own to claim and must not be pulled
+    // into a reciprocal set it is not a member of. An absent product yields an
+    // empty map, which lands in that same arm rather than needing its own.
+    pathsByLocale: product ? productPathsByLocale(product) : {},
+    title: entity?.title ?? null,
+    description: entity?.description,
+    socialImage: entity?.socialImage,
+    contentIndexable: resolution.kind === 'ok' ? resolution.indexable : false,
+  });
+}
 
 /**
  * Product detail (Blueprint `pages/product-detail`): identity block ordering —
@@ -21,25 +107,121 @@ import {
  * shoppers keep their place in the catalog.
  */
 // Next.js 15: route params are delivered as a Promise.
-export default function ProductDetailPage({ params }: { params: Promise<{ slug: string }> }) {
+/**
+ * The slug law runs in the page SHELL, above the Suspense boundary, and that
+ * placement is the whole correctness of the route's status codes.
+ *
+ * `notFound()` and `permanentRedirect()` can only set a status where Next
+ * assigns one. Raised from inside a boundary — as the product lookup used to
+ * be — the shell has already flushed with a 200 and the throw resolves as
+ * client-rendered content instead: the response is a **200 carrying a
+ * not-found page**. A crawler drops a real 404 and INDEXES a soft one, so an
+ * unknown slug would have put an error page into the index under a URL that
+ * will never hold content. (Measured: `/products/no-such-product` answered 200
+ * before this moved.)
+ *
+ * The cost is that the product read is no longer streamed — but it is the one
+ * thing this page IS, so a skeleton bought nothing while the only content
+ * loaded. The genuinely secondary read (per-variant selling plans) stays in the
+ * boundary below, which is what streaming is for.
+ */
+export default async function ProductDetailPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  const { binding } = await getRequestLocale();
+  const [{ slug }, resolvedSearchParams] = await Promise.all([params, searchParams]);
+  const product = await productForRequest(slug);
+  const resolution = resolveProductPath({ requestedSlug: slug, product, binding });
+
+  // `product === null` IS the resolution's notFound arm — spelled out rather
+  // than matched on `resolution.kind` so TypeScript narrows `product` for the
+  // render below (`notFound()` returns never). Matching the kind would leave it
+  // nullable and force a cast that asserts what the law already guarantees.
+  if (product === null) notFound();
+  if (resolution.kind === 'redirect') permanentRedirect(resolution.to);
+
   return (
     <div className="space-y-8">
+      {structuredData(product, binding, slug, resolvedSearchParams, resolution).map((node) => (
+        <script
+          key={node['@type']}
+          type="application/ld+json"
+          // The ONE way to put JSON-LD in a document; `serializeJsonLd` escapes
+          // `<`, so a description carrying `</script>` cannot close the element.
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(node) }}
+        />
+      ))}
       <Suspense fallback={<DetailSkeleton />}>
-        <ProductDetail params={params} />
+        <ProductDetail product={product} locale={binding} />
       </Suspense>
     </div>
   );
 }
 
-async function ProductDetail({ params }: { params: Promise<{ slug: string }> }) {
-  // Request-time hole (cacheComponents): the build keeps the fallback shell.
-  await connection();
-  const { slug } = await params;
-  const product = await getProductBySlug(slug);
+/**
+ * The structured data this page is entitled to emit — empty whenever it is not.
+ *
+ * Gated on the SAME `routeRobots` the metadata uses, because a page telling
+ * crawlers to ignore it while handing them a machine-readable description of
+ * its contents is making two opposite claims at once. `undefined` from that
+ * call is the one mechanism's way of saying "this is a real, indexable
+ * address", and it already covers the fallback copy, the merchant's own
+ * `indexable: false`, query-state views and the missing public origin.
+ *
+ * The origin is read ONCE and handed to both claims this function makes — the
+ * canonical `buildAlternates` derives, and the breadcrumb item URLs — so the
+ * two can never name different hosts. Its null arm is what narrows it to a
+ * string for those URLs; it cannot be taken here, because no-origin is one of
+ * the reasons the gate above would already have closed.
+ */
+function structuredData(
+  product: ProductWithSeo,
+  binding: LocaleBinding,
+  slug: string,
+  searchParams: RouteSearchParams,
+  resolution: ReturnType<typeof resolveProductPath>,
+): JsonLdNode[] {
+  const contentIndexable = resolution.kind === 'ok' ? resolution.indexable : false;
+  if (routeRobots(`/products/${slug}`, searchParams, contentIndexable) !== undefined) return [];
+
+  const publicOrigin = getPublicOrigin();
+  const alternates = buildAlternates({
+    binding,
+    pathsByLocale: productPathsByLocale(product),
+    publicOrigin,
+  });
+  if (!alternates || publicOrigin === null) return [];
 
-  if (!product) {
-    notFound();
-  }
+  return [
+    productJsonLd({
+      name: product.name,
+      description: product.description,
+      image: product.featuredAsset?.preview,
+      canonical: alternates.canonical,
+      variants: product.variants,
+    }),
+    breadcrumbJsonLd({
+      binding,
+      publicOrigin,
+      leafName: product.name,
+      trail: BREADCRUMB_TRAIL,
+    }),
+  ];
+}
+
+async function ProductDetail({
+  product,
+  locale: binding,
+}: {
+  product: ProductWithSeo;
+  locale: LocaleBinding;
+}) {
+  // Request-time hole: streamed inside its Suspense boundary.
+  await connection();
 
   // Subscription selling plans are eligible per variant, so fetch the groups for
   // each of the product's variants (in parallel) and pass a variantId -> groups
@@ -60,12 +242,13 @@ async function ProductDetail({ params }: { params: Promise<{ slug: string }> })
     <>
       <div className="breadcrumbs text-sm text-base-content/60">
         <ul>
-          <li>
-            <Link href="/">Home</Link>
-          </li>
-          <li>
-            <Link href="/products">Products</Link>
-          </li>
+          {BREADCRUMB_TRAIL.map((crumb) => (
+            <li key={crumb.path}>
+              <LocaleLink href={crumb.path} locale={binding}>
+                {crumb.name}
+              </LocaleLink>
+            </li>
+          ))}
           <li>
             <span aria-current="page">{product.name}</span>
           </li>
@@ -78,7 +261,7 @@ async function ProductDetail({ params }: { params: Promise<{ slug: string }> })
             // eslint-disable-next-line @next/next/no-img-element
             <img
               src={product.featuredAsset.preview}
-              alt={product.name}
+              alt={getAssetAlt(product.featuredAsset)}
               className="h-full w-full object-cover"
             />
           ) : (

package/templates/storefront/src/app/products/page.tsx

@@ -1,30 +1,65 @@
+import type { Metadata } from 'next';
 import { connection } from 'next/server';
 import { Suspense } from 'react';
 
 import { ProductCard } from '../../components/ProductCard';
 import { getProducts } from '../../lib/forgecart';
+import type { LocaleBinding } from '../../lib/locale/localized-path';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { staticPathsByLocale } from '../../lib/seo/alternates';
+import { routeMetadata } from '../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../lib/seo/noindex';
+
+/**
+ * The catalog is indexable; a SORTED catalog is the same products in another
+ * order, so `?sort=` is a view of this page rather than a page of its own.
+ *
+ * The title is the template's own chrome, in English, exactly like this page's
+ * `<h1>`: structural surfaces are not translated content, and inventing a
+ * translation layer for them here would put a second, weaker source of truth
+ * beside the shop API's. The pages whose titles a merchant actually cares
+ * about — products — take theirs from the localized SEO sidecar.
+ */
+export async function generateMetadata({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [resolvedSearchParams, { binding, languageCodes, shopName, channelResolved }] =
+    await Promise.all([searchParams, getRequestLocale()]);
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/products',
+    pathsByLocale: staticPathsByLocale(languageCodes, '/products'),
+    searchParams: resolvedSearchParams,
+    title: 'All products',
+  });
+}
 
 // PROGRESSIVE PRE-RENDERING: static shell; the data sections below are
 // per-request holes streamed inside their Suspense boundaries
-// (cacheComponents — see next.config.js).
+// (see next.config.js for why every route is request-rendered).
 
 /**
  * Catalog — the browse grid. The header carries the count as orientation
  * (Blueprint listing guidance: state scope up front); cards do the visual
  * lifting, the grid stays quiet.
  */
-export default function ProductsPage() {
+export default async function ProductsPage() {
+  const { binding } = await getRequestLocale();
   return (
     <div className="space-y-8">
       <Suspense fallback={<CatalogSkeleton />}>
-        <Catalog />
+        <Catalog locale={binding} />
       </Suspense>
     </div>
   );
 }
 
-async function Catalog() {
-  // Request-time hole (cacheComponents): the build keeps the fallback shell.
+async function Catalog({ locale }: { locale: LocaleBinding }) {
+  // Request-time hole: streamed inside its Suspense boundary.
   await connection();
   const { items, totalItems } = await getProducts({ take: 24 });
 
@@ -44,7 +79,7 @@ async function Catalog() {
       ) : (
         <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 sm:gap-6 lg:grid-cols-4">
           {items.map((product) => (
-            <ProductCard key={product.id} product={product} />
+            <ProductCard key={product.id} product={product} locale={locale} />
           ))}
         </div>
       )}

package/templates/storefront/src/app/register/page.tsx

@@ -0,0 +1,54 @@
+import type { Metadata } from 'next';
+
+import { RegisterForm } from '../../components/account/RegisterForm';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+
+/**
+ * `/register` — where a shopper creates an account (#1471).
+ *
+ * The page renders a form and nothing else: it asks the shop API nothing on
+ * GET, so unlike `/verify` there is no request-time hole to stream, and unlike
+ * `/reset-password` there is no token in the URL to read. Everything that
+ * happens here happens on the SUBMIT, over the shopper's own websocket.
+ *
+ * Unlike the two account-LINK routes, this one IS locale-prefixable — a
+ * shopper addresses it, from a link on this storefront, rather than receiving
+ * it in a mail — so `register` is deliberately absent from the grammar's
+ * unprefixed set and `/de/register` serves the German render.
+ */
+
+const PAGE_TITLE = 'Create an account';
+
+/**
+ * Noindex via `NOINDEX_PATHS`: a form with no content of its own competes with
+ * nothing, and it is the same posture `/cart` and `/checkout` take.
+ *
+ * No alternates, despite the route existing in every language. Hreflang is a
+ * claim about which address of a cluster a crawler should prefer, and a page
+ * that has just declined to be indexed at all has no such preference to state;
+ * the empty map is what makes `buildAlternates` withhold the claim rather than
+ * this page hand-rolling a robots value of its own.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/register',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+export default async function RegisterPage() {
+  const { binding } = await getRequestLocale();
+
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      <RegisterForm locale={binding} />
+    </div>
+  );
+}

package/templates/storefront/src/app/reset-password/page.tsx

@@ -0,0 +1,60 @@
+import type { Metadata } from 'next';
+
+import { RequestPasswordResetForm } from '../../components/account/RequestPasswordResetForm';
+import { ResetPasswordForm } from '../../components/account/ResetPasswordForm';
+import { readLinkToken } from '../../lib/account/account-link';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../lib/seo/noindex';
+
+/**
+ * `/reset-password` — the page the platform's password-reset e-mail links to,
+ * and the place a shopper asks for that e-mail in the first place (#1472).
+ *
+ * ONE route, two modes, chosen by the URL's token:
+ *
+ *  - `?token=…` — set a new password. The token is spent by the SUBMIT, never
+ *    by the render: unlike verification, the shopper has something to type, so
+ *    consuming the token on arrival would burn it before they got the chance.
+ *  - no token — ask for a link. A shopper who lets one expire has nowhere else
+ *    to go, and sending them back to the mail that is already stale is a dead
+ *    end; the same address they were mailed at is all this form needs.
+ *
+ * Both modes render forms and nothing else, so unlike `/verify` there is no
+ * request-time hole to stream — the page reads the request and renders.
+ */
+
+const PAGE_TITLE = 'Reset your password';
+
+/** Noindex, and no alternates — for the reasons `/verify`'s metadata states. */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/reset-password',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+export default async function ResetPasswordPage({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  const [params, { binding }] = await Promise.all([searchParams, getRequestLocale()]);
+  const token = readLinkToken(params);
+
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      {token === null ? (
+        <RequestPasswordResetForm locale={binding} />
+      ) : (
+        <ResetPasswordForm token={token} locale={binding} />
+      )}
+    </div>
+  );
+}

package/templates/storefront/src/app/robots.ts

@@ -0,0 +1,69 @@
+import type { MetadataRoute } from 'next';
+
+import { NOINDEX_PATHS, NOINDEX_QUERY_KEYS } from '../lib/seo/noindex';
+import { getPublicOrigin } from '../lib/seo/public-origin';
+
+/**
+ * `robots.txt` (#1347, epic launch#54 W1-9) — the crawler-facing half of the
+ * indexability contract in `lib/seo/noindex.ts`.
+ *
+ * FORCE-DYNAMIC, and that is load-bearing rather than cautious. Next
+ * pre-renders metadata routes at build time by default, and a storefront is
+ * built once then run with its per-channel environment supplied afterwards. A
+ * build-time answer would freeze the BUILDER's environment — which never has a
+ * channel's public origin — into `Disallow: /` for every store shipped from
+ * that image, permanently, with no way to correct it short of a rebuild. The
+ * scaffold is frozen at provisioning time (#1041), so "permanently" is literal.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Infrastructure routes that are never a destination for a human or a crawler:
+ * the tracking relay, the error beacon, the SDK proxy and the health probe.
+ *
+ * Deliberately NOT derived from the locale grammar's `UNPREFIXED_FIRST_SEGMENTS`
+ * despite the overlap. That set answers "which first segments are not a
+ * language?" and correctly contains `sitemap.xml`, `robots.txt`, `_next` and
+ * `favicon.ico` — every one of which a crawler MUST be allowed to fetch.
+ * Sharing one list would make the next infrastructure route silently
+ * uncrawlable, or a crawlable asset silently unprefixed.
+ */
+const INFRASTRUCTURE_DISALLOW: readonly string[] = [
+  '/api/',
+  '/__fc/',
+  '/__forge_beacon',
+  '/ping',
+];
+
+/**
+ * Without a public origin the storefront asserts nothing, so `robots.txt`
+ * refuses the whole tree. With one, it mirrors the noindex set — the page
+ * rules are DERIVED from `noindex.ts` rather than restated, because a
+ * `robots.txt` that disagrees with the pages' own `robots` metadata is the
+ * exact drift this module exists to prevent.
+ *
+ * The `Sitemap:` line rides the origin BRANCH, not merely the origin value: the
+ * URL it names has to be absolute, and the document it points at is empty
+ * without an origin. Announcing an empty sitemap is a claim about the catalog;
+ * announcing nothing is the absence of one, which is all a deployment that has
+ * not been told its own address is entitled to say.
+ */
+export default function robots(): MetadataRoute.Robots {
+  const publicOrigin = getPublicOrigin();
+  if (publicOrigin === null) {
+    return { rules: { userAgent: '*', disallow: '/' } };
+  }
+
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: [
+        ...NOINDEX_PATHS,
+        ...INFRASTRUCTURE_DISALLOW,
+        ...NOINDEX_QUERY_KEYS.map((key) => `/*?${key}=`),
+      ],
+    },
+    sitemap: `${publicOrigin}/sitemap.xml`,
+  };
+}

package/templates/storefront/src/app/sitemap.ts

@@ -0,0 +1,106 @@
+import type { MetadataRoute } from 'next';
+
+import { getProductSeoEntries, getServedPageRoutes } from '../lib/forgecart';
+import { resolveChannelLocales } from '../lib/locale/channel-locales-loader';
+import { getPublicOrigin } from '../lib/seo/public-origin';
+import { readScaffoldedRoutes } from '../lib/seo/scaffolded-routes';
+import { createSitemapCache, sitemapWindowMs } from '../lib/seo/sitemap-cache';
+import {
+  MAX_SITEMAP_URLS,
+  STATIC_ROUTES,
+  collectProductSitemapUrls,
+  mergeScaffoldedRoutes,
+  pageSitemapRoutes,
+  sitemapBudgetWarning,
+  staticSitemapUrls,
+} from '../lib/seo/sitemap-entries';
+
+/**
+ * `sitemap.xml` (#1347, epic launch#54 W1-9) — the discovery half of the SEO
+ * contract, listing every URL this deployment is willing to be indexed at.
+ *
+ * FORCE-DYNAMIC for the same load-bearing reason as `robots.ts`: Next
+ * pre-renders metadata routes at build time, the storefront image is built
+ * once and handed its channel environment afterwards, and the scaffold is
+ * frozen at provisioning time (#1041). A build-time answer would freeze the
+ * BUILDER's empty environment — no origin, no channel, no catalog — into an
+ * empty sitemap for every store shipped from that image, permanently. The
+ * 60s window is held in-process by `createSitemapCache` for exactly the same
+ * reason ISR is refused here: `revalidate` would pre-render the first response
+ * at build time too, which is the identical failure wearing a TTL.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * An empty document without a public origin, and no `<lastmod>` claims — the
+ * same refusal `robots.ts` and every page's `robots` metadata make in that
+ * state. Every URL a sitemap lists is absolute, so a deployment with no origin
+ * has nothing truthful to put in one.
+ *
+ * A backend failure is deliberately NOT caught: an unreachable shop makes this
+ * route 5xx, which tells a crawler to come back. Serving an empty sitemap
+ * instead would assert that the catalog is empty — the one answer that is
+ * actively false, and the one a crawler would act on by dropping URLs.
+ */
+const cache = createSitemapCache(build, { ttlMs: sitemapWindowMs });
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  return cache.get();
+}
+
+/**
+ * The refusal is inside the window rather than guarding it, because the origin
+ * is memoized for the life of the process: an unconfigured deployment stays
+ * unconfigured until it restarts, so caching its empty answer cannot make it
+ * any staler than the memo already has.
+ */
+async function build(): Promise<MetadataRoute.Sitemap> {
+  const publicOrigin = getPublicOrigin();
+  if (publicOrigin === null) return [];
+
+  const { channel } = await resolveChannelLocales(null);
+  const { languageCodes, defaultLanguageCode } = channel;
+
+  // The template's own routes, every page scaffolded since, and every ACF page
+  // the shop says it currently SERVES (#1934). Read per build rather than at
+  // module load, so a page created a moment ago is in the document on the next
+  // window — the reason `createStorefrontPage` writes a row at all, and the
+  // reason the ACF feed is a live query rather than a file: an ACF page is
+  // published through the API and writes nothing to this pod's disk.
+  //
+  // PRECEDENCE falls out of the merge and is worth naming: the base table wins
+  // over both, and within the appended list the FIRST claimant of a path wins —
+  // so a code-scaffolded page at `/pages/x` outranks an ACF page at the same
+  // slug. That is also how Next routes them (a literal `app/pages/x/page.tsx`
+  // shadows the dynamic `[slug]`), so the document cannot disagree with the
+  // router about which page an address serves.
+  const [scaffolded, servedPageRoutes] = await Promise.all([
+    readScaffoldedRoutes(),
+    getServedPageRoutes(defaultLanguageCode),
+  ]);
+  const routes = mergeScaffoldedRoutes(STATIC_ROUTES, [
+    ...scaffolded,
+    ...pageSitemapRoutes(servedPageRoutes),
+  ]);
+  const staticUrls = staticSitemapUrls(languageCodes, defaultLanguageCode, publicOrigin, routes);
+  const productUrls = await collectProductSitemapUrls(
+    async (skip, take) => getProductSeoEntries(defaultLanguageCode, { skip, take }),
+    defaultLanguageCode,
+    publicOrigin,
+    Math.max(0, MAX_SITEMAP_URLS - staticUrls.length),
+  );
+
+  const urls = [...staticUrls, ...productUrls];
+
+  // The one place this template writes to the console, and it earns it: a
+  // catalog that outgrows a single XML sitemap would otherwise stop being
+  // submitted for indexing in complete silence, inside the feature whose whole
+  // job is getting pages indexed. There is no logger in a scaffolded storefront
+  // and no channelId to tag — only the channel token, which is a credential and
+  // must never reach a log — so the pod's stdout is the channel, and the 60s
+  // window bounds this to at most one line a minute.
+  const warning = sitemapBudgetWarning(urls.length);
+  if (warning !== null) console.warn(warning);
+
+  return urls;
+}