@forgecart/cli 2.202610280649.0 → 2.202610280926.0

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

@@ -0,0 +1,87 @@
+/**
+ * DEV-ONLY same-origin error-beacon forwarder.
+ *
+ * The storefront's client beacon (`ForgeErrorBeacon`) POSTs a browser-surfaced
+ * runtime error here — same-origin, so the browser never learns the pod-internal
+ * receiver address. This handler forwards the body SERVER-side to the in-pod
+ * workspace-manager receiver at `http://127.0.0.1:<FORGE_BEACON_PORT>/__forge_beacon`,
+ * which folds it into the supervisor's runtime state so the shop's recovery brain
+ * can originate a fix for a crash the dev-server's stderr scan cannot see.
+ *
+ * Gated entirely on `NODE_ENV === 'development'`: a deployed `next start` storefront
+ * answers 404 here and forwards nothing — the whole beacon path ships only in the
+ * in-pod dev-server. Request access keeps it out of any static prerender so it
+ * behaves identically under `next dev` and a dev build.
+ *
+ * Folder name: `%5F%5Fforge_beacon` is URL-encoded `__forge_beacon`. The App Router
+ * treats a folder whose name starts with `_` as PRIVATE and leaves it out of routing
+ * entirely, so the literal spelling this route shipped with answered the not-found
+ * page to every POST — silently, because the client swallows delivery failures by
+ * design (#2103). The `%5F` escape is Next's documented way to serve a URL segment
+ * that really starts with an underscore, and only the FOLDER may change: the URL is
+ * a contract with the in-pod receiver (`StorefrontBeaconService`'s `BEACON_PATH`),
+ * which this template's server half (`src/instrumentation.ts`) posts to as well.
+ */
+
+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.
+  await fetch(`http://127.0.0.1:${BEACON_PORT}/__forge_beacon`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  }).catch(() => undefined);
+
+  return new Response(null, { status: 204 });
+}

package/templates/storefront-shadcn-blank/src/app/api/%5F%5Fbackend/methods/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from 'next/server';
+
+import { getBackend } from '../../../../server/bootstrap';
+
+/**
+ * DEV-ONLY registry listing — the agent's verification surface for backend
+ * features. After authoring a method, the agent probes this route and
+ * confirms the new name is listed; a boot failure (the api-map drift check)
+ * surfaces here as a 500 carrying the actionable message.
+ *
+ * Gated on `NODE_ENV === 'development'`: the literal check is inlined by
+ * the bundler, so a production build answers 404 and dead-code-eliminates
+ * the body. Method NAMES are the only thing exposed — never inputs,
+ * outputs, or configuration.
+ */
+export async function GET(): Promise<NextResponse> {
+  if (process.env.NODE_ENV !== 'development') {
+    return NextResponse.json({ error: 'not found' }, { status: 404 });
+  }
+  try {
+    const { registry } = await getBackend();
+    return NextResponse.json({ methods: [...registry.keys()].sort() });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: reason }, { status: 500 });
+  }
+}

package/templates/storefront-shadcn-blank/src/app/error.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { Button } from '../components/ui/button';
+
+/**
+ * Route-level backstop boundary. The action layer never throws (typed
+ * `ActionResult` envelopes end at inline UI), so landing here means a RENDER
+ * failed — e.g. a Server Component read against an unreachable shop API.
+ * Recovery is a re-render via `reset()`.
+ */
+export default function RouteError({ reset }: { error: Error; reset: () => void }) {
+  return (
+    <div className="mx-auto max-w-xl space-y-4 py-16 text-center">
+      <h1 className="text-2xl font-bold tracking-tight text-foreground">Something went wrong</h1>
+      <p className="text-muted-foreground">
+        The store could not load this page. Please try again in a moment.
+      </p>
+      <Button type="button" onClick={() => reset()}>
+        Try again
+      </Button>
+    </div>
+  );
+}

