@decocms/nextjs 7.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@decocms/nextjs",
+  "version": "7.0.0",
+  "type": "module",
+  "description": "Deco framework binding for Next.js App Router",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/nextjs/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.0.0",
+    "@decocms/blocks-admin": "7.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "next": "^15.4.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/ClientOnlySection.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import type { ComponentType } from "react";
+
+interface ClientOnlySectionProps {
+  loader: () => Promise<{ default: ComponentType<any> }>;
+  props: Record<string, unknown>;
+}
+
+const cache = new Map<() => Promise<{ default: ComponentType<any> }>, ComponentType<any>>();
+
+export function ClientOnlySection({ loader, props }: ClientOnlySectionProps) {
+  let Dynamic = cache.get(loader);
+  if (!Dynamic) {
+    Dynamic = dynamic(loader, { ssr: false });
+    cache.set(loader, Dynamic);
+  }
+  return <Dynamic {...props} />;
+}

package/src/DecoPageRenderer.test.tsx

@@ -0,0 +1,27 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { registerSectionsSync } from "@decocms/blocks/cms";
+import { DecoPageRenderer } from "./DecoPageRenderer";
+
+function Hero({ label }: { label?: string }) {
+  return <h1>{`hero-${label ?? "none"}`}</h1>;
+}
+
+describe("DecoPageRenderer (next)", () => {
+  it("renders eager sections in order", async () => {
+    registerSectionsSync({
+      "site/sections/NextPageA.tsx": { default: Hero },
+      "site/sections/NextPageB.tsx": { default: Hero },
+    });
+
+    const element = await DecoPageRenderer({
+      sections: [
+        { key: "site/sections/NextPageA.tsx", component: "site/sections/NextPageA.tsx", props: { label: "first" }, index: 0 } as any,
+        { key: "site/sections/NextPageB.tsx", component: "site/sections/NextPageB.tsx", props: { label: "second" }, index: 1 } as any,
+      ],
+      pagePath: "/",
+    });
+    const html = renderToString(element);
+    expect(html.indexOf("hero-first")).toBeLessThan(html.indexOf("hero-second"));
+  });
+});

package/src/DecoPageRenderer.tsx

