@forgecart/cli 2.202608221935.0 → 2.202609190800.0

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

@@ -1,13 +1,24 @@
+import type { Metadata } from 'next';
 import { connection } from 'next/server';
 import { Suspense } from 'react';
 
 import { CheckoutGate } from '../../components/checkout/CheckoutGate';
 import { getAvailableCountries } from '../../lib/forgecart';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeRobots } from '../../lib/seo/noindex';
+
+/**
+ * Never indexable: checkout is a funnel step, not a destination, and every
+ * nested step inherits the decision through `NOINDEX_PATHS`.
+ */
+export function generateMetadata(): Metadata {
+  return { robots: routeRobots('/checkout') };
+}
 
 /**
  * Checkout entry. The server's only job here is the PUBLIC prefetch — the
  * channel's shipping countries off the anonymous channel singleton, streamed
- * as a hole (cacheComponents). The session work (the order itself, every
+ * as a hole. The session work (the order itself, every
  * checkout mutation) lives on the shopper's websocket: `CheckoutGate`
  * hydrates the live cart client-side and mounts the flow, or shows the
  * honest empty state.
@@ -25,8 +36,9 @@ export default function CheckoutPage() {
 
 async function CheckoutWithCountries() {
   await connection();
+  const { binding } = await getRequestLocale();
   const countries = await getAvailableCountries();
-  return <CheckoutGate countries={countries} />;
+  return <CheckoutGate countries={countries} locale={binding} />;
 }
 
 function CheckoutRouteSkeleton() {

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

@@ -1,35 +1,89 @@
 import type { Metadata } from 'next';
-import Link from 'next/link';
+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 { Header } from '../components/Header';
+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 { getBrowserShopConfig } from '../lib/shop-config';
 
 import './globals.css';
 
-export const metadata: Metadata = {
-  title: 'Storefront',
-  description: 'A ForgeCart channel storefront.',
-};
+/**
+ * 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 instead of the word
+ * `Storefront` — which is what every page of every ForgeCart store displayed
+ * before this. 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).
+ *
+ * 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.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { shopName, channelResolved } = await getRequestLocale();
+  return shellMetadata({ shopName, channelResolved });
+}
 
 /**
- * The PPR-static shell: no cookie reads, no session work — the layout renders
- * the same for every shopper. The cart hydrates CLIENT-side over the
- * shopper's own websocket (`CartProvider` + `shop-session.ts`), armed with
- * the channel coordinates serialized here (public storefront token — the
- * admin secret never takes this path).
+ * The root layout — 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. That single requirement
+ * decides the rendering model for the whole storefront, and `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.
+ *
+ * One consequence worth knowing: on `notFound()` Next discards the app tree
+ * and seeds a bare error document, so `app/not-found.tsx` reaches the shopper
+ * on client hydration rather than in the SSR body. The STATUS is correct
+ * either way, which is what the crawler consumes.
+ *
+ * The cart still hydrates CLIENT-side over the shopper's own websocket
+ * (`CartProvider` + `shop-session.ts`), armed with the channel coordinates
+ * serialized here (public storefront token — the admin secret never takes this
+ * path).
  */
