@forgecart/cli 2.202610052310.0 → 2.202610060357.0

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

@@ -0,0 +1,419 @@
+import type { LocaleBinding } from '../locale/localized-path';
+import { buildAlternates } from './alternates';
+import type { Alternates, PathsByLocale } from './alternates';
+import { NOINDEX_ROBOTS, deploymentRefusesIndexing, shouldNoindex } from './noindex';
+import type { DeploymentPosture, RobotsDirective, RouteSearchParams } from './noindex';
+import { getPublicOrigin } from './public-origin';
+
+/**
+ * What every page SAYS it is (#1347, epic launch#54 W1-9).
+ *
+ * One composer for every route's `generateMetadata`, rather than each route
+ * assembling its own object. The reason is not tidiness: a page's title, its
+ * canonical, its hreflang set, its robots directive and its social card are
+ * five claims about the SAME address, and a route that builds them separately
+ * can emit any subset — a title with no canonical, an og:url that disagrees
+ * with the canonical, hreflang on a page marked noindex. Nothing in the
+ * template would notice. Built together, they cannot disagree.
+ *
+ * PURE, and it imports nothing from `next` — the same constraint `noindex.ts`
+ * and `alternates.ts` carry, for the same reason: the storefront template ships
+ * with its own `node_modules`, so a module that imports `next` is unreachable
+ * from the template-spec project and its rules stop being vectors. The shapes
+ * below are structural and assignable to Next's `Metadata` at the call sites;
+ * a production `next build` is what proves that, and it is part of this
+ * slice's acceptance.
+ *
+ * Three deliberate renames from the signature the issue sketches
+ * (`{locale, pathsByLocale, title, description, image?, noindex?}`):
+ *
+ *  - `locale` → `binding`, the template's own name for the (rendering locale,
+ *    channel default) pair every path helper already takes.
+ *  - `image` → `socialImage`. The 2026-09-05 operator amendment makes the
+ *    social block opt-in on the entity's SOCIAL image specifically
+ *    (`SeoMetaLanguage.socialEnabled`), never on `featuredAsset.preview` —
+ *    and a parameter called `image` sitting next to a product that has a
+ *    featured asset is an invitation to wire exactly the wrong one.
+ *  - `noindex` → `contentIndexable`, matching `noindex.ts`'s existing
+ *    vocabulary. An inverted boolean named `noindex` passed into a rule set
+ *    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;
+}
+
+/**
+ * The Open Graph block. `type` is `website` for every storefront surface: a
+ * product is not an article, and og's own `product` type is not something a
+ * crawler treats better than a well-formed website card.
+ */
+export interface OpenGraphMetadata {
+  type: 'website';
+  locale: string;
+  alternateLocale?: string[];
+  url: string;
+  title: string;
+  description?: string;
+  images: string[];
+}
+
+export interface TwitterMetadata {
+  card: 'summary_large_image';
+  title: string;
+  description?: string;
+  images: string[];
+}
+
+/** One page's complete claim set. */
+export interface PageMetadata {
+  title: string;
+  description?: string;
+  robots?: RobotsDirective;
+  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 {
+  binding: LocaleBinding;
+  /** Every language that genuinely has this content, mapped to its own path. */
+  pathsByLocale: PathsByLocale;
+  /** The locale-STRIPPED route this page IS. */
+  pathname: string;
+  /** The request's query, for the query-state noindex rules. */
+  searchParams?: RouteSearchParams;
+  shopName?: string | null;
+  /**
+   * This page's own name, or null when it has none of its own — the home page
+   * and the shell, whose name IS the store's.
+   */
+  title: string | null;
+  description?: string | null;
+  /**
+   * The entity's SOCIAL image. Its presence is the entire opt-in: unset means
+   * no `og:*` and no `twitter:*` tags at all (operator amendment 2026-09-05).
+   */
+  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[];
+}
+
+/**
+ * One language's row of the SEO sidecar (#1341), narrowed to what a page's
+ * metadata reads. A structural subset of the SDK's `SeoMetaLanguage`, for the
+ * same reason `resolve-path.ts` narrows it: the rule is then a table of
+ * vectors instead of something only a live channel can exercise.
+ */
+export interface SeoMetaRow {
+  languageCode: string;
+  title?: string | null;
+  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 — a product's, already in the request's
+   * language, or an ACF page definition's.
+   */
+  name: string;
+  seo: { languages: readonly SeoMetaRow[] };
+}
+
+/** What the sidecar contributes to one locale's metadata. */
+export interface EntityMetadata {
+  title: string;
+  description: string | null;
+  socialImage: string | null;
+}
+
+/**
+ * The sidecar's answer for one locale.
+ *
+ * `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, 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);
+  const socialImage = row?.socialEnabled === true ? (row.socialImage?.preview ?? null) : null;
+  return {
+    title: row?.title?.trim() ? row.title : source.name,
+    description: row?.description?.trim() ? row.description : null,
+    socialImage,
+  };
+}
+
+/** What a storefront is called when the merchant has not named it. */
+export const FALLBACK_SITE_TITLE = 'Storefront';
+
+/** The description every route inherits unless it carries its own. */
+export const SITE_DESCRIPTION = 'A ForgeCart channel storefront.';
+
+/**
+ * `<page name> | <shop name>`, and every degenerate case decided here.
+ *
+ * The suffix appears ONLY when the shop name is non-empty, so a channel that
+ * has not set one gets `Boots` rather than `Boots | ` — and a page with no
+ * name of its own gets the shop name alone rather than ` | Acme`. Whitespace
+ * counts as empty on both sides: a merchant who typed a space into the shop
+ * name field has not named their store, and `SeoMetaLanguage.title` is a
+ * merchant override that can be saved blank.
+ */
+export function pageTitle(name?: string | null, shopName?: string | null): string {
+  const page = name?.trim() ?? '';
+  const site = shopName?.trim() ?? '';
+  if (page === '') return site === '' ? FALLBACK_SITE_TITLE : site;
+  if (site === '') return page;
+  return `${page} | ${site}`;
+}
+
+/**
+ * The deployment-wide floor, applied by the root layout.
+ *
+ * A merchant who scaffolds `app/impressum/page.tsx` and writes no metadata
+ * still inherits this, so neither a preview pod nor a process that never
+ * reached its channel can leak a page through a route nobody remembered to
+ * annotate. It carries NO canonical and NO hreflang on purpose: those are
+ * claims about a specific address, and the layout does not know which route it
+ * is wrapping — a floor that named one would make every unannotated route
+ * claim to be the home page.
+ */
+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),
+  };
+}
+
+/**
+ * One page's metadata.
+ *
+ * Keys carrying no value are OMITTED rather than set to `undefined`, and that
+ * is load-bearing: Next merges a page's metadata over the layout's, and a key
+ * that is PRESENT with an undefined value still wins the merge. A page
+ * returning `robots: undefined` would punch a hole straight through the floor
+ * above and publish itself from a preview host; a page returning
+ * `description: undefined` would blank the inherited one instead of keeping
+ * it. Absent means "inherit", which is what these routes actually mean.
+ */
+export function buildMetadata(input: MetadataInput): PageMetadata {
+  const { binding, pathsByLocale, publicOrigin, channelResolved } = input;
+  const title = pageTitle(input.title, input.shopName);
+  const description = input.description?.trim() ? input.description : null;
+
+  const noindex = shouldNoindex({
+    pathname: input.pathname,
+    searchParams: input.searchParams,
+    publicOrigin,
+    channelResolved,
+    contentIndexable: input.contentIndexable,
+  });
+
+  // An UNRESOLVED channel forfeits the alternates entirely, where a missing
+  // public origin does not: without an origin the language set is still known
+  // and the canonical is merely relative (`alternates.ts`), but without a
+  // channel the set itself is a fallback guess — and hreflang is a claim about
+  // OTHER URLs, which a guess must never make. The two refusals look alike and
+  // are not: one lacks an address, the other lacks the facts.
+  const alternates =
+    channelResolved === false ? undefined : buildAlternates({ binding, pathsByLocale, publicOrigin });
+
+  return {
+    title,
+    ...(description === null ? {} : { description }),
+    ...(noindex ? { robots: NOINDEX_ROBOTS } : {}),
+    ...(alternates === undefined ? {} : { alternates }),
+    ...socialTags({ ...input, title, description, alternates }),
+    ...verificationTags(input.siteVerifications),
+  };
+}
+
+/** `buildMetadata` with the deployment's origin filled in — what routes call. */
+export function routeMetadata(input: Omit<MetadataInput, 'publicOrigin'>): PageMetadata {
+  return buildMetadata({ ...input, publicOrigin: getPublicOrigin() });
+}
+
+/** `buildShellMetadata` with the origin filled in — what the root layout calls. */
+export function shellMetadata(input: Omit<ShellMetadataInput, 'publicOrigin'>): ShellMetadata {
+  return buildShellMetadata({ ...input, publicOrigin: getPublicOrigin() });
+}
+
+interface SocialTagsInput extends MetadataInput {
+  title: string;
+  description: string | null;
+  alternates: Alternates | undefined;
+}
+
+/**
+ * The `og:*` / `twitter:*` block, or nothing at all.
+ *
+ * OPT-IN on the social image, by operator amendment: an entity with no social
+ * image set emits no social tags whatsoever. Deriving one from the product
+ * photo would put a square catalog crop into every share card and make the
+ * merchant's explicit choice indistinguishable from the default — the whole
+ * point of `SeoMetaLanguage.socialEnabled` being armed only by a stored image.
+ *
+ * Two further gates, and neither is redundant with the opt-in: `og:url` must
+ * be ABSOLUTE, so a deployment with no public origin cannot emit one; and the
+ * canonical it uses comes from the alternates, which are absent for a fallback
+ * copy and for an unresolved channel. A share card pointing at an address this
+ * page has just declined to claim would be the same contradiction the
+ * alternates avoid, one protocol over.
+ *
+ * Deliberately NOT gated on indexability. `noindex` is an instruction to
+ * search engines about a page's place in an INDEX; an og card is what a link
+ * to it looks like when a shopper pastes it into a chat. An experiment-pinned
+ * URL should still preview when someone shares it.
+ */
+function socialTags({
+  socialImage,
+  binding,
+  pathsByLocale,
+  publicOrigin,
+  alternates,
+  title,
+  description,
+}: SocialTagsInput): Pick<PageMetadata, 'openGraph' | 'twitter'> {
+  if (!socialImage) return {};
+  if (publicOrigin === null || alternates === undefined) return {};
+
+  const images = [socialImage];
+  const shared = { title, ...(description === null ? {} : { description }), images };
+  // The channel's own language codes, unmodified. Open Graph conventionally
+  // carries `en_US`-shaped values, but the platform's registry is two-letter
+  // codes and there is no honest way to invent the territory half — an
+  // invented `en_US` would be a claim about a market nobody configured.
+  const alternateLocale = Object.keys(pathsByLocale).filter((code) => code !== binding.locale);
+
+  return {
+    openGraph: {
+      type: 'website',
+      locale: binding.locale,
+      ...(alternateLocale.length === 0 ? {} : { alternateLocale }),
+      url: alternates.canonical,
+      ...shared,
+    },
+    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 };
+}

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