@@ -0,0 +1,103 @@
+import type { DeferredSection, ResolvedSection } from "@decocms/blocks/cms";
+import { resolveDeferredSection } from "@decocms/blocks/cms";
+import { SectionRenderer } from "./SectionRenderer";
+import { DeferredSectionBoundary } from "./DeferredSection";
+import { cloneElement, type ReactElement, type ReactNode } from "react";
+
+interface DecoPageRendererProps {
+  sections: ResolvedSection[];
+  deferredSections?: DeferredSection[];
+  pagePath: string;
+  pageUrl?: string;
+  loadingFallback?: ReactNode;
+  errorFallback?: ReactNode;
+}
+
+type PageItem =
+  | { type: "eager"; section: ResolvedSection; sort: number }
+  | { type: "deferred"; deferred: DeferredSection; sort: number };
+
+function mergeSections(resolved: ResolvedSection[], deferred: DeferredSection[]): PageItem[] {
+  const items: PageItem[] = [];
+  resolved.forEach((section, i) => items.push({ type: "eager", section, sort: section.index ?? i }));
+  for (const d of deferred) items.push({ type: "deferred", deferred: d, sort: d.index });
+  items.sort((a, b) => a.sort - b.sort);
+  return items;
+}
+
+/**
+ * Top-level renderer for a resolved CMS page. Kicks off (but does not await)
+ * each deferred section's resolve promise immediately, so they resolve
+ * concurrently with the eager sections' own rendering — React's streaming
+ * SSR then flushes each <Suspense> boundary as its promise settles.
+ */
+export async function DecoPageRenderer({
+  sections,
+  deferredSections = [],
+  pagePath,
+  pageUrl,
+  loadingFallback,
+  errorFallback,
+}: DecoPageRendererProps) {
+  const items = mergeSections(sections, deferredSections);
+
+  // `resolveDeferredSection`'s real signature (packages/blocks/src/cms/resolve.ts)
+  // takes positional args `(component, rawProps, pagePath, matcherCtx?)` and
+  // returns a `ResolvedSection` WITHOUT `index` set — unlike the object-shaped
+  // call the plan sketch assumed. `pageUrl` isn't a direct parameter either; it
+  // flows in via `matcherCtx.url`, mirroring how the TanStack route loader
+  // builds `matcherCtx` for `loadDeferredSection` (packages/tanstack/src/routes/cmsRoute.ts).
+  // We also stamp `index` onto the resolved section ourselves (mirroring what
+  // `resolveDeferredSectionFull` does) so downstream consumers can rely on it.
+  const matcherCtx = pageUrl ? { url: pageUrl } : undefined;
+  const deferredPromises = new Map<number, Promise<ResolvedSection | null>>();
+  for (const d of deferredSections) {
+    deferredPromises.set(
+      d.index,
+      resolveDeferredSection(d.component, d.rawProps ?? {}, pagePath, matcherCtx).then((resolved) => {
+        if (!resolved) return null;
+        return { ...resolved, index: d.index };
+      }),
+    );
+  }
+
+  // Eager sections are resolved via a direct (awaited) function call rather
+  // than nested as a `<SectionRenderer />` JSX child. `SectionRenderer` is an
+  // async function; Next's real RSC renderer awaits async components nested
+  // anywhere in the tree, but that's specific to the RSC streaming renderer —
+  // plain `react-dom/server` (used by this package's unit tests, and by any
+  // consumer that isn't going through Next's RSC pipeline) throws ("A
+  // component suspended while responding to synchronous input") when an async
+  // component suspends outside a `<Suspense>` boundary. Deferred sections are
+  // deliberately exempt: `DeferredSectionBoundary` wraps its async child in a
+  // `<Suspense>`, so letting it suspend there is exactly the intended
+  // behavior (renders the fallback synchronously, then streams in later).
+  //
+  // `deferredPromises` above is already populated before this `Promise.all`
+  // runs, so every deferred resolve is in flight concurrently with eager
+  // section rendering — nothing here blocks on it.
+  const rendered = await Promise.all(
+    items.map(async (item): Promise<ReactElement | null> => {
+      if (item.type === "eager") {
+        const element = await SectionRenderer({
+          resolved: item.section,
+          errorFallback,
+        });
+        if (!element) return null;
+        return cloneElement(element, { key: `${item.section.key}-${item.section.index}` });
+      }
+      return (
+        <DeferredSectionBoundary
+          key={`deferred-${item.deferred.key}-${item.deferred.index}`}
+          deferred={item.deferred}
+          promise={deferredPromises.get(item.deferred.index)!}
+          pagePath={pagePath}
+          fallback={loadingFallback}
+          errorFallback={errorFallback}
+        />
+      );
+    }),
+  );
+
+  return <>{rendered}</>;
+}

package/src/DecoRootLayout.test.tsx

@@ -0,0 +1,22 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { DecoRootLayout } from "./DecoRootLayout";
+
+describe("DecoRootLayout (next)", () => {
+  it("renders the html shell with LiveControls and the analytics bootstrap script", () => {
+    const html = renderToString(
+      <DecoRootLayout siteName="test-site">
+        <div>page content</div>
+      </DecoRootLayout>,
+    );
+    expect(html).toContain("page content");
+    expect(html).toContain("__DECO_STATE");
+    // "window.DECO" alone is a false-positive trap: it also appears twice in
+    // this component's own inline bootstrap script (buildDecoEventsBootstrap's
+    // `window.DECO = window.DECO || {}` and `window.DECO.events = ...`), so it
+    // would still pass even if the ANALYTICS_SCRIPT <script> tag were deleted
+    // entirely. "IntersectionObserver" only exists inside ANALYTICS_SCRIPT
+    // (packages/blocks/src/sdk/analytics.ts) — it genuinely pins that script.
+    expect(html).toContain("IntersectionObserver");
+  });
+});

package/src/DecoRootLayout.tsx

