@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/lib/seo/public-origin.ts

@@ -0,0 +1,166 @@
+/**
+ * The storefront's public origin (#1347, epic launch#54 W1-9).
+ *
+ * This one value decides whether the deployment is ENTITLED to make claims to
+ * a search engine. A storefront reachable only at an ephemeral preview URL has
+ * no stable address to be canonical about, so every absolute claim it could
+ * emit — canonical, hreflang, sitemap entry — would name a host that stops
+ * existing when the pod is reaped. The posture that follows is "assert
+ * nothing": see `noindex.ts`, which reads this and nothing else to decide the
+ * deployment-wide floor.
+ *
+ * The value is supplied by `forgecart init` (`--public-origin`), which writes
+ * `FORGECART_PUBLIC_ORIGIN` for a published storefront and OMITS it for
+ * preview pods. Absence is therefore a real, expected, meaningful state — not
+ * a misconfiguration to warn about.
+ *
+ * ABSENT and REJECTED are different states and are reported differently
+ * (#1677). Both produce a null origin and therefore `Disallow: /`, and for a
+ * long time both did so in complete silence — so a deployment configured with,
+ * say, a scheme-less `DEPLOYMENT_URL_TEMPLATE` built, deployed, served 200s,
+ * rendered correctly to a human, and told every crawler not to index it, with
+ * no error anywhere. The first signal was an unexplained traffic collapse.
+ *
+ * The asymmetry that caused it: this module is a SECURITY boundary and must
+ * reject anything it cannot vouch for, while the OPERATOR needs to know their
+ * configuration was rejected. Silence served the first obligation and betrayed
+ * the second. The rejections below are unchanged — they were always correct —
+ * and a rejected value is now stated on stdout instead of being swallowed.
+ */
+
+/** Why a present value could not be used as a public origin. */
+export type PublicOriginRejection =
+  | 'not-a-url'
+  | 'unsupported-scheme'
+  | 'carries-path'
+  | 'carries-query-or-fragment';
+
+/**
+ * The three genuinely different states of this variable.
+ *
+ * A discriminated union rather than `string | null`, because the null was
+ * doing two incompatible jobs: "this is a preview deployment, as intended" and
+ * "your configuration is broken". Collapsing them is what made the second one
+ * invisible.
+ */
+export type PublicOriginResolution =
+  | { kind: 'absent' }
+  | { kind: 'ok'; origin: string }
+  | { kind: 'rejected'; raw: string; reason: PublicOriginRejection };
+
+/**
+ * Classify a raw `FORGECART_PUBLIC_ORIGIN`.
+ *
+ * Never throws: this runs inside `robots.txt` and every page's metadata, where
+ * a throw would surface as a 500 on the one route whose entire job is to answer
+ * conservatively — strictly worse than the `Disallow: /` a refusal produces.
+ *
+ * Rejected on purpose:
+ * - non-http(s) schemes — `javascript:` and `data:` in a canonical `<link>` or
+ *   a `Sitemap:` line are injection surfaces, not addresses;
+ * - anything carrying a path, query or fragment — an origin with a path
+ *   silently produces double-pathed canonicals (`https://x/shop/products` from
+ *   origin `https://x/shop`), which is a duplicate-content bug that looks
+ *   correct in review.
+ */
+export function resolvePublicOrigin(raw: string | undefined): PublicOriginResolution {
+  const trimmed = raw?.trim();
+  if (!trimmed) return { kind: 'absent' };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { kind: 'rejected', raw: trimmed, reason: 'not-a-url' };
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { kind: 'rejected', raw: trimmed, reason: 'unsupported-scheme' };
+  }
+  // Unreachable for http/https — they are WHATWG "special" schemes, for which
+  // an empty host is a parse failure that the catch above already took. Kept
+  // as a belt on a security boundary, and classified as malformed because that
+  // is what an http URL with no host is.
+  if (!parsed.host) return { kind: 'rejected', raw: trimmed, reason: 'not-a-url' };
+  // `new URL('https://x')` normalizes pathname to '/', so '/' is the only
+  // pathname a bare origin can have.
+  if (parsed.pathname !== '/') {
+    return { kind: 'rejected', raw: trimmed, reason: 'carries-path' };
+  }
+  if (parsed.search || parsed.hash) {
+    return { kind: 'rejected', raw: trimmed, reason: 'carries-query-or-fragment' };
+  }
+
+  return { kind: 'ok', origin: `${parsed.protocol}//${parsed.host}` };
+}
+
+/**
+ * The origin, or null when there is none to use.
+ *
+ * Kept as the shape every caller wants — `noindex.ts` and `alternates.ts` ask
+ * "do we have an address", not "why not". The classification above is for the
+ * one caller that has to REPORT, immediately below.
+ */
+export function parsePublicOrigin(raw: string | undefined): string | null {
+  const resolution = resolvePublicOrigin(raw);
+  return resolution.kind === 'ok' ? resolution.origin : null;
+}
+
+/** What an operator needs to hear, per rejection reason. */
+function rejectionDetail(reason: PublicOriginRejection): string {
+  switch (reason) {
+    case 'not-a-url':
+      // The scheme hint is safe to give unconditionally: every value this
+      // reason can describe fails to parse as an absolute URL, and every
+      // absolute URL this module would accept begins with one of those two
+      // schemes. It is also the likeliest cause by far — a deployment template
+      // written as a host pattern rather than a URL pattern.
+      return 'it is not a parseable absolute URL (an origin must begin with the http:// or https:// scheme)';
+    case 'unsupported-scheme':
+      return 'it has no http:// or https:// scheme (a bare host is not an origin)';
+    case 'carries-path':
+      return 'it carries a path — an origin is scheme + host only';
+    case 'carries-query-or-fragment':
+      return 'it carries a query or fragment — an origin is scheme + host only';
+  }
+}
+
+/**
+ * Cached because the origin is deployment identity: it cannot change without
+ * a new process, and every rendered route asks for it.
+ *
+ * Resolved LAZILY rather than at module load. A module-level constant is
+ * evaluated when the bundle is first imported, which for a `next build` can be
+ * build time — freezing whatever the builder's environment happened to hold
+ * into the shipped bundle. Storefronts are built once and run with per-channel
+ * env supplied later, so a build-time read would bake "no origin" into every
+ * published store permanently.
+ */
+let cached: { readonly value: string | null } | null = null;
+
+/**
+ * The deployment's public origin, or null when it has none.
+ *
+ * A REJECTED value is reported here, exactly once per process — the memo makes
+ * that free, and once is right: this is deployment identity, so repeating it
+ * per request would bury the line it is trying to surface. An ABSENT value
+ * says nothing, because a preview pod with no origin is working as designed
+ * and a warning there would train operators to ignore this channel.
+ *
+ * `console.error` and not a thrown error, for the reason the classifier above
+ * does not throw either: the storefront must keep serving. It just must stop
+ * doing so silently.
+ */
+export function getPublicOrigin(): string | null {
+  if (cached === null) {
+    const resolution = resolvePublicOrigin(process.env.FORGECART_PUBLIC_ORIGIN);
+    if (resolution.kind === 'rejected') {
+      console.error(
+        `[public-origin] FORGECART_PUBLIC_ORIGIN is set to ${JSON.stringify(resolution.raw)} but was REJECTED: ${rejectionDetail(resolution.reason)}. ` +
+          'This storefront will serve "Disallow: /" and every page will be noindex until it is corrected — the site stays reachable, but no search engine will index it.',
+      );
+    }
+    cached = { value: resolution.kind === 'ok' ? resolution.origin : null };
+  }
+  return cached.value;
+}