package/templates/storefront-shadcn-blank/src/app/global-error.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+/**
+ * Root backstop: replaces the whole document when the root layout itself
+ * fails to render. Must own its own <html>/<body> — the layout that normally
+ * provides them is the thing that crashed. Styled inline (no globals.css —
+ * that import lives in the crashed layout).
+ */
+export default function GlobalError({ reset }: { error: Error; reset: () => void }) {
+  return (
+    <html lang="en">
+      <body
+        style={{ fontFamily: 'system-ui, sans-serif', padding: '4rem 1rem', textAlign: 'center' }}
+      >
+        <h1>Something went wrong</h1>
+        <p>The store is temporarily unavailable. Please try again in a moment.</p>
+        <button type="button" onClick={() => reset()} style={{ padding: '0.5rem 1.25rem' }}>
+          Try again
+        </button>
+      </body>
+    </html>
+  );
+}

package/templates/storefront-shadcn-blank/src/app/globals.css

@@ -0,0 +1,156 @@
+@import "tailwindcss";
+
+/*
+ * ═══════════════════════════════════════════════════════════════════════════
+ * STOREFRONT THEME — the single brand mutation point (design-system contract)
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Every component in this template speaks SEMANTIC shadcn/ui tokens (bg-card,
+ * text-muted-foreground, border-input, the Button / Badge / Alert variants,
+ * …), so the `:root` block below is the ONE place a brand lives. Restyling
+ * the storefront = editing those values — nothing else. Never scatter raw
+ * palette utilities (bg-gray-900, text-white, #hex) through components; if a
+ * component needs a color, it needs a TOKEN: declared once in `:root` and
+ * exposed to Tailwind through `@theme inline`, as the status tokens are.
+ *
+ * The daisyUI storefront and this one are rows of one template set. The table
+ * is how every daisyUI theme token reads here — the same brand decision under
+ * its shadcn/ui name:
+ *
+ *   daisyUI theme token            shadcn/ui token (this file)
+ *   ───────────────────────────    ──────────────────────────────────────────
+ *   --color-base-100               --card, --popover
+ *   --color-base-200               --background
+ *   --color-base-300               --border, --input
+ *   --color-base-content           --foreground (+ --card-foreground,
+ *                                  --popover-foreground)
+ *   --color-primary(-content)      --primary(-foreground)
+ *   --color-secondary(-content)    --secondary(-foreground)
+ *   --color-accent(-content)       --accent(-foreground)
+ *   --color-neutral(-content)      --muted(-foreground)
+ *   --color-error                  --destructive
+ *   --color-success(-content)      --success(-foreground)  declared by this variant
+ *   --color-warning(-content)      --warning(-foreground)  declared by this variant
+ *   --color-info(-content)         --info(-foreground)     declared by this variant
+ *   --radius-selector              --radius-sm
+ *   --radius-field                 --radius-md
+ *   --radius-box                   --radius-lg (= --radius)
+ *   --font-sans (@theme)           --font-sans (@theme inline)
+ *
+ * shadcn/ui names no success, warning or info color, so this variant declares
+ * them beside --destructive, each with the -foreground that stays legible on
+ * it (the Alert's status variants fill with them). --ring has no daisyUI
+ * counterpart — daisyUI draws a focus outline in the control's own color — so
+ * it takes the primary ink.
+ *
+ * The baseline is the daisyUI storefront's own, deliberately UNBRANDED
+ * monochrome (near-black on soft gray), carried value for value through the
+ * table — with one deliberate exception, the muted pair. daisyUI's neutral is
+ * a high-contrast FILL; shadcn/ui's muted pair is the SUBDUED one every
+ * vendored component reads for quiet surfaces and secondary text (bg-muted,
+ * text-muted-foreground — an input's placeholder among them). The baseline
+ * keeps that role: --muted is a soft gray surface, and --muted-foreground the
+ * mid-gray ink the daisyUI template writes as text-base-content/60. Accent
+ * keeps daisyUI's dark highlight, which is also what a ghost or outline
+ * button turns on hover.
+ *
+ * Radius: daisyUI's selector and field radii are both 0.375rem and its box
+ * radius 0.5rem, so --radius is the box radius and the sm/md steps sit one
+ * notch below it. A brand font goes in `@theme inline`: swap the --font-sans
+ * stack (and add the font's `@font-face`/import above it).
+ */
+:root {
+  /* Base — white surfaces over a soft-gray substrate, near-black text. */
+  --background: #f9fafb;
+  --foreground: #111827;
+  --card: #ffffff;
+  --card-foreground: #111827;
+  --popover: #ffffff;
+  --popover-foreground: #111827;
+  --border: #e5e7eb;
+  --input: #e5e7eb;
+
+  /* Actions — unbranded monochrome. */
+  --primary: #111827;
+  --primary-foreground: #ffffff;
+  --secondary: #374151;
+  --secondary-foreground: #ffffff;
+  --accent: #1f2937;
+  --accent-foreground: #ffffff;
+  --muted: #f3f4f6;
+  --muted-foreground: #6b7280;
+  --ring: #111827;
+
+  /* Status — conventional semantics, not brand. */
+  --destructive: #dc2626;
+  --success: #16a34a;
+  --success-foreground: #ffffff;
+  --warning: #d97706;
+  --warning-foreground: #ffffff;
+  --info: #2563eb;
+  --info-foreground: #ffffff;
+
+  /* Shape — the daisyUI storefront's box radius. */
+  --radius: 0.5rem;
+}
+
+/* The tokens as Tailwind theme values: bg-card, text-muted-foreground, rounded-md, font-sans, … */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+
+  --radius-sm: calc(var(--radius) - 2px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* Brand typography mutation point — swap the stack to give the store a font. */
+  --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+    "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+/* The shadcn/ui base layer: token-colored borders and focus outlines, the page on --background. */
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+/*
+ * Base document behavior (structural — NOT part of the theme contract).
+ * A horizontal touchpad glide must never trigger the browser's swipe-back
+ * navigation: mid-checkout that discards the shopper's in-progress state
+ * (the refresh-resume path recovers the payment step, but preventing the
+ * accidental navigation is the real fix). The back button and keyboard
+ * navigation are untouched — only the overscroll gesture is consumed.
+ */
+html,
+body {
+  overscroll-behavior-x: none;
+}

package/templates/storefront-shadcn-blank/src/app/layout.tsx

@@ -0,0 +1,102 @@
+import type { Metadata } from 'next';
+import { notFound, permanentRedirect } from 'next/navigation';
+import { Suspense, type ReactNode } from 'react';
+
+import { ForgeErrorBeacon } from '../components/ForgeErrorBeacon';
+import { ForgeTracker } from '../components/ForgeTracker';
+import { ForgecartDesigner } from '../components/ForgecartDesigner';
+import { getRequestLocale } from '../lib/locale/request-binding';
+import { shellMetadata } from '../lib/seo/metadata';
+import { getSiteVerifications } from '../lib/seo/site-verification';
+import { FORGE_REVISION_META, resolveLiveRevision } from '../server/forge/live-revision';
+
+import './globals.css';
+
+/**
+ * The deployment-wide metadata floor.
+ *
+ * Resolved per REQUEST rather than declared as a static `metadata` object,
+ * because everything in it arrives in the environment of the running server
+ * rather than of the machine that built the bundle: the public origin from
+ * `.env` (see `lib/seo/public-origin.ts`) and the shop name from the channel
+ * itself. A build-time answer would bake the builder's empty environment into
+ * every store shipped from that image.
+ *
+ * The title is the STORE's name, so a merchant who scaffolds a page and writes
+ * no metadata gets their own store in the browser tab. Route-specific claims
+ * live on the routes; this is only the floor, and it deliberately carries no
+ * canonical (it does not know which route it is wrapping).
+ *
+ * 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>`. 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), written where the page is
+ * RENDERED: the browser beacon reads it back at throw time, so a promote landing
+ * between serve and throw cannot make the report blame the new revision for the
+ * old one's crash. Dev-gated by the literal `NODE_ENV` check, so a production
+ * build eliminates the resolution and a deployed storefront leaks no revision.
+ * Unresolvable is a NORMAL answer and means no tag.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { shopName, channelResolved } = await getRequestLocale();
+  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 } };
+}
+
+/**
+ * The root layout of a blank storefront (#3480) — the platform's shell with no
+ * example storefront on it: no header, no footer navigation and no cart. What a
+ * blank workspace builds on is all here: the document language, the locale
+ * contract, the metadata floor above and the invisible client plumbing.
+ *
+ * DYNAMIC on every route, by design (D8). It reads the request locale to write
+ * `<html lang>`, and `lang` is an attribute on the document root: structurally
+ * outside every Suspense boundary, so it cannot come from a streamed hole.
+ * `next.config.js` carries the reasoning — Cache Components is off because the
+ * escape hatch it would force (a `<Suspense>` above `<body>`) is exactly what
+ * makes the two throws below unable to set a status.
+ *
+ * Those throws are the locale contract's teeth. Raised HERE, in the shell,
+ * they reach the one place Next assigns a status: `permanentRedirect` gives a
+ * real 308 with a `Location`, and `notFound` a real 404. Raised from inside
+ * any boundary they would resolve as client-rendered content instead, and the
+ * response would be a 200 carrying a 404 page — a soft-404, which a crawler
+ * indexes rather than drops.
+ */
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const { decision, binding } = await getRequestLocale();
+  if (decision.kind === 'redirect') permanentRedirect(decision.to);
+  if (decision.kind === 'notFound') notFound();
+
+  return (
+    <html lang={binding.locale}>
+      <body className="min-h-screen bg-background font-sans text-foreground antialiased">
+        <main className="mx-auto max-w-6xl px-4 py-10">{children}</main>
+        {/* Invisible client plumbing. The tracker reads usePathname(), which
+            needs a boundary of its own — null fallback, these render nothing.
+            This must stay INSIDE <body>: a boundary above it would make the
+            shell resumable and cost the statuses above. */}
+        <Suspense fallback={null}>
+          <ForgecartDesigner />
+          <ForgeErrorBeacon />
+          <ForgeTracker
+            enabled={Boolean(
+              process.env.FORGECART_SHOP_API_URL && process.env.FORGECART_CHANNEL_TOKEN,
+            )}
+          />
+        </Suspense>
+      </body>
+    </html>
+  );
+}