@@ -0,0 +1,82 @@
+import type { ReactNode } from "react";
+import { LiveControls } from "@decocms/blocks/hooks";
+import { ANALYTICS_SCRIPT } from "@decocms/blocks/sdk/analytics";
+
+function buildDecoEventsBootstrap(account?: string): string {
+  const accountJson = JSON.stringify(account ?? "");
+  return `
+window.__RUNTIME__ = window.__RUNTIME__ || { account: ${accountJson} };
+window.DECO = window.DECO || {};
+window.DECO.events = window.DECO.events || {
+  _q: [],
+  _subs: [],
+  dispatch: function(e) {
+    this._q.push(e);
+    for (var i = 0; i < this._subs.length; i++) {
+      try { this._subs[i](e); } catch(err) { console.error('[DECO.events]', err); }
+    }
+  },
+  subscribe: function(fn) {
+    this._subs.push(fn);
+    for (var i = 0; i < this._q.length; i++) {
+      try { fn(this._q[i]); } catch(err) {}
+    }
+  }
+};
+window.dataLayer = window.dataLayer || [];
+`;
+}
+
+export interface DecoRootLayoutProps {
+  /** Language attribute for the <html> tag. Default: "en" */
+  lang?: string;
+  /** DaisyUI data-theme attribute. Default: "light" */
+  dataTheme?: string;
+  /** Site name for LiveControls (admin iframe communication). Required. */
+  siteName: string;
+  /** Commerce platform account name for analytics bootstrap (e.g. VTEX account). */
+  account?: string;
+  /** CSS class for <body>. Default: "bg-base-200 text-base-content" */
+  bodyClassName?: string;
+  children?: ReactNode;
+}
+
+/**
+ * Root layout for app/layout.tsx — the Next.js analogue of
+ * `@decocms/tanstack`'s `DecoRootLayout`.
+ *
+ * The bootstrap/analytics <script> tags run once per navigation session
+ * because Next.js App Router doesn't remount a shared layout.tsx across
+ * same-layout navigations — the same property TanStack's <ScriptOnce>
+ * provides explicitly, here implicit in the framework's own layout model.
+ * That's why a plain inline <script> (rather than a ScriptOnce-like helper)
+ * is sufficient here.
+ *
+ * No <head>/<HeadContent> equivalent: Next.js App Router injects
+ * `generateMetadata`'s output automatically, and a root layout.tsx doesn't
+ * render its own <head> element by convention.
+ *
+ * No NavigationProgress/StableOutlet port in v1 — those are
+ * TanStack-Router-specific SPA-navigation UX polish (a loading bar during
+ * client-side nav, height-preserved outlet), not part of the core
+ * CMS-rendering feature set this plan scopes.
+ */
+export function DecoRootLayout({
+  lang = "en",
+  dataTheme = "light",
+  siteName,
+  account,
+  bodyClassName = "bg-base-200 text-base-content",
+  children,
+}: DecoRootLayoutProps) {
+  return (
+    <html lang={lang} data-theme={dataTheme} suppressHydrationWarning>
+      <body className={bodyClassName} suppressHydrationWarning>
+        <script dangerouslySetInnerHTML={{ __html: buildDecoEventsBootstrap(account) }} />
+        {children}
+        <LiveControls site={siteName} />
+        <script dangerouslySetInnerHTML={{ __html: ANALYTICS_SCRIPT }} />
+      </body>
+    </html>
+  );
+}

package/src/DeferredSection.test.tsx

@@ -0,0 +1,27 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { registerSectionsSync } from "@decocms/blocks/cms";
+import { DeferredSectionBoundary } from "./DeferredSection";
+
+function Hero({ label }: { label?: string }) {
+  return <h1>{`hero-${label ?? "none"}`}</h1>;
+}
+
+describe("DeferredSectionBoundary (next)", () => {
+  it("renders the fallback while the promise is pending, per Suspense semantics", () => {
+    const KEY = "site/sections/NextDeferredA.tsx";
+    registerSectionsSync({ [KEY]: { default: Hero } });
+
+    const neverResolves = new Promise<any>(() => {});
+    const html = renderToString(
+      <DeferredSectionBoundary
+        deferred={{ key: KEY, component: KEY, index: 0 } as any}
+        promise={neverResolves}
+        pagePath="/"
+        fallback={<div>loading</div>}
+      />,
+    );
+    expect(html).toContain("loading");
+    expect(html).not.toContain("hero-");
+  });
+});

package/src/DeferredSection.tsx