@@ -0,0 +1,218 @@
+import { getPublicOrigin } from './public-origin';
+
+/**
+ * The ONE noindex mechanism (#1347, epic launch#54 W1-9).
+ *
+ * Indexability is decided here and expressed in exactly one way: the `robots`
+ * field of Next's metadata. The middleware stays a zero-logic rewrite stage and
+ * never emits an `X-Robots-Tag`, because two mechanisms mean two answers — and
+ * the one a crawler honours is whichever it happens to read first. A merchant
+ * debugging "why is my page not indexed" must have exactly one place to look.
+ *
+ * `follow: true` throughout: a page we do not want INDEXED is still a page
+ * whose links we want CRAWLED. `noindex, nofollow` on the cart would strand
+ * every product reachable only from it.
+ */
+
+/**
+ * Routes that are never indexable, at any origin.
+ *
+ * `/verify` and `/reset-password` (#1472) are here for a stronger reason than
+ * the funnel pair: they are only ever reached through a one-shot token in a
+ * private e-mail. A crawler that indexed one would publish a page whose only
+ * meaningful state is reached with a credential it cannot have, and would
+ * FETCH the URLs it found — spending real tokens on a shopper's behalf.
+ * `robots.ts` derives its `Disallow` list from this set, which is what keeps
+ * a well-behaved crawler from making that request at all.
+ *
+ * `/register` (#1471) is here for the FUNNEL reason instead. It is an ordinary
+ * addressable page — a shopper reaches it from a link on this storefront, and
+ * it stays locale-prefixable unlike the two link routes — but it is a form with
+ * no content of its own, identical for every visitor, so there is nothing for a
+ * search result to be about. One entry covers every language: this set is
+ * matched against the locale-STRIPPED path.
+ */
+export const NOINDEX_PATHS: readonly string[] = [
+  '/cart',
+  '/checkout',
+  '/verify',
+  '/reset-password',
+  '/register',
+];
+
+/**
+ * Query keys that turn a URL into a VIEW of a page rather than the page.
+ *
+ * Each names a distinct duplicate-content source: `sort` reorders a listing
+ * whose canonical form is the unsorted one, `fc-exp` pins an experiment arm,
+ * and `fc-preview` renders unpublished content. Indexing any of them competes
+ * with the page's own canonical URL using near-identical copy.
+ *
+ * Presence is the signal, not the value — `?fc-preview` and `?fc-preview=1`
+ * are equally a preview URL.
+ */
+export const NOINDEX_QUERY_KEYS: readonly string[] = ['sort', 'fc-exp', 'fc-preview'];
+
+/** Next's shape for a page's resolved `searchParams`. */
+export type RouteSearchParams = Record<string, string | string[] | undefined>;
+
+/**
+ * The facts that refuse indexing for EVERY route of a deployment, including
+ * ones this template has never heard of.
+ *
+ * Separated from the per-route input because these two arms are what the root
+ * layout's floor is made of, and the floor and the routes MUST decide them
+ * identically: Next merges page metadata over the layout's, so a page that
+ * evaluated fewer arms than the floor would publish itself straight through
+ * it. One rule, two callers — see {@link deploymentRefusesIndexing}.
+ */
+export interface DeploymentPosture {
+  /** The deployment's public origin, or null when it has none. */
+  publicOrigin: string | null;
+  /**
+   * Whether the channel behind this render was established (#1347, hand-off
+   * from #1346).
+   *
+   * `false` means the storefront does not know what it is serving — an
+   * unconfigured scaffold, or a cold process whose backend it could not reach
+   * — so it is rendering a GUESSED language set. Undefined means the caller
+   * has no opinion, which is not the same as `true`: as with
+   * `contentIndexable`, a caller that never checked must not thereby assert.
+   */
+  channelResolved?: boolean;
+}
+
+/** Everything the indexability decision reads. */
+export interface NoindexInput extends DeploymentPosture {
+  /** The locale-STRIPPED route path (`/de/cart` is decided as `/cart`). */
+  pathname: string;
+  /** The request's query, when the caller is a page. Layouts never receive one. */
+  searchParams?: RouteSearchParams;
+  /**
+   * The CONTENT's own indexability, for routes that have resolved it — the
+   * merchant's explicit choice (`SeoMetaLanguage.indexable`) or the fact that
+   * this language is showing a derived fallback copy rather than real content.
+   *
+   * Undefined means the route has no content-level opinion, which is not the
+   * same as `true`: a route that never resolved one must not be able to assert
+   * indexability it never checked.
+   */
+  contentIndexable?: boolean;
+}
+
+/**
+ * The robots directive shape, declared here rather than imported as Next's
+ * `Metadata['robots']`.
+ *
+ * This module is PURE — it imports nothing from `next` — for the same reason
+ * `lib/locale/grammar.ts` is: a rule that decides what search engines may index
+ * has to be unit-testable as a table of vectors, and the template-spec cannot
+ * resolve `next` (the template carries its own `node_modules`, outside the
+ * workspace). A structural type keeps the rules testable while remaining
+ * assignable to `Metadata['robots']` at every call site.
+ */
+export interface RobotsDirective {
+  index: boolean;
+  follow: boolean;
+}
+
+/** The directive for anything we have decided not to have indexed. */
+export const NOINDEX_ROBOTS: RobotsDirective = { index: false, follow: true };
+
+/**
+ * Whether the DEPLOYMENT refuses indexing, whatever route is being rendered.
+ *
+ * Both arms are the same shape of refusal: the storefront cannot answer
+ * authoritatively, so it declines to make a claim rather than making a guess a
+ * crawler would act on. Neither is about the page — a page cannot opt out of
+ * either — which is why they are the floor the root layout applies and the
+ * first thing every route's own decision consults.
+ */
+export function deploymentRefusesIndexing({
+  publicOrigin,
+  channelResolved,
+}: DeploymentPosture): boolean {
+  // No stable public address ⇒ no claim this deployment makes could be true
+  // tomorrow. This arm is what makes a preview pod safe by default.
+  if (publicOrigin === null) return true;
+
+  // The channel behind this render was never established, so the language set,
+  // the default language and every URL derived from them are a fallback GUESS
+  // (`lib/locale/channel-locales-loader.ts`). The page still renders — the
+  // prewarm contract requires it, and a site-wide 5xx is the worst thing a
+  // crawler can be shown — but a guess must not be indexed under an address
+  // that will serve something else once the backend answers.
+  return channelResolved === false;
+}
+
+/**
+ * Whether this route must not be indexed.
+ *
+ * Pure and total, so the rule set is unit-testable without a running Next.
+ * Ordered cheapest-first; every arm is independently sufficient.
+ */
+export function shouldNoindex({
+  pathname,
+  searchParams,
+  publicOrigin,
+  channelResolved,
+  contentIndexable,
+}: NoindexInput): boolean {
+  if (deploymentRefusesIndexing({ publicOrigin, channelResolved })) return true;
+
+  // The content itself says no — either the merchant set it, or this language
+  // is showing a derived copy. Either way it outranks the route's own opinion:
+  // a product page is normally the most indexable thing a storefront has, and
+  // that is exactly why an explicit refusal has to survive it.
+  if (contentIndexable === false) return true;
+
+  const route = normalizeRoute(pathname);
+  if (NOINDEX_PATHS.some((path) => route === path || route.startsWith(`${path}/`))) return true;
+
+  if (!searchParams) return false;
+  return NOINDEX_QUERY_KEYS.some((key) => searchParams[key] !== undefined);
+}
+
+/**
+ * Trailing slashes are equivalent addresses for the same route, and a nested
+ * route under a noindex parent inherits the decision (`/checkout/payment` is
+ * no more indexable than `/checkout`). The root is left alone — `/` normalizing
+ * to `''` would make every `startsWith` test true.
+ */
+function normalizeRoute(pathname: string): string {
+  if (pathname.length > 1 && pathname.endsWith('/')) return pathname.slice(0, -1);
+  return pathname;
+}
+
+/**
+ * The `robots` metadata for a page, or undefined when it is indexable.
+ *
+ * Undefined rather than an explicit `index: true` so an indexable page emits no
+ * robots tag at all, which is what "no opinion" means to a crawler and keeps
+ * the assertion surface to the pages that genuinely make one.
+ *
+ * Callers pass their own route literal rather than reading the current path:
+ * under the locale rewrite the rendered route and the browser's URL differ, and
+ * a route file already knows which route it is with certainty.
+ *
+ * Every page MUST go through this rather than hand-rolling a robots value.
+ * Next merges page metadata over the layout's, and a key that is PRESENT with
+ * an undefined value still overrides — so a page returning a bare
+ * `robots: undefined` would punch a hole straight through the preview-posture
+ * floor and publish itself from an ephemeral host. This function cannot do
+ * that: its first arm is the same origin check the floor uses, so page and
+ * floor can never disagree.
+ */
+export function routeRobots(
+  pathname: string,
+  searchParams?: RouteSearchParams,
+  contentIndexable?: boolean,
+): RobotsDirective | undefined {
+  const noindex = shouldNoindex({
+    pathname,
+    searchParams,
+    publicOrigin: getPublicOrigin(),
+    contentIndexable,
+  });
+  return noindex ? NOINDEX_ROBOTS : undefined;
+}