package/templates/storefront-shadcn-blank/src/app/page.tsx

@@ -0,0 +1,53 @@
+import type { Metadata } from 'next';
+
+import { getRequestLocale } from '../lib/locale/request-binding';
+import { staticPathsByLocale } from '../lib/seo/alternates';
+import { pageTitle, routeMetadata } from '../lib/seo/metadata';
+import type { RouteSearchParams } from '../lib/seo/noindex';
+
+/**
+ * The landing surface is indexable — unless the URL carries query state (an
+ * experiment pin, a preview) that makes it a VIEW of the page competing with
+ * the page's own address.
+ *
+ * `title: null` because the store's landing page has no name of its own: it IS
+ * the store, so it takes the shop name alone rather than composing something
+ * like `Home | Acme`. The description is the shell's, inherited by omission.
+ */
+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,
+    // The canonical is built from the BASE path, so `/?fc-exp=hero:b` declares
+    // `/` as its address — the query-state copy points at the page it is a view
+    // of, which is the whole reason those URLs are noindex rather than ignored.
+    pathname: '/',
+    pathsByLocale: staticPathsByLocale(languageCodes, '/'),
+    searchParams: resolvedSearchParams,
+    title: null,
+  });
+}
+
+/**
+ * Home — the blank storefront's one page (#3480): the store's name as its one
+ * heading, and nothing else. No example content to delete: everything the
+ * merchant builds starts here, on the shell's platform plumbing and the
+ * vendored components in `src/components/ui/`. The heading reads the name the
+ * document title carries, so a channel that has not named its store still
+ * renders one.
+ */
+export default async function HomePage() {
+  const { shopName } = await getRequestLocale();
+  return (
+    <h1 className="text-4xl font-bold tracking-tight text-balance">
+      {pageTitle(null, shopName)}
+    </h1>
+  );
+}