@@ -0,0 +1,59 @@
+import { Suspense, type ReactNode } from "react";
+import type { DeferredSection, ResolvedSection } from "@decocms/blocks/cms";
+import { SectionErrorBoundary } from "@decocms/blocks/hooks";
+import { SectionRenderer } from "./SectionRenderer";
+
+interface DeferredSectionBoundaryProps {
+  deferred: DeferredSection;
+  promise: Promise<ResolvedSection | null>;
+  pagePath: string;
+  fallback?: ReactNode;
+  errorFallback?: ReactNode;
+}
+
+async function ResolvedDeferredSection({
+  promise,
+  errorFallback,
+}: {
+  promise: Promise<ResolvedSection | null>;
+  errorFallback?: ReactNode;
+}) {
+  const resolved = await promise;
+  if (!resolved) return null;
+  return <SectionRenderer resolved={resolved} errorFallback={errorFallback} />;
+}
+
+/**
+ * Deferred/streamed section — the RSC-native analogue of DecoPageRenderer's
+ * <Suspense><Await promise={promise}>{...}</Await></Suspense>. React 19
+ * Server Components can await a promise directly inside an async component,
+ * so there is no need for TanStack's <Await> wrapper — <Suspense> here is
+ * the same React primitive TanStack also uses, just without the extra
+ * unwrapping component.
+ */
+export function DeferredSectionBoundary({
+  deferred,
+  promise,
+  pagePath: _pagePath,
+  fallback,
+  errorFallback,
+}: DeferredSectionBoundaryProps) {
+  const sectionId = deferred.key
+    .replace(/\//g, "-")
+    .replace(/\.tsx$/, "")
+    .replace(/^site-sections-/, "");
+
+  return (
+    <SectionErrorBoundary sectionKey={deferred.key} fallback={errorFallback}>
+      <Suspense
+        fallback={
+          <section id={sectionId} data-manifest-key={deferred.key} data-deferred="true">
+            {fallback}
+          </section>
+        }
+      >
+        <ResolvedDeferredSection promise={promise} errorFallback={errorFallback} />
+      </Suspense>
+    </SectionErrorBoundary>
+  );
+}

package/src/SectionRenderer.test.tsx

@@ -0,0 +1,97 @@
+import { renderToString } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { registerSection, registerSections, registerSectionsSync } from "@decocms/blocks/cms";
+import { SectionRenderer } from "./SectionRenderer";
+
+function Hero({ label }: { label?: string }) {
+  return <h1>{`hero-${label ?? "none"}`}</h1>;
+}
+
+// The test environment runs under jsdom (see root vitest.config.ts), where
+// `window` is defined. next/dynamic's internals branch on
+// `typeof window === "undefined"` to decide server vs. client behavior, so
+// under jsdom it always takes the client path — `{ ssr: false }` vs.
+// `{ ssr: true }` produce IDENTICAL rendered output here (both effectively
+// render `null` during a synchronous renderToString call, since the loader's
+// promise can't resolve in time regardless of the ssr option). Asserting on
+// rendered HTML would therefore pass even if ClientOnlySection passed
+// `{ ssr: true }` by mistake — it exercises no real server/window-undefined
+// code path in this environment.
+//
+// Instead we verify the actual contract ClientOnlySection is responsible
+// for: that it calls next/dynamic with `{ ssr: false }`. We spy on the
+// `next/dynamic` module import via `vi.mock` + `vi.hoisted`.
+const { dynamicSpy } = vi.hoisted(() => ({ dynamicSpy: vi.fn() }));
+
+vi.mock("next/dynamic", () => ({
+  default: (loader: unknown, options: unknown) => {
+    dynamicSpy(loader, options);
+    return function DynamicStub() {
+      return null;
+    };
+  },
+}));
+
+beforeEach(() => {
+  dynamicSpy.mockClear();
+});
+
+describe("SectionRenderer (next)", () => {
+  it("renders a sync-registered section directly", async () => {
+    const KEY = "site/sections/NextSyncA.tsx";
+    registerSectionsSync({ [KEY]: { default: Hero } });
+
+    const element = await SectionRenderer({
+      resolved: { key: KEY, component: KEY, props: { label: "a" } } as any,
+    });
+    const html = renderToString(element);
+    expect(html).toContain("hero-a");
+  });
+
+  it("awaits a code-split (non-sync) section's loader", async () => {
+    const KEY = "site/sections/NextLazyA.tsx";
+    registerSections({ [KEY]: () => Promise.resolve({ default: Hero }) });
+
+    const element = await SectionRenderer({
+      resolved: { key: KEY, component: KEY, props: { label: "b" } } as any,
+    });
+    const html = renderToString(element);
+    expect(html).toContain("hero-b");
+  });
+
+  it("routes a clientOnly-registered section through next/dynamic with ssr:false", async () => {
+    const KEY = "site/sections/NextClientOnlyA.tsx";
+    const loader = () => Promise.resolve({ default: Hero });
+    registerSection(KEY, loader, { clientOnly: true });
+
+    const element = await SectionRenderer({
+      resolved: { key: KEY, component: KEY, props: { label: "c" } } as any,
+    });
+    const html = renderToString(element);
+
+    // The actual contract: ClientOnlySection must call next/dynamic with
+    // { ssr: false } for this section's loader. This fails if the
+    // implementation is changed to pass { ssr: true } (or omits the option).
+    expect(dynamicSpy).toHaveBeenCalledWith(loader, { ssr: false });
+
+    // The section shell (wrapping <section> + manifest key) still renders
+    // server-side regardless of the dynamic child's ssr option.
+    expect(html).toContain(`data-manifest-key="${KEY}"`);
+  });
+
+  it("warns and renders nothing for an unregistered section", async () => {
+    const KEY = "site/sections/NextMissingA.tsx";
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const element = await SectionRenderer({
+      resolved: { key: KEY, component: KEY, props: {} } as any,
+    });
+
+    expect(element).toBeNull();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(`No component registered for: ${KEY}`),
+    );
+
+    warnSpy.mockRestore();
+  });
+});