package/templates/storefront-shadcn/src/lib/seo/redirect-plan.ts

@@ -0,0 +1,86 @@
+import type { RedirectRule } from '../../seo/redirects';
+import { isUnprefixedPath, parseLocalePath } from '../locale/grammar';
+
+/**
+ * The rename-redirect rule (#1347, epic launch#54 W1-9).
+ *
+ * Separate from the table it reads (`src/seo/redirects.ts`) on purpose. That
+ * file is edited by a merchant and rewritten by the agent on every rename; if
+ * the matching logic lived beside the data, an edit meant to add one row could
+ * silently take the rule with it. Data there, machinery here, and the boundary
+ * is what makes an automated edit to that file structurally safe.
+ *
+ * Pure, like every other rule in this layer — the middleware imports
+ * `next/server` and is therefore unreachable by the template spec project, so
+ * a decision left in the middleware could only ever be exercised by booting a
+ * server. This is the same split `planLocaleRewrite` uses.
+ */
+
+/** How many links of a redirect chain are followed before giving up. */
+export const MAX_REDIRECT_HOPS = 8;
+
+/**
+ * Where this request should be sent, or null when it should be served.
+ *
+ * Returns the FINAL destination of a chain rather than the next link in it.
+ * `/a → /b → /c` answers one 308 to `/c`: each additional hop costs a
+ * round-trip, and search engines both dilute the signal they carry across a
+ * chain and stop following one entirely after a handful of links, so a chain
+ * served link-by-link quietly loses exactly what the redirect existed to save.
+ *
+ * A cycle resolves to null — the page is served (or 404s) instead. That is the
+ * strictly better failure: a browser caught in a redirect loop shows an error
+ * page for every URL in the cycle, while a missing redirect costs only the one
+ * URL that was renamed. The hop cap makes the same choice for a chain too long
+ * to be worth following.
+ */
+export function planRedirect(pathname: string, table: readonly RedirectRule[]): string | null {
+  // Infrastructure routes are not pages and must never be redirected: a
+  // merchant entry for `/robots.txt` or `/api/...` would break crawling or the
+  // SDK proxy, and nothing downstream would report it.
+  if (isUnprefixedPath(pathname)) return null;
+
+  const { localeCandidate, pathname: routePath } = parseLocalePath(pathname);
+
+  const seen = new Set<string>([routePath]);
+  let current = routePath;
+  for (let hop = 0; hop < MAX_REDIRECT_HOPS; hop += 1) {
+    const next = table.find((rule) => normalize(rule.from) === current);
+    if (!next) {
+      // Unmoved on the first look means there is nothing to do at all; unmoved
+      // later means the chain ended, and `current` is where it ended.
+      return current === routePath ? null : prefixed(current, localeCandidate);
+    }
+    const target = normalize(next.to);
+    if (seen.has(target)) return null;
+    seen.add(target);
+    current = target;
+  }
+  return null;
+}
+
+/**
+ * The redirect re-enters the language it left from.
+ *
+ * The candidate is re-attached unvalidated, deliberately: middleware is
+ * zero-fetch by contract and cannot know which languages the channel offers.
+ * `/zz/summer-sale` therefore redirects to `/zz/promotions/summer`, which the
+ * layout then 404s — the same answer `/zz/promotions/summer` would have given
+ * if it had been requested directly, which is the point. Validity is decided
+ * in one place, and it is not this one.
+ */
+function prefixed(path: string, localeCandidate: string | null): string {
+  return localeCandidate === null ? path : `/${localeCandidate}${path}`;
+}
+
+/**
+ * A table entry as an address, so `/summer-sale/` and `/summer-sale` are the
+ * same entry. Matching is otherwise EXACT — no prefixes, no patterns: a rule
+ * that matched `/summer-sale/tents` because `/summer-sale` moved would drag
+ * along URLs nobody decided to move.
+ */
+function normalize(path: string): string {
+  const trimmed = path.trim();
+  const rooted = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  return rooted.length > 1 && rooted.endsWith('/') ? rooted.slice(0, -1) : rooted;
+}