package/templates/storefront-shadcn-blank/src/app/pages/[slug]/not-found.tsx

@@ -0,0 +1,24 @@
+import { LocaleLink } from '../../../components/LocaleLink';
+import { buttonVariants } from '../../../components/ui/button';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+
+/**
+ * What a visitor sees at a page URL that holds nothing: an unknown route, or a
+ * page whose content is not published (or not published YET). The copy does not
+ * distinguish them on purpose — "this is scheduled for Tuesday" is the
+ * merchant's information, not the public's.
+ */
+export default async function AcfPageNotFound() {
+  const { binding } = await getRequestLocale();
+  return (
+    <div className="space-y-4">
+      <h1 className="text-2xl font-bold tracking-tight text-foreground">Page not found</h1>
+      <p className="text-muted-foreground">
+        We couldn&apos;t find that page. It may have been moved or taken down.
+      </p>
+      <LocaleLink href="/" locale={binding} className={buttonVariants()}>
+        Back to the shop
+      </LocaleLink>
+    </div>
+  );
+}

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

@@ -0,0 +1,115 @@
+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 {
+  getPageByRoute,
+  getPageEntries,
+  type PageEntry,
+  type PageGroup,
+} from '../../../lib/forgecart';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
+import { routeMetadata } from '../../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../../lib/seo/noindex';
+import { PAGE_ROUTE_PREFIX } from '../../../lib/seo/sitemap-entries';
+
+/**
+ * The merchant's own pages (#1934, epic launch#50), served at the route the
+ * shop API minted for the page definition.
+ *
+ * Locale-prefixed addresses land here too and cost nothing: the route tree is
+ * FLAT by law (#1041) and the middleware rewrites `/de/pages/x` onto this same
+ * file with the locale carried on a request header, so `/pages/x` and every
+ * `/<xx>/pages/x` are one route with one decision.
+ *
+ * FORCE-DYNAMIC, explicitly. "An unpublished page answers 404 on the NEXT
+ * request" is this feature's contract, and a contract must not rest on the
+ * incidental fact that some module downstream happens to read `headers()`. No
+ * `revalidate`, no `use cache`: a window here would serve a page the merchant
+ * has already taken down, which is the one failure this route may not have.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * The page's definition AND its visible record, read once per request.
+ *
+ * Both halves together, because the 404 decision needs both and Next invokes
+ * `generateMetadata` and the page as separate calls — without React's request
+ * cache the two would resolve independently, and a page unpublished between
+ * them would emit indexable metadata for a URL that then 404s.
+ *
+ * The entries read is skipped when nothing is mounted at the route: there is no
+ * definition code to ask about, and the resolution's answer is already settled.
+ */
+const pageForRequest = cache(
+  async (route: string): Promise<{ group: PageGroup | null; entries: PageEntry[] }> => {
+    const group = await getPageByRoute(route);
+    if (group === null) return { group: null, entries: [] };
+    return { group, entries: await getPageEntries(group.code) };
+  },
+);
+
+/**
+ * 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.
+ *
+ * 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,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<RouteSearchParams>;
+}): Promise<Metadata> {
+  const [{ slug }, resolvedSearchParams, { binding, languageCodes, shopName, channelResolved }] =
+    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,
+    searchParams: resolvedSearchParams,
+    ...pageContentClaims(resolution, { locale: binding.locale, languageCodes, pathname }),
+  });
+}
+
+/**
+ * The resolution runs in the page SHELL, above any boundary, and that placement
+ * is the whole correctness of this route's status codes: `notFound()` can only
+ * set a status where Next assigns one, and raised from inside a Suspense
+ * boundary the shell has already flushed a 200 — a crawler then INDEXES the
+ * not-found page instead of dropping it (the same law `products/[slug]`
+ * carries, measured there).
+ *
+ * There is no boundary at all here, and that follows from the same fact: the
+ * two reads ARE this page, so streaming a skeleton would buy nothing while the
+ * only content loaded.
+ */
+export default async function AcfPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const { group, entries } = await pageForRequest(slug);
+  const resolution = resolvePage({ requestedRoute: slug, group, entries });
+
+  if (resolution.kind === 'notFound') notFound();
+
+  return (
+    <article className="space-y-8">
+      <h1 className="text-3xl font-bold tracking-tight text-balance">{resolution.group.name}</h1>
+      <PageFields definitions={resolution.group.fieldDefinitions} entry={resolution.entry} />
+    </article>
+  );
+}

package/templates/storefront-shadcn-blank/src/app/ping/route.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness ping for the in-pod dev-server readiness probe.
+ *
+ * Returns a static 200 with no layout, data fetch, or session. The workspace's
+ * readiness probe hits THIS route (not `/`) on a fast cadence while the store is
+ * STARTING and then a slow liveness cadence forever — and `/` renders the
+ * cart-aware layout, whose `activeOrder` call MATERIALISES an active order on every
+ * request. Probing `/` therefore minted a throwaway order on every poll; probing a
+ * route handler renders nothing and touches no session, so readiness polling stays
+ * side-effect-free.
+ *
+ * Request access keeps it out of any static prerender so a production build serves
+ * it on demand exactly like `next dev` does — the probe always gets a fresh 200.
+ */
+
+export function GET(): Response {
+  return new Response('ok', {
+    status: 200,
+    headers: { 'content-type': 'text/plain' },
+  });
+}