package/src/SectionRenderer.tsx

@@ -0,0 +1,62 @@
+import { createElement, type ReactNode } from "react";
+import {
+  getSection,
+  getSectionOptions,
+  getSyncComponent,
+} from "@decocms/blocks/cms";
+import type { ResolvedSection } from "@decocms/blocks/cms";
+import { SectionErrorBoundary } from "@decocms/blocks/hooks";
+import { ClientOnlySection } from "./ClientOnlySection";
+
+interface SectionRendererProps {
+  resolved: ResolvedSection;
+  errorFallback?: ReactNode;
+}
+
+/**
+ * Renders one resolved section. Runs inside an async Server Component tree,
+ * so code-split sections are loaded via a plain await — no client-side
+ * React.lazy/Suspense needed for content in the initial response.
+ */
+export async function SectionRenderer({ resolved, errorFallback }: SectionRendererProps) {
+  const sectionId = resolved.key
+    .replace(/\//g, "-")
+    .replace(/\.tsx$/, "")
+    .replace(/^site-sections-/, "");
+
+  const options = getSectionOptions(resolved.component);
+  const errFallback = options?.errorFallback
+    ? createElement(options.errorFallback, { error: new Error("") })
+    : errorFallback;
+
+  const isClientOnly = options?.clientOnly === true;
+  const SyncComp = getSyncComponent(resolved.component);
+  let content: ReactNode;
+
+  if (isClientOnly) {
+    const loader = getSection(resolved.component);
+    if (!loader) {
+      console.warn(`[SectionRenderer] No component registered for: ${resolved.component}`);
+      return null;
+    }
+    content = <ClientOnlySection loader={loader} props={resolved.props} />;
+  } else if (SyncComp) {
+    content = createElement(SyncComp, resolved.props);
+  } else {
+    const loader = getSection(resolved.component);
+    if (!loader) {
+      console.warn(`[SectionRenderer] No component registered for: ${resolved.component}`);
+      return null;
+    }
+    const mod = await loader();
+    content = createElement(mod.default, resolved.props);
+  }
+
+  return (
+    <section id={sectionId} data-manifest-key={resolved.key}>
+      <SectionErrorBoundary sectionKey={resolved.key} fallback={errFallback}>
+        {content}
+      </SectionErrorBoundary>
+    </section>
+  );
+}

package/src/createDecoPage.test.tsx

@@ -0,0 +1,65 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { registerSections, setBlocks } from "@decocms/blocks/cms";
+import { createDecoPage } from "./createDecoPage";
+
+function Hero({ label }: { label?: string }) {
+  return <h1>{`hero-${label ?? "none"}`}</h1>;
+}
+
+describe("createDecoPage (next)", () => {
+  it("resolves and renders the page for the current path", async () => {
+    // registerSections (the async-loader registry, packages/blocks/src/cms/registry.ts)
+    // — NOT registerSectionsSync — is what resolveDecoPage's pipeline reads:
+    // resolveRawSection() gates each raw CMS section through getSection(),
+    // which only consults the registry registerSections populates.
+    // registerSectionsSync populates a separate `syncComponents` map that
+    // SectionRenderer checks first for already-rendered pages, but a section
+    // registered ONLY via registerSectionsSync is silently dropped (with a
+    // "[CMS] No component registered for: ..." warning) during CMS
+    // resolution itself — confirmed by running this test against the plan's
+    // original registerSectionsSync-based sketch.
+    registerSections({ "site/sections/CreateDecoPageHero.tsx": async () => ({ default: Hero }) });
+    // Block key MUST start with "pages-" — that's the prefix getAllPages()
+    // (packages/blocks/src/cms/loader.ts) filters on. The plan's sketch used
+    // "pages/home.json", which getAllPages() would silently skip, so
+    // resolveDecoPage would return null and this test would fail even with a
+    // correct implementation.
+    setBlocks({
+      "pages-home": {
+        path: "/",
+        sections: [{ __resolveType: "site/sections/CreateDecoPageHero.tsx", label: "home" }],
+        seo: {
+          __resolveType: "website/sections/Seo/SeoV2.tsx",
+          title: "Home title",
+          description: "Home description",
+        },
+      },
+    });
+
+    const { generateMetadata, default: Page } = createDecoPage({ siteName: "test-site" });
+
+    const element = await Page({ params: Promise.resolve({ slug: [] }) });
+    const html = renderToString(element);
+    expect(html).toContain("hero-home");
+
+    const metadata = await generateMetadata({ params: Promise.resolve({ slug: [] }) });
+    expect(metadata.title).toBe("Home title");
+    expect(metadata.description).toBe("Home description");
+  });
+
+  it("calls next/navigation notFound() when no page matches the path", async () => {
+    setBlocks({
+      "pages-home": {
+        path: "/",
+        sections: [{ __resolveType: "site/sections/CreateDecoPageHero.tsx", label: "home" }],
+      },
+    });
+
+    const { default: Page } = createDecoPage({ siteName: "test-site" });
+
+    await expect(
+      Page({ params: Promise.resolve({ slug: ["missing"] }) }),
+    ).rejects.toThrow();
+  });
+});

package/src/createDecoPage.tsx

@@ -0,0 +1,107 @@
+import { cache } from "react";
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+import {
+  extractSeoFromProps,
+  extractSeoFromSections,
+  resolveDecoPage,
+  type DecoPageResult,
+  type PageSeo,
+} from "@decocms/blocks/cms";
+import { DecoPageRenderer } from "./DecoPageRenderer";
+
+interface CreateDecoPageOptions {
+  siteName: string;
+}
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>;
+}
+
+function pathFromSlug(slug: string[] | undefined): string {
+  return `/${(slug ?? []).join("/")}`;
+}
+
+/**
+ * Merge page-level SEO (the `seo` block resolved into `DecoPageResult.seoSection`)
+ * with section-contributed SEO (sections registered via `registerSeoSections`
+ * whose resolved props also carry SEO fields — e.g. a PDP SEO section). Page
+ * level fields win on conflict, mirroring `buildPageSeo` in the TanStack
+ * binding (packages/tanstack/src/routes/cmsRoute.ts:408-484).
+ *
+ * Deliberately narrower than that binding's version: it does NOT run
+ * `seoSection` through its own section loader (so commerce-loader-backed
+ * jsonLD on the seo block won't resolve here) and does NOT fall back to
+ * site-wide SEO defaults or apply title/description templates. Those are
+ * out of scope for this minimal page.tsx wiring.
+ */
+function buildSeo(page: DecoPageResult): PageSeo {
+  const sectionSeo = extractSeoFromSections(page.resolvedSections);
+  const pageSeo = page.seoSection ? extractSeoFromProps(page.seoSection.props) : {};
+  return { ...sectionSeo, ...pageSeo };
+}
+
+/**
+ * Creates the { generateMetadata, default } pair a site spreads into
+ * app/[[...slug]]/page.tsx. Mirrors `@decocms/tanstack`'s `cmsRouteConfig`.
+ *
+ * `resolveForPath` is wrapped in React's `cache()` so `generateMetadata` and
+ * the page body share one `resolveDecoPage` call per request instead of
+ * resolving twice — the same pattern faststore-fila's own
+ * `resolveCmsPageByPath` already used against the old /next tier. This relies
+ * on Next's RSC renderer establishing a per-request cache boundary that
+ * `cache()` memoizes against: calling the returned functions directly outside
+ * that renderer (e.g. in a plain unit test) will NOT dedupe, since there is
+ * no active cache boundary for `cache()` to key off — verified empirically
+ * against this repo's `react` version. The functions still return correct,
+ * independent results either way; only the single-request sharing is
+ * untestable outside Next's own pipeline.
+ */
+export function createDecoPage({ siteName }: CreateDecoPageOptions) {
+  // `siteName` is unused here. `MatcherContext` (packages/blocks/src/cms/resolve.ts)
+  // has no siteName field, so there's nothing to thread it into `resolveDecoPage`.
+  // It's kept in the options shape to mirror `cmsRouteConfig({ siteName })`'s call
+  // signature and as the extension point for Task 7's root layout
+  // (LiveControls/analytics wiring) — genuinely unused in this file.
+  void siteName;
+
+  const resolveForPath = cache(async (pathname: string) => resolveDecoPage(pathname, {}));
+
+  async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+    const { slug } = await params;
+    const page = await resolveForPath(pathFromSlug(slug));
+    if (!page) return {};
+
+    const seo = buildSeo(page);
+    return {
+      title: seo.title,
+      description: seo.description,
+      alternates: seo.canonical ? { canonical: seo.canonical } : undefined,
+      robots: seo.noIndexing ? { index: false, follow: false } : undefined,
+    };
+  }
+
+  async function Page({ params }: PageProps) {
+    const { slug } = await params;
+    const pathname = pathFromSlug(slug);
+    const page = await resolveForPath(pathname);
+    if (!page) notFound();
+
+    // Call DecoPageRenderer directly (await its result) rather than nesting
+    // it as `<DecoPageRenderer .../>` JSX. DecoPageRenderer.tsx documents why:
+    // it's an async function, and Next's real RSC renderer awaits async
+    // components anywhere in the tree — but react-dom/server's synchronous
+    // renderer (used by this package's unit tests, and by any consumer not
+    // going through Next's RSC pipeline) throws when an async component
+    // suspends outside a <Suspense> boundary. Awaiting it here directly
+    // keeps both paths working, matching the same convention
+    // DecoPageRenderer itself uses for SectionRenderer.
+    return await DecoPageRenderer({
+      sections: page.resolvedSections,
+      deferredSections: page.deferredSections,
+      pagePath: pathname,
+    });
+  }
+
+  return { generateMetadata, default: Page };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { createDecoPage } from "./createDecoPage";
+export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
+export { DecoPageRenderer } from "./DecoPageRenderer";
+export { SectionRenderer } from "./SectionRenderer";
+export { ClientOnlySection } from "./ClientOnlySection";
+export { DeferredSectionBoundary } from "./DeferredSection";
+export {
+  decofileGET,
+  decofilePOST,
+  invokePOST,
+  metaGET,
+  renderGET,
+  renderPOST,
+} from "./routeHandlers";