package/templates/storefront-shadcn/src/lib/seo/resolve-path.ts

@@ -0,0 +1,107 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+import { advertisedPathsByLocale, ownContentRow } from './sidecar';
+import type { SeoSidecar } from './sidecar';
+
+/**
+ * The language-first slug law for product URLs (#1347, epic launch#54 W1-9).
+ *
+ * Every product URL must end in one of four honest answers, and which one is
+ * decided HERE rather than in the route, so the rule is a table of vectors
+ * instead of a branch nobody can enumerate.
+ *
+ * The whole law rests on one backend guarantee (#1339): a product fetched
+ * through a locale's own client answers with THAT locale's current slug in
+ * `slug`, and `resolvedLanguageCode` names the language whose current *or
+ * previous* slug actually matched the lookup. So a stale slug, a renamed
+ * product's previous slug, and a request that used another language's slug all
+ * arrive here as the same observable fact — `product.slug` differs from what
+ * was asked for — and all three deserve the same answer: one permanent redirect
+ * to the address this locale actually uses.
+ *
+ * That collapse is deliberate. Treating them as three cases would mean three
+ * lookups of "which language was this slug from", and the backend has already
+ * done that work.
+ */
+
+/** One language's slug for a product. */
+export interface ProductTranslationRow {
+  languageCode: string;
+  slug: string;
+}
+
+/** The product fields the law reads — a structural subset of the SDK's product. */
+export interface ResolvableProduct {
+  /** The CURRENT slug in the requesting locale's language. */
+  slug: string;
+  /** Every language's slug for this product, translated or not. */
+  translations: readonly ProductTranslationRow[];
+  seo: SeoSidecar;
+}
+
+/**
+ * The languages that may be ADVERTISED for this product, mapped to their paths.
+ *
+ * A product's ADDRESS is earned per language — `translations` says a language
+ * has a SLUG — and the sidecar's intersection rule (`advertisedPathsByLocale`)
+ * keeps only the ones that also have CONTENT, so a slug-bearing fallback copy
+ * is never advertised as an hreflang alternate.
+ */
+export function productPathsByLocale(product: ResolvableProduct): Record<string, string> {
+  const addresses = Object.fromEntries(
+    product.translations.map((row) => [row.languageCode, `/products/${row.slug}`]),
+  );
+  return advertisedPathsByLocale(addresses, product.seo);
+}
+
+/** What the route must do with this URL. */
+export type PathResolution =
+  | { kind: 'ok'; indexable: boolean }
+  | { kind: 'redirect'; to: string }
+  | { kind: 'fallback' }
+  | { kind: 'notFound' };
+
+export interface ResolveProductPathInput {
+  /** The slug exactly as it appeared in the URL. */
+  requestedSlug: string;
+  /** The product as fetched through THIS locale's client, or null when absent. */
+  product: ResolvableProduct | null;
+  binding: LocaleBinding;
+}
+
+/**
+ * Decide the honest answer for a product URL.
+ *
+ * Ordered so that each arm can assume the ones above it did not fire.
+ */
+export function resolveProductPath({
+  requestedSlug,
+  product,
+  binding,
+}: ResolveProductPathInput): PathResolution {
+  // No product answered to this slug in any language — a real 404, not a
+  // rendered "not found" page at a 200. A crawler indexes a soft-404; it drops
+  // a real one.
+  if (!product) return { kind: 'notFound' };
+
+  // The locale addresses this product by a different slug than the one asked
+  // for. One redirect covers a stale slug, a renamed product's previous slug
+  // (#1339's `previousSlug`), and a request that used another language's slug:
+  // the backend already resolved which, and the answer is the same regardless.
+  if (product.slug !== requestedSlug) {
+    return { kind: 'redirect', to: localizedPath(`/products/${product.slug}`, binding) };
+  }
+
+  // No content of this language's own (`ownContentRow` — a missing row reads
+  // as untranslated) means the shopper is looking at a derived copy. It
+  // renders, but it makes no claims: noindex, no hreflang, no canonical.
+  // Indexing it would put near-duplicate copy in competition with the language
+  // that genuinely has the content.
+  const row = ownContentRow(product.seo, binding.locale);
+  if (row === null) return { kind: 'fallback' };
+
+  // Real content in this language. The merchant's own indexability choice is
+  // the last word, and it rides on the resolution rather than being re-derived
+  // by the caller — one lookup, one answer.
+  return { kind: 'ok', indexable: row.indexable };
+}

