@forgecart/cli 2.202609221621.0 → 2.202609282317.0

package/templates/storefront/src/app/%5F%5Fforge_beacon/route.ts

@@ -25,12 +25,55 @@
 
 const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
 
+/**
+ * The revision the reporting page was SERVED at, lifted out of the forwarded
+ * body for the log line below, or `null` when the report is untagged.
+ *
+ * Reads the body it is ALREADY forwarding verbatim rather than re-deriving
+ * anything: the value was stamped into the document at render time, and this
+ * handler is a forwarder, not a second opinion. The parse is guarded because a
+ * malformed body must not change what this route does — the forward still
+ * happens and the client still gets its 204, exactly as before. `JSON.parse` is
+ * the one throw on this path and it carries no code to classify, which is why it
+ * is caught here and nowhere else (`instrumentation.ts` swallows its own boot
+ * failure in the same template for the same reason); judging the payload stays
+ * the receiver's job.
+ */
+function servedRevision(body: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const value = (parsed as { atRevision?: unknown }).atRevision;
+    if (typeof value !== 'string' || value.length === 0) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
 export async function POST(request: Request): Promise<Response> {
   if (process.env.NODE_ENV !== 'development') {
     return new Response(null, { status: 404 });
   }
 
   const body = await request.text();
+  // Make the dev-server's output ring revision-attributable (#847): this line is
+  // written to the ring the supervisor retains and `TailServerLogs` serves, so a
+  // human or the recovery brain reading the ring can tell WHICH tree a
+  // browser-surfaced crash belongs to instead of guessing from timing.
+  //
+  // It deliberately carries the revision and NOTHING ELSE — no message, no stack,
+  // no route. The ambient scanner matches dev-server output case-insensitively
+  // against RUNTIME_ERROR_PATTERNS ('error:', 'typeerror', 'unhandled', …;
+  // `runtime-error-scanner.types.ts`), so echoing the reported message here would
+  // put the crash text INTO the stream that scanner reads and fold a second,
+  // independent ambient error for the very report already on its way to the
+  // receiver — a self-inflicted double-fire. An untagged report stays silent
+  // rather than logging a placeholder, which keeps today's output byte-identical
+  // for every producer that does not stamp (the server `onRequestError` path
+  // never reaches this route at all — it POSTs the receiver directly).
+  const revision = servedRevision(body);
+  if (revision !== null) console.log(`[forge-beacon browser rev=${revision}]`);
   // Forward server-side to the loopback receiver. A delivery failure is swallowed —
   // the beacon is a best-effort backstop, never a hard dependency of the page — but
   // the client still gets a clean 204 so it never retries against a flapping pod.

package/templates/storefront/src/app/layout.tsx

@@ -10,7 +10,9 @@ import { LocaleLink } from '../components/LocaleLink';
 import { CartProvider } from '../lib/cart-context';
 import { getRequestLocale } from '../lib/locale/request-binding';
 import { shellMetadata } from '../lib/seo/metadata';
+import { getSiteVerifications } from '../lib/seo/site-verification';
 import { getBrowserShopConfig } from '../lib/shop-config';
+import { FORGE_REVISION_META, resolveLiveRevision } from '../server/forge/live-revision';
 
 import './globals.css';
 
@@ -34,10 +36,43 @@ import './globals.css';
  * It reads the SAME resolution the layout body reads below — React's request
  * cache makes `getRequestLocale()` one channel read per request no matter how
  * many callers there are, so the floor costs nothing extra.
+ *
+ * The site-verification placements (#1530) are read on the same request cache
+ * and handed to the SAME composer, so `lib/seo/metadata.ts` stays the only
+ * thing in this template that turns a placement into a `<meta>`: the
+ * alternative — a hand-written tag in the markup below — would be a second
+ * emitter with its own idea of when a placement is servable. They ride the
+ * FLOOR rather than a route, because the verifier chooses which page it fetches
+ * and a tag on only some of them is a verification that works until it does not.
+ *
+ * It also carries the DEV-ONLY revision stamp (#847). The tag has to be written
+ * where the page is RENDERED, because that is the only moment that knows which
+ * tree the shopper is actually looking at: the browser beacon reads it back at
+ * throw time, so a promote landing between serve and throw can no longer make
+ * the report blame the new revision for the old one's crash. It rides
+ * `generateMetadata` rather than a `<meta>` in the JSX below because arbitrary
+ * head tags are what `other` is for, and the shell's own metadata contract then
+ * stays untouched — the stamp is spread ON TOP of `shellMetadata`'s answer and
+ * adds a key no SEO surface reads.
+ *
+ * Dev-gated at this call site, like every other file in the beacon path: the
+ * literal `NODE_ENV` check is what lets a production build eliminate the
+ * resolution entirely, so a deployed storefront emits no tag and leaks no
+ * revision. Unresolvable is a NORMAL answer and means no tag — the report then
+ * arrives untagged and the receiver keeps its existing behaviour.
  */
 export async function generateMetadata(): Promise<Metadata> {
   const { shopName, channelResolved } = await getRequestLocale();
-  return shellMetadata({ shopName, channelResolved });
+  const siteVerifications = await getSiteVerifications();
+  const shell = shellMetadata({ shopName, channelResolved, siteVerifications });
+  if (process.env.NODE_ENV !== 'development') return shell;
+  const revision = resolveLiveRevision();
+  if (revision === null) return shell;
+  // MERGED into the shell's `other`, never written over it: that key carries the
+  // site-verification placements (#1530), and a storefront pod serves through
+  // `npm run dev`, so an overwrite here would strip the provider's tag from
+  // every page its verifier can fetch.
+  return { ...shell, other: { ...shell.other, [FORGE_REVISION_META]: revision } };
 }
 
 /**

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

@@ -2,6 +2,7 @@ import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 import { cache } from 'react';
 
+import { pageContentClaims } from '../../../lib/content/page-metadata';
 import { PageFields } from '../../../lib/content/render-fields';
 import { resolvePage } from '../../../lib/content/resolve-page';
 import {
@@ -11,7 +12,6 @@ import {
   type PageGroup,
 } from '../../../lib/forgecart';
 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';
 import { PAGE_ROUTE_PREFIX } from '../../../lib/seo/sitemap-entries';
@@ -53,14 +53,16 @@ const pageForRequest = cache(
 );
 
 /**
- * A page's indexability comes from the same resolution the route acts on, so
- * the tag and the status can never disagree about what this URL is.
+ * A page's metadata comes from the same resolution the route acts on, so the
+ * head and the status can never disagree about what this URL is.
  *
- * The title is the merchant's own page name — the one piece of per-page SEO
- * that exists today. A page has no per-language SEO sidecar yet (#1375), so
- * there is no description, no social image, and the alternate set is the
- * structural one: a page route is the SAME address in every language the
- * channel offers, exactly like `/products`.
+ * Its CONTENT claims — title, description, social card, alternates and
+ * indexability — are the record's per-language SEO sidecar (#1375), decided in
+ * `lib/content/page-metadata.ts` by the rules the product route uses: the
+ * definition's `seoSources` mapping and the merchant's stored overrides arrive
+ * already resolved into each language, and a language with no copy of its own
+ * renders as a fallback that claims nothing (noindex, no canonical, never an
+ * hreflang alternate). This file only dispatches.
  */
 export async function generateMetadata({
   params,
@@ -73,16 +75,15 @@ export async function generateMetadata({
     await Promise.all([params, searchParams, getRequestLocale()]);
   const { group, entries } = await pageForRequest(slug);
   const resolution = resolvePage({ requestedRoute: slug, group, entries });
+  const pathname = `${PAGE_ROUTE_PREFIX}/${slug}`;
 
   return routeMetadata({
     binding,
     shopName,
     channelResolved,
-    pathname: `${PAGE_ROUTE_PREFIX}/${slug}`,
-    pathsByLocale: staticPathsByLocale(languageCodes, `${PAGE_ROUTE_PREFIX}/${slug}`),
+    pathname,
     searchParams: resolvedSearchParams,
-    title: resolution.kind === 'ok' ? resolution.group.name : null,
-    contentIndexable: resolution.kind === 'ok',
+    ...pageContentClaims(resolution, { locale: binding.locale, languageCodes, pathname }),
   });
 }
 

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

@@ -61,11 +61,11 @@ const productForRequest = cache(async (slug: string) => getProductBySlug(slug));
  * 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.
+ * Like an ACF page's (`/pages/<route>`, #1375), this route's 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,

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

@@ -18,7 +18,8 @@ import type { RouteSearchParams } from '../../lib/seo/noindex';
  * `<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.
+ * about — products and the merchant's own ACF pages — take theirs from the
+ * localized SEO sidecar.
  */
 export async function generateMetadata({
   searchParams,

package/templates/storefront/src/components/ForgeErrorBeacon.tsx

@@ -23,6 +23,14 @@ import { useEffect } from 'react';
  * the page's own error boundary still renders. The full
  * browser → API route → pod → supervisor-fold path is exercised at the e2e layer,
  * not in this template.
+ *
+ * Every report carries the revision the PAGE WAS SERVED AT (#847), read out of the
+ * `forge-revision` meta tag the server wrote into this document rather than looked
+ * up fresh at throw time. That distinction is the entire point: a fresh lookup would
+ * answer whatever is live NOW, so a promote landing between serve and throw would
+ * make this report blame the new revision for the old one's crash — and the pod's
+ * same-revision fold would then mark a healthy tree DEGRADED. The tag cannot drift,
+ * because it was rendered with the markup that broke.
  */
 export function ForgeErrorBeacon() {
   useEffect(() => {
@@ -30,12 +38,35 @@ export function ForgeErrorBeacon() {
       return;
     }
 
+    /**
+     * The revision this document was SERVED at, or `undefined` when the server
+     * did not stamp one (production, or a pod that cannot resolve it — both
+     * normal). `'forge-revision'` is repeated here as a literal on purpose: the
+     * resolver lives in `src/server/forge/live-revision.ts`, which a client
+     * component must not import, so this is the same repeated-contract shape the
+     * `/__forge_beacon` URL already uses across this feature's producers.
+     *
+     * An absent tag, an absent attribute and an empty value all answer
+     * `undefined`, which `JSON.stringify` then omits from the body entirely —
+     * so an unstamped page sends exactly the payload it sent before, and the pod
+     * keeps its existing untagged behaviour instead of receiving a blank string
+     * it would have to interpret.
+     */
+    const readServedRevision = (): string | undefined => {
+      const content = document
+        .querySelector('meta[name="forge-revision"]')
+        ?.getAttribute('content');
+      if (!content) return undefined;
+      return content;
+    };
+
     const send = (message: string, stack?: string) => {
       const body = JSON.stringify({
         message,
         stack,
         route: window.location.pathname,
         source: 'browser',
+        atRevision: readServedRevision(),
       });
       // Same-origin POST; keepalive lets it survive a navigation/unload. A failed
       // delivery is intentionally swallowed — the beacon is a backstop signal, not

package/templates/storefront/src/instrumentation.ts

@@ -27,6 +27,11 @@
  * The hook NEVER throws out of itself: a failed delivery is swallowed (the beacon is a
  * best-effort backstop, never a hard dependency of the request), so a flapping receiver
  * can never mask or replace the underlying request error Next is already reporting.
+ *
+ * The error's own `code` rides along verbatim — a fact, never a verdict: a request
+ * that races a recompile evaluates Turbopack's stub for a module that no longer parses
+ * and throws `code: 'MODULE_UNPARSABLE'`, and the receiver reads that code to leave a
+ * BUILD failure to the build detectors instead of folding it as a render crash.
  */
 
 const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
@@ -86,10 +91,11 @@ export async function onRequestError(
     return;
   }
 
-  const err = error as { message?: string; digest?: string } | undefined;
+  const err = error as { message?: string; digest?: string; code?: unknown } | undefined;
   const body = JSON.stringify({
     message: typeof err?.message === 'string' ? err.message : String(error),
     digest: typeof err?.digest === 'string' ? err.digest : undefined,
+    code: typeof err?.code === 'string' ? err.code : undefined,
     route: request.path,
     routeType: context.routeType,
     source: 'server',

package/templates/storefront/src/lib/content/page-metadata.ts

@@ -0,0 +1,113 @@
+import { staticPathsByLocale } from '../seo/alternates';
+import { entityMetadata } from '../seo/metadata';
+import type { MetadataInput, SeoMetaRow } from '../seo/metadata';
+import { advertisedPathsByLocale, ownContentRow } from '../seo/sidecar';
+import type { SeoLanguageRow } from '../seo/sidecar';
+import type { PageResolution } from './resolve-page';
+
+/**
+ * What a page URL claims about its own CONTENT (#1375, epic launch#54 D11 as
+ * amended by ruling ANSWER-1547Z) — the half of `/pages/<route>`'s metadata the
+ * page decides, as a value the route spreads into `routeMetadata`.
+ *
+ * Every claim is read off the page record's per-language SEO sidecar, through
+ * the SAME rules the product route uses, so a page and a product can never
+ * disagree about what a language without its own copy is (ruling Q6: product
+ * parity):
+ *
+ *  - title, description and social image come from `entityMetadata` — the
+ *    sidecar's row for this locale, the title falling back to the page
+ *    definition's own name, and the social card armed only by a STORED image
+ *    (a page's mapped image never arms it);
+ *  - the alternates cluster is the route's address in every language the
+ *    channel offers, narrowed to the languages that hold content of their own
+ *    (`advertisedPathsByLocale`) — an untranslated language is never an
+ *    hreflang alternate, and its own copy claims no canonical;
+ *  - indexability is the merchant's choice for a language with its own copy,
+ *    and `false` for a derived fallback (`ownContentRow`).
+ *
+ * PURE BY CONTRACT, for the reason `resolve-page.ts` is: the template-spec
+ * imports it by relative path, which is what makes these claims a table of
+ * vectors rather than something only a running pod can exercise. The inputs
+ * are structural for the same reason — the generated query types satisfy them,
+ * so the scaffold's own compiler proves the assignment.
+ */
+
+/** One language of a page record's sidecar, as these claims read it. */
+export type PageSeoRow = SeoLanguageRow & SeoMetaRow;
+
+/** The definition fields these claims read. */
+export interface ClaimingPageGroup {
+  /** The merchant's name for the page — the title when the sidecar names none. */
+  readonly name: string;
+}
+
+/**
+ * The record fields these claims read.
+ *
+ * The sidecar is optional AND nullable because the generated selection is: the
+ * shop API answers `seo: null` for a definition that is not a page kind. A
+ * resolution that reached its `ok` arm has already proven the definition IS a
+ * page, so a null here means the API and the definition disagree — read, like a
+ * missing language row, as "no language has content of its own".
+ */
+export interface ClaimingPageEntry {
+  readonly seo?: { readonly languages: readonly PageSeoRow[] } | null;
+}
+
+/** Where the page is being rendered, and every language its route exists in. */
+export interface PageClaimsContext {
+  /** The locale this page is being rendered in. */
+  locale: string;
+  /** Every language the channel offers — the languages a page ROUTE exists in. */
+  languageCodes: readonly string[];
+  /** The locale-STRIPPED address of this page (`/pages/<route>`). */
+  pathname: string;
+}
+
+/** The content half of a page's `MetadataInput`, every key decided. */
+export type PageContentClaims = Required<
+  Pick<
+    MetadataInput,
+    'pathsByLocale' | 'title' | 'description' | 'socialImage' | 'contentIndexable'
+  >
+>;
+
+/** The sidecar a record without one is read as: no language holds its own copy. */
+const NO_SIDECAR: NonNullable<ClaimingPageEntry['seo']> = { languages: [] };
+
+/**
+ * A URL that is not a page claims nothing about content: no name of its own, no
+ * alternates, and not indexable — the refusal the product route states for a
+ * missing product, stated here rather than left to whatever Next does with the
+ * head of a page that answers 404.
+ */
+const NOT_FOUND_CLAIMS: PageContentClaims = {
+  pathsByLocale: {},
+  title: null,
+  description: null,
+  socialImage: null,
+  contentIndexable: false,
+};
+
+/**
+ * Decide the content claims of one page URL from the resolution the route acts
+ * on — the same value that decides its status, so the head and the response
+ * can never disagree about what the URL is.
+ */
+export function pageContentClaims(
+  resolution: PageResolution<ClaimingPageGroup, ClaimingPageEntry>,
+  { locale, languageCodes, pathname }: PageClaimsContext,
+): PageContentClaims {
+  if (resolution.kind === 'notFound') return NOT_FOUND_CLAIMS;
+
+  const seo = resolution.entry.seo ?? NO_SIDECAR;
+  const entity = entityMetadata({ name: resolution.group.name, seo }, locale);
+  return {
+    pathsByLocale: advertisedPathsByLocale(staticPathsByLocale(languageCodes, pathname), seo),
+    title: entity.title,
+    description: entity.description,
+    socialImage: entity.socialImage,
+    contentIndexable: ownContentRow(seo, locale)?.indexable ?? false,
+  };
+}

package/templates/storefront/src/lib/forgecart.ts

@@ -133,9 +133,9 @@ import type {
   RefreshShippingRateGroupsMutation,
   SeoEntriesQuery,
   ShopEligiblePaymentProvidersQuery,
-  ShopEntriesQuery,
   ShopOrderByCodeQuery,
   ShopPageByRouteQuery,
+  ShopPageEntriesQuery,
   ShopProductQuery,
 } from '@forgecart/sdk/shop';
 
@@ -163,8 +163,12 @@ export type SeoEntryFeedPage = SeoEntriesQuery['seoEntries'];
 export type PageGroup = NonNullable<ShopPageByRouteQuery['pageByRoute']>;
 /** One field definition of a page — the label and the identity of a value. */
 export type PageFieldDefinition = PageGroup['fieldDefinitions'][number];
-/** One record of a page, with its values and repeater rows. */
-export type PageEntry = ShopEntriesQuery['entries']['items'][number];
+/**
+ * One record of a page, with its values, its repeater rows and its per-language
+ * SEO sidecar (#1375) — the page's title, description, indexability and
+ * alternates are read off `seo` by `lib/content/page-metadata.ts`.
+ */
+export type PageEntry = ShopPageEntriesQuery['entries']['items'][number];
 /** One stored value, discriminated by `__typename` over the ACF field types. */
 export type PageFieldValue = PageEntry['fields'][number];
 
@@ -298,14 +302,17 @@ export async function getPageByRoute(route: string): Promise<PageGroup | null> {
 }
 
 /**
- * The record a page URL serves, as a list of at most one (#1934).
+ * The record a page URL serves, as a list of at most one (#1934), with its SEO
+ * sidecar (#1375).
  *
  * `take: 1` because a route is ONE address; `createdAt ASC` because that makes
  * it the page's ORIGINAL record. The shop API's own default is `createdAt
  * DESC`, and inheriting it would mean that adding a second record to a live
  * page silently REPLACES what the URL has been serving — a content change
  * nobody asked for, made by a create. Ascending is a stable answer: the page a
- * merchant published stays the page at that URL.
+ * merchant published stays the page at that URL. The bound also prices the
+ * sidecar: `seo` costs one per-language resolve per returned record, which is
+ * why it rides this one-record read (`ShopPageEntries`) and never a listing.
  *
  * The list may come back EMPTY, and that is the feature's whole 404 arm: every
  * storefront read is fenced to published content, so a page whose only records
@@ -315,7 +322,7 @@ export async function getPageByRoute(route: string): Promise<PageGroup | null> {
 export async function getPageEntries(definitionCode: string): Promise<PageEntry[]> {
   const { entries } = await (
     await getShopClient()
-  ).acf.shopEntries({
+  ).acf.shopPageEntries({
     definitionCode,
     options: { take: 1, sort: [{ field: 'createdAt', direction: 'ASC' }] },
   });

package/templates/storefront/src/lib/seo/alternates.ts

@@ -98,7 +98,10 @@ export function buildAlternates({
  * Structural routes are not translated content: `/products` is the same route
  * in every cluster, so every offered language has it and each one is a genuine
  * alternate. That is the opposite of a product, where membership has to be
- * earned per language (see `productPathsByLocale`).
+ * earned per language (see `productPathsByLocale`). An ACF page sits between
+ * the two: its route is this same address in every language, but its content
+ * is translated, so the map is narrowed by the page's sidecar before it is
+ * advertised (`advertisedPathsByLocale`, #1375).
  */
 export function staticPathsByLocale(
   languageCodes: readonly string[],

package/templates/storefront/src/lib/seo/metadata.ts

@@ -39,11 +39,42 @@ import { getPublicOrigin } from './public-origin';
  *    whose fields mean the opposite is a defect waiting to be written.
  */
 
+/**
+ * One site-verification placement, narrowed to what a `<meta>` tag needs
+ * (#1530).
+ *
+ * A structural subset of the SDK's `SeoSiteVerification`, for the same reason
+ * `SeoMetaRow` narrows `SeoMetaLanguage`: this module has to stay reachable
+ * from the template-spec project, which imports it by relative path and so
+ * cannot follow anything that pulls in `next` or the SDK. The request-time read
+ * that produces these lives in `site-verification.ts`, which can.
+ *
+ * `name` is the PROVIDER's own, always. A storefront that spelled one vendor's
+ * meta name into its source would serve that vendor and silently ignore every
+ * other one the merchant connects — and would have to be edited again for the
+ * next, which is precisely the thing a descriptor exists to avoid.
+ */
+export interface SiteVerificationMeta {
+  name: string;
+  content: string;
+}
+
+/**
+ * Bare `<meta name content>` pairs, keyed by name.
+ *
+ * The value is a LIST because Next emits one tag per element: two placements
+ * that happen to share a name — the same provider under two accounts — both
+ * reach the document, where a plain string would have kept whichever was folded
+ * last and dropped the other without a trace.
+ */
+export type SiteVerificationTags = Record<string, string[]>;
+
 /** The floor the root layout emits — no route, so no route-specific claims. */
 export interface ShellMetadata {
   title: string;
   description: string;
   robots?: RobotsDirective;
+  other?: SiteVerificationTags;
 }
 
 /**
@@ -76,11 +107,17 @@ export interface PageMetadata {
   alternates?: Alternates;
   openGraph?: OpenGraphMetadata;
   twitter?: TwitterMetadata;
+  other?: SiteVerificationTags;
 }
 
 export interface ShellMetadataInput extends DeploymentPosture {
   /** The merchant's shop name, or null/empty when unset. */
   shopName?: string | null;
+  /**
+   * What the channel's SEO providers need this deployment to serve (#1530),
+   * read per request by `site-verification.ts`. Absent or empty emits nothing.
+   */
+  siteVerifications?: readonly SiteVerificationMeta[];
 }
 
 export interface MetadataInput extends DeploymentPosture {
@@ -105,6 +142,18 @@ export interface MetadataInput extends DeploymentPosture {
   socialImage?: string | null;
   /** The content's own indexability — see `noindex.ts`. */
   contentIndexable?: boolean;
+  /**
+   * The same placements the shell emits (#1530) — for a route that has a
+   * reason of its own to set `other`.
+   *
+   * Next merges a page's metadata OVER the layout's one key at a time, so a
+   * page that sets `other` at all REPLACES the floor's, verification tags
+   * included. Passing them here is how such a route keeps them. Every route
+   * this template ships sets no `other` and therefore passes nothing, and
+   * inherits the shell's — absent means inherit, exactly as it does for
+   * `description` and `robots` above.
+   */
+  siteVerifications?: readonly SiteVerificationMeta[];
 }
 
 /**
@@ -119,12 +168,19 @@ export interface SeoMetaRow {
   description?: string | null;
   /** Armed exactly when a social image is STORED — never derived. */
   socialEnabled?: boolean;
+  /**
+   * The stored social image, else an ACF page entry's MAPPED image (#1375).
+   * Not an opt-in by itself: a mapped image arrives here with the flag down.
+   */
   socialImage?: { preview: string } | null;
 }
 
 /** An entity that carries a per-language SEO sidecar. */
 export interface EntityMetadataSource {
-  /** The entity's own display name, already in the request's language. */
+  /**
+   * The entity's own display name — a product's, already in the request's
+   * language, or an ACF page definition's.
+   */
   name: string;
   seo: { languages: readonly SeoMetaRow[] };
 }
@@ -139,19 +195,24 @@ export interface EntityMetadata {
 /**
  * The sidecar's answer for one locale.
  *
- * `title` falls back to the entity's own name rather than to nothing: the
- * sidecar's derived default IS the translated name, so a null title means the
- * sidecar had nothing to say, not that the page has no name. `description`
- * does NOT fall back to the entity's body — a product description is rich text
- * from the dashboard, and putting raw HTML in a `<meta name="description">` is
- * how a store ends up with `<p>` in its search results. The sidecar already
- * derives a first-sentence description when the merchant sets none; if even
- * that is absent there is nothing honest to emit.
+ * `title` falls back to the entity's own name rather than to nothing: a null
+ * title means the sidecar had nothing to say — a product's derived default IS
+ * its translated name, and an ACF page whose definition maps no title source
+ * derives none (#1375) — not that the page has no name. `description` does NOT
+ * fall back to the entity's body — a product description is rich text from the
+ * dashboard, and putting raw HTML in a `<meta name="description">` is how a
+ * store ends up with `<p>` in its search results. The sidecar already derives
+ * one wherever an honest source exists (a product's first sentence, a page's
+ * mapped description or excerpt); if even that is absent there is nothing
+ * honest to emit, and the page inherits the shell's.
  *
- * The social image requires BOTH the armed flag and an actual image. They are
- * supposed to agree — `socialEnabled` is defined as "a social image is stored"
- * — but a storefront that assumes an invariant it cannot enforce is one API
- * change away from emitting an `og:image` with no URL.
+ * The social image requires BOTH the armed flag and an actual image, and the
+ * flag is the opt-in. For a product the two agree by construction, but an ACF
+ * page entry's row legitimately carries its MAPPED image with the flag down
+ * (#1375: a mapped image fills the image slot and never arms social) — and even
+ * where they are supposed to agree, a storefront that assumes an invariant it
+ * cannot enforce is one API change away from emitting an `og:image` with no
+ * URL.
  */
 export function entityMetadata(source: EntityMetadataSource, locale: string): EntityMetadata {
   const row = source.seo.languages.find((entry) => entry.languageCode === locale);
@@ -202,12 +263,14 @@ export function buildShellMetadata({
   shopName,
   publicOrigin,
   channelResolved,
+  siteVerifications,
 }: ShellMetadataInput): ShellMetadata {
   const refuses = deploymentRefusesIndexing({ publicOrigin, channelResolved });
   return {
     title: pageTitle(null, shopName),
     description: SITE_DESCRIPTION,
     ...(refuses ? { robots: NOINDEX_ROBOTS } : {}),
+    ...verificationTags(siteVerifications),
   };
 }
 
@@ -250,6 +313,7 @@ export function buildMetadata(input: MetadataInput): PageMetadata {
     ...(noindex ? { robots: NOINDEX_ROBOTS } : {}),
     ...(alternates === undefined ? {} : { alternates }),
     ...socialTags({ ...input, title, description, alternates }),
+    ...verificationTags(input.siteVerifications),
   };
 }
 
@@ -321,3 +385,35 @@ function socialTags({
     twitter: { card: 'summary_large_image', ...shared },
   };
 }
+
+/**
+ * The verification tags, or nothing at all (#1530).
+ *
+ * The SINGLE place in this template where a placement becomes a `<meta>`, and
+ * both emitters above route through it — the shell, which is what every route
+ * inherits, and a page that sets `other` for its own reasons and would
+ * otherwise replace the shell's. Two spellings of one tag is how a document
+ * ends up serving a token the platform has already re-minted.
+ *
+ * Deliberately NOT Next's `metadata.verification` block. Every key in it is
+ * named after one named vendor, so which key a token landed in would be a
+ * decision this template makes about which provider the merchant uses — and a
+ * provider without a key of its own could not be served at all. `other` takes
+ * the name from the descriptor, which is the whole point of there being a
+ * descriptor.
+ *
+ * An empty list emits no `other` KEY rather than an empty object, for the
+ * reason stated above `buildMetadata`: a key present with a falsy value still
+ * wins Next's merge, so a page with no placements would blank the shell's.
+ */
+function verificationTags(
+  siteVerifications: readonly SiteVerificationMeta[] | undefined,
+): Pick<PageMetadata, 'other'> {
+  if (siteVerifications === undefined || siteVerifications.length === 0) return {};
+
+  const other: SiteVerificationTags = {};
+  for (const { name, content } of siteVerifications) {
+    other[name] = [...(other[name] ?? []), content];
+  }
+  return { other };
+}