package/src/routeHandlers.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { setMetaData } from "@decocms/blocks-admin";
+import { metaGET } from "./routeHandlers";
+
+describe("routeHandlers (next)", () => {
+  it("metaGET returns the schema response", async () => {
+    setMetaData({ sections: {}, actions: {}, loaders: {} } as any);
+    const response = await metaGET(new Request("https://example.com/live/_meta"));
+    expect(response.status).toBe(200);
+  });
+});

package/src/routeHandlers.ts

@@ -0,0 +1,37 @@
+import {
+  handleDecofileRead,
+  handleDecofileReload,
+  handleInvoke,
+  handleMeta,
+  handleRender,
+} from "@decocms/blocks-admin";
+
+/** For app/live/_meta/route.ts: `export { metaGET as GET } from "@decocms/nextjs"` */
+export async function metaGET(request: Request): Promise<Response> {
+  return handleMeta(request);
+}
+
+/** For app/.decofile/route.ts (or an equivalent rewritten path — Next.js route
+ * segments can't literally start with a dot; see Task 9's fixture for the
+ * rewrite-rule workaround). */
+export async function decofileGET(): Promise<Response> {
+  return handleDecofileRead();
+}
+
+export async function decofilePOST(request: Request): Promise<Response> {
+  return handleDecofileReload(request);
+}
+
+/** For app/deco/invoke/[...key]/route.ts */
+export async function invokePOST(request: Request): Promise<Response> {
+  return handleInvoke(request);
+}
+
+/** For app/live/previews/[...path]/route.ts */
+export async function renderGET(request: Request): Promise<Response> {
+  return handleRender(request);
+}
+
+export async function renderPOST(request: Request): Promise<Response> {
+  return handleRender(request);
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}