package/templates/storefront-shadcn/src/lib/seo/scaffolded-routes.ts

@@ -0,0 +1,83 @@
+import 'server-only';
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { SCAFFOLDED_ROUTES_DIR, parseScaffoldedRoute } from './sitemap-entries';
+import type { StaticRoute } from './sitemap-entries';
+
+/**
+ * Reads the rows scaffolded pages dropped into `src/seo/routes.d/` (#1347).
+ *
+ * Separate from `sitemap-entries.ts` because it touches the filesystem, and
+ * that module is imported by the template spec project — an `node:fs` read
+ * there would move the sitemap's rules out of the vector layer and into
+ * something only a running server can exercise. Rules there, IO here.
+ *
+ * A directory rather than a generated barrel file for the same reason it is a
+ * directory on the writing side: an import list would have to be read, edited
+ * and rewritten, which two concurrent scaffolds can do in an order that loses
+ * one of them. Reading a directory has no such step.
+ */
+
+/**
+ * Every scaffolded route, or an empty list.
+ *
+ * Never throws, and that is deliberate: this runs inside `sitemap.xml`, where
+ * the alternatives to an empty list are a 5xx (which tells a crawler to come
+ * back to a broken document) or a half-built sitemap presented as complete. A
+ * missing directory is the NORMAL state — a scaffold that has created no pages
+ * has none — so it is not even a warning.
+ *
+ * A fragment that does not parse is skipped and named on stdout. Skipping is
+ * the honest half: the file is written by another process and editable by
+ * hand, so a malformed one is a bug in the writer, and guessing what it meant
+ * would publish a URL nobody chose. Naming it is the other half — a route
+ * silently missing from the sitemap is exactly the failure this feature
+ * exists to prevent, so it must not be able to happen quietly.
+ */
+export async function readScaffoldedRoutes(): Promise<StaticRoute[]> {
+  const directory = join(process.cwd(), SCAFFOLDED_ROUTES_DIR);
+
+  let files: string[];
+  try {
+    files = (await readdir(directory)).filter((name) => name.endsWith('.json'));
+  } catch {
+    // Absent (nothing scaffolded yet) or unreadable. Both mean the same thing
+    // to a sitemap: there are no scaffolded routes to list.
+    return [];
+  }
+
+  // Async, and read in parallel, because this runs on a request path: a
+  // merchant with a few hundred scaffolded pages is a few hundred file reads,
+  // and doing them synchronously would block the event loop for every other
+  // request in flight. The 60s window makes it rare, not free.
+  const named = files.sort((a, b) => a.localeCompare(b));
+  const parsed = await Promise.all(named.map((name) => readOne(join(directory, name))));
+
+  const routes: StaticRoute[] = [];
+  for (const [index, route] of parsed.entries()) {
+    if (route === null) {
+      console.warn(
+        `[sitemap] ignoring ${SCAFFOLDED_ROUTES_DIR}/${named[index]} — it is not a {"path","indexable"} row, so the page it names is NOT in the XML sitemap.`,
+      );
+      continue;
+    }
+    routes.push(route);
+  }
+  return routes;
+}
+
+/**
+ * One fragment, or null when it is unusable for any reason — unreadable,
+ * not JSON, or not the shape. The caller reports; this only decides.
+ */
+async function readOne(path: string): Promise<StaticRoute | null> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  return parseScaffoldedRoute(parsed);
+}