-export default function RootLayout({ children }: { children: ReactNode }) {
-  const shopConfig = getBrowserShopConfig();
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const { decision, binding, languageCodes } = await getRequestLocale();
+  if (decision.kind === 'redirect') permanentRedirect(decision.to);
+  if (decision.kind === 'notFound') notFound();
+
+  // The shopper's own socket is opened CLIENT-side, so it cannot read the
+  // request headers the server resolved the locale from. It gets the resolved
+  // language here, which keeps one source of truth — the URL — for both the
+  // server's per-locale clients and the browser's session client. Without it
+  // the cart would answer in the channel default on a German page.
+  const shopConfig = getBrowserShopConfig(binding.locale);
   return (
-    <html lang="en">
+    <html lang={binding.locale}>
       <body className="min-h-screen bg-base-200 text-base-content antialiased">
         <CartProvider shopConfig={shopConfig}>
-          <Header />
+          <Header locale={binding} languageCodes={languageCodes} />
           <main className="mx-auto max-w-6xl px-4 py-10">{children}</main>
           <footer className="footer footer-horizontal mt-8 items-center border-t border-base-300 bg-base-100 px-6 py-8 text-sm text-base-content/60 sm:px-10">
             <aside>
@@ -38,22 +92,31 @@ export default function RootLayout({ children }: { children: ReactNode }) {
             </aside>
             <nav aria-label="Footer" className="sm:justify-self-end">
               <div className="grid grid-flow-col gap-4">
-                <Link href="/" className="link link-hover">
+                <LocaleLink href="/" locale={binding} className="link link-hover">
                   Home
-                </Link>
-                <Link href="/products" className="link link-hover">
+                </LocaleLink>
+                <LocaleLink href="/products" locale={binding} className="link link-hover">
                   Products
-                </Link>
-                <Link href="/cart" className="link link-hover">
+                </LocaleLink>
+                <LocaleLink href="/cart" locale={binding} className="link link-hover">
                   Cart
-                </Link>
+                </LocaleLink>
+                {/* The only affordance for `/register` (#1471). It sits in the
+                    footer rather than the header nav on purpose: the template
+                    ships no sign-in surface yet, and an account entry in the
+                    primary nav would advertise an account AREA that does not
+                    exist. A merchant who adds sign-in moves it up. */}
+                <LocaleLink href="/register" locale={binding} className="link link-hover">
+                  Create account
+                </LocaleLink>
               </div>
             </nav>
           </footer>
         </CartProvider>
         {/* Invisible client plumbing. The tracker reads usePathname(), which
-            cacheComponents only allows under a Suspense boundary — null
-            fallback, these render nothing. */}
+            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 />

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

@@ -1,19 +1,56 @@
-import Link from 'next/link';
+import type { Metadata } from 'next';
 import { connection } from 'next/server';
 import { Suspense } from 'react';
 import { cache } from 'react';
 
+import { LocaleLink } from '../components/LocaleLink';
 import { ProductCard } from '../components/ProductCard';
+import { getAssetAlt } from '../lib/asset-alt';
 import { getVariant } from '../lib/experiments';
 import { getFeaturedProducts } from '../lib/forgecart';
+import type { LocaleBinding } from '../lib/locale/localized-path';
+import { getRequestLocale } from '../lib/locale/request-binding';
+import { staticPathsByLocale } from '../lib/seo/alternates';
+import { routeMetadata } from '../lib/seo/metadata';
+import type { RouteSearchParams } from '../lib/seo/noindex';
 
-// PROGRESSIVE PRE-RENDERING: static shell; the data sections below are
-// per-request holes streamed inside their Suspense boundaries
-// (cacheComponents — see next.config.js).
+// The data sections below are per-request holes streamed inside their Suspense
+// boundaries. The page itself is dynamic like every route (the root layout
+// reads the request locale — see next.config.js).
 
 /** One featured read per request, shared by both holes (React request cache). */
 const featured = cache(async () => getFeaturedProducts(4));
 
+/**
+ * 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 store's landing surface (Blueprint `pages/product-landing-page`):
  * a product-led hero with ONE dominant conversion action, an editorial
@@ -21,11 +58,12 @@ const featured = cache(async () => getFeaturedProducts(4));
  * and a closing conversion band. Every color is a semantic token; the brand
  * lives in the globals.css theme block alone.
  */
-export default function HomePage() {
+export default async function HomePage() {
+  const { binding } = await getRequestLocale();
   return (
     <div className="space-y-16">
       <Suspense fallback={<HeroSkeleton />}>
-        <Hero />
+        <Hero locale={binding} />
       </Suspense>
 
       <section aria-labelledby="featured-heading">
@@ -33,12 +71,16 @@ export default function HomePage() {
           <h2 id="featured-heading" className="text-2xl font-semibold tracking-tight">
             Featured
           </h2>
-          <Link href="/products" className="link link-hover text-sm text-base-content/60">
+          <LocaleLink
+            href="/products"
+            locale={binding}
+            className="link link-hover text-sm text-base-content/60"
+          >
             View all products
-          </Link>
+          </LocaleLink>
         </div>
         <Suspense fallback={<GridSkeleton />}>
-          <FeaturedGrid />
+          <FeaturedGrid locale={binding} />
         </Suspense>
       </section>
     </div>
@@ -53,8 +95,8 @@ export default function HomePage() {
  * and the default copy renders. `data-fc-variant` mirrors the assignment for
  * debugging/verification; exposure tracking happens server-side.
  */
-async function Hero() {
-  // Request-time hole (cacheComponents): the build keeps the fallback shell.
+async function Hero({ locale }: { locale: LocaleBinding }) {
+  // Request-time hole: streamed inside its Suspense boundary.
   await connection();
   const [products, hero] = await Promise.all([featured(), getVariant('hero-headline')]);
   const heroProduct = products.find((product) => product.featuredAsset) ?? null;
@@ -75,14 +117,15 @@ async function Hero() {
               : 'This storefront is served by a ForgeCart channel. Browse the catalog and add products to your cart.'}
           </p>
           <div className="mt-8">
-            <Link href="/products" className="btn btn-primary btn-lg">
+            <LocaleLink href="/products" locale={locale} className="btn btn-primary btn-lg">
               Shop all products
-            </Link>
+            </LocaleLink>
           </div>
         </div>
         {heroProduct?.featuredAsset && (
-          <Link
+          <LocaleLink
             href={`/products/${heroProduct.slug}`}
+            locale={locale}
             className="w-full max-w-md lg:flex-1"
             aria-label={`View ${heroProduct.name}`}
           >
@@ -91,18 +134,18 @@ async function Hero() {
               {/* eslint-disable-next-line @next/next/no-img-element */}
               <img
                 src={heroProduct.featuredAsset.preview}
-                alt={heroProduct.name}
+                alt={getAssetAlt(heroProduct.featuredAsset)}
                 className="h-full w-full object-cover"
               />
             </figure>
-          </Link>
+          </LocaleLink>
         )}
       </div>
     </section>
   );
 }
 
-async function FeaturedGrid() {
+async function FeaturedGrid({ locale }: { locale: LocaleBinding }) {
   await connection();
   const products = await featured();
 
@@ -119,7 +162,7 @@ async function FeaturedGrid() {
       <div className="grid grid-cols-2 gap-4 sm:gap-6 lg:grid-cols-4">
         {products.map((product, index) => (
           <div key={product.id} className={index === 0 ? 'col-span-2 row-span-2' : undefined}>
-            <ProductCard product={product} emphasis={index === 0} />
+            <ProductCard product={product} locale={locale} emphasis={index === 0} />
           </div>
         ))}
       </div>
@@ -132,9 +175,9 @@ async function FeaturedGrid() {
           <p className="max-w-md text-neutral-content/70 text-pretty">
             The whole catalog ships from this store — browse everything in one place.
           </p>
-          <Link href="/products" className="btn btn-primary btn-wide">
+          <LocaleLink href="/products" locale={locale} className="btn btn-primary btn-wide">
             Browse the catalog
-          </Link>
+          </LocaleLink>
         </div>
       </section>
     </>

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

@@ -0,0 +1,23 @@
+import { LocaleLink } from '../../../components/LocaleLink';
+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-base-content">Page not found</h1>
+      <p className="text-base-content/60">
+        We couldn&apos;t find that page. It may have been moved or taken down.
+      </p>
+      <LocaleLink href="/" locale={binding} className="btn btn-primary">
+        Back to the shop
+      </LocaleLink>
+    </div>
+  );
+}

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

@@ -0,0 +1,114 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { cache } from 'react';
+
+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 { 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';
+
+/**
+ * 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 indexability comes from the same resolution the route acts on, so
+ * the tag 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`.
+ */
+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 });
+
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: `${PAGE_ROUTE_PREFIX}/${slug}`,
+    pathsByLocale: staticPathsByLocale(languageCodes, `${PAGE_ROUTE_PREFIX}/${slug}`),
+    searchParams: resolvedSearchParams,
+    title: resolution.kind === 'ok' ? resolution.group.name : null,
+    contentIndexable: resolution.kind === 'ok',
+  });
+}
+
+/**
+ * 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/src/app/ping/route.ts

@@ -9,7 +9,7 @@
  * route handler renders nothing and touches no session, so readiness polling stays
  * side-effect-free.
  *
- * Request access keeps it out of the static prerender (cacheComponents) so a production build serves
+ * 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.
  */
 

package/templates/storefront/src/app/products/[slug]/not-found.tsx

@@ -1,15 +1,17 @@
-import Link from 'next/link';
+import { LocaleLink } from '../../../components/LocaleLink';
+import { getRequestLocale } from '../../../lib/locale/request-binding';
 
-export default function ProductNotFound() {
+export default async function ProductNotFound() {
+  const { binding } = await getRequestLocale();
   return (
     <div className="space-y-4">
       <h1 className="text-2xl font-bold tracking-tight text-base-content">Product not found</h1>
       <p className="text-base-content/60">
         We couldn&apos;t find that product. It may have been removed.
       </p>
-      <Link href="/products" className="btn btn-primary">
+      <LocaleLink href="/products" locale={binding} className="btn btn-primary">
         Back to products
-      </Link>
+      </LocaleLink>
     </div>
   );
 }