package/templates/storefront-shadcn/src/lib/seo/sidecar.ts

@@ -0,0 +1,75 @@
+import type { PathsByLocale } from './alternates';
+
+/**
+ * What the per-language SEO sidecar says about an entity's COPIES (#1341,
+ * ACF pages #1375): which languages hold content of their own, and whether
+ * this locale's copy may be indexed.
+ *
+ * One rule for every entity that carries a sidecar. A product and an ACF page
+ * entry ask the same two questions of the same rows, and two spellings of the
+ * answer would let a product and a page disagree about what an untranslated
+ * language is — one advertising a fallback copy the other refuses to (#1375
+ * ruling Q6: pages take product parity).
+ *
+ * PURE, for the reason every module under `lib/seo/` is: the template-spec
+ * imports it by relative path from outside the scaffold, so nothing reachable
+ * from here may need the template's Next toolchain.
+ */
+
+/** One language's row in the sidecar, narrowed to what these claims read. */
+export interface SeoLanguageRow {
+  languageCode: string;
+  /** Whether this language has real content, as opposed to a derived fallback. */
+  translated: boolean;
+  /** The merchant's explicit indexability choice for this language. */
+  indexable: boolean;
+}
+
+/** An entity's sidecar, as far as these claims read it. */
+export interface SeoSidecar {
+  languages: readonly SeoLanguageRow[];
+}
+
+/**
+ * This locale's row when the locale holds content of its own, or null when the
+ * shopper is looking at a derived fallback copy — real content in another
+ * language, shown here so the URL is not a dead end.
+ *
+ * A MISSING row is treated exactly like `translated: false`. The sidecar is
+ * supposed to carry one entry per channel language, so absence means the
+ * sidecar and the channel disagree — and the safe reading of a disagreement
+ * is the one that makes no claim.
+ */
+export function ownContentRow(seo: SeoSidecar, locale: string): SeoLanguageRow | null {
+  const row = seo.languages.find((entry) => entry.languageCode === locale);
+  return row?.translated ? row : null;
+}
+
+/**
+ * The languages that may be ADVERTISED for this entity, mapped to their paths:
+ * every language that has an address in `addresses` AND content of its own.
+ *
+ * The intersection of two different facts, and taking either alone is a bug.
+ * An address says the language can be REACHED — a product's per-language slug,
+ * or a page route that exists in every language the channel offers; the
+ * sidecar's `translated` says the language has CONTENT. A language can have the
+ * first without the second — that is exactly the fallback copy — and
+ * advertising it as an hreflang alternate would point a crawler at a derived
+ * page and pull it into a reciprocal set it does not belong to.
+ *
+ * `indexable: false` does NOT remove a language: the merchant suppressing a
+ * page they own leaves the translation in place, so its siblings must keep
+ * naming it or the cluster's reciprocity breaks. Indexability is `noindex.ts`'s
+ * job, not this map's. The order is the addresses' own.
+ */
+export function advertisedPathsByLocale(
+  addresses: PathsByLocale,
+  seo: SeoSidecar,
+): Record<string, string> {
+  const translated = new Set(
+    seo.languages.filter((row) => row.translated).map((row) => row.languageCode),
+  );
+  return Object.fromEntries(
+    Object.entries(addresses).filter(([languageCode]) => translated.has(languageCode)),
+  );
+}

package/templates/storefront-shadcn/src/lib/seo/site-verification.ts

@@ -0,0 +1,98 @@
+import 'server-only';
+
+import { cache } from 'react';
+
+import { getShopClient } from '../forgecart';
+import type { SiteVerificationMeta } from './metadata';
+
+/**
+ * What the channel's SEO providers need this storefront to serve (#1530).
+ *
+ * A provider proves the merchant owns this address by asking them to place a
+ * token on it. The platform mints that token per account and per origin, and
+ * this read is the storefront's half of the handshake: it asks the shop API
+ * what to serve, and `metadata.ts` turns each descriptor into one
+ * `<meta name content>` tag. Nothing here knows which provider minted what —
+ * the NAME arrives in the descriptor, so a second provider is a server change
+ * and no template change at all.
+ *
+ * Only `META` placements are served. The mechanism rides in the descriptor
+ * precisely so that a provider verifying some other way — a DNS record, a file
+ * at a path this template does not route — cannot have its token silently
+ * rendered as a meta tag, which would be a placement that looks made and is
+ * not.
+ *
+ * PER REQUEST, and no further. React's `cache()` collapses the callers of one
+ * render into a single read; there is deliberately no TTL and no process memo
+ * above it. A verifier makes ONE fetch, and a token re-minted while a replica
+ * still serves a cached copy of the old one is a verification that fails with
+ * every part of the system reporting health — the same reason
+ * `sitemap-cache.ts`'s window is safe (a stale URL list costs a crawl) and one
+ * here would not be.
+ *
+ * Failure is ALWAYS an empty list, never a throw. This read happens inside the
+ * root layout's `generateMetadata`, structurally outside every Suspense
+ * boundary (D8), so a throw here is a 500 on every route of the store — and
+ * what is lost instead is one meta tag whose absence the platform already
+ * detects and retries on its next sync. An unconfigured scaffold reaches the
+ * same arm: `getShopClient()` throws when `.env` carries no coordinates, and
+ * the prewarm contract says a storefront with no configuration must SERVE.
+ */
+
+/** The answer whenever there is nothing honest to serve. */
+const NONE: readonly SiteVerificationMeta[] = [];
+
+/**
+ * The one mechanism this template can satisfy — a tag in the document it
+ * renders. Compared against the descriptor's own value rather than assumed.
+ */
+const META_METHOD = 'META';
+
+/**
+ * How long the document shell may wait for this read.
+ *
+ * The same bound, for the same reason, as the channel read in
+ * `locale/channel-locales-loader.ts`: the shell has no Suspense boundary above
+ * it, so an unbounded wait holds the whole document open with nothing to time
+ * it out. Past this the storefront serves without the tag, which is the lesser
+ * of the two failures by a wide margin.
+ */
+const VERIFICATION_READ_TIMEOUT_MS = 2_000;
+
+/**
+ * The placements this storefront must serve, for THIS request.
+ *
+ * Read through the generated SDK like every other shop-API call in the
+ * template — there are no hand-written query documents here, which is what
+ * keeps the storefront's reads and the API's schema from drifting apart.
+ *
+ * The request's own client is used rather than one pinned to the channel
+ * default: the answer is the same in every language, so the cheaper of two
+ * correct options wins, and that is the socket this render already has open.
+ */
+export const getSiteVerifications = cache(async (): Promise<readonly SiteVerificationMeta[]> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      readPlacements(),
+      new Promise<readonly SiteVerificationMeta[]>((resolve) => {
+        timer = setTimeout(() => {
+          resolve(NONE);
+        }, VERIFICATION_READ_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    // The template's sanctioned catch: an external SDK call, wrapped at its
+    // call site, exactly as `forgecart.ts#runAccountOperation` and
+    // `shop-session.ts` do. Nothing is swallowed that anyone here could act on
+    // — the platform's sync ladder is what observes an unserved placement.
+    return NONE;
+  } finally {
+    clearTimeout(timer);
+  }
+});
+
+async function readPlacements(): Promise<readonly SiteVerificationMeta[]> {
+  const { seoSiteVerifications } = await (await getShopClient()).seo.seoSiteVerifications();
+  return seoSiteVerifications.filter((placement) => placement.method === META_METHOD);
+}