@decocms/nextjs 8.1.0-next.0 → 8.5.0

package/README.md

@@ -1,365 +1,134 @@
-# `@decocms/nextjs`
-
-Deco framework binding for Next.js App Router — the Next.js sibling of
-`@decocms/tanstack`. Four surfaces, composed together:
-
-- **`@decocms/nextjs/config`** — `withDeco(nextConfig)`, a `next.config`
-  wrapper that adds the rewrites and `transpilePackages` Deco's admin
-  protocol needs.
-- **`@decocms/nextjs/routeHandlers`** — `createDecoRouteHandlers({ setup })`,
-  a single catch-all dispatcher for the whole Studio admin protocol
-  (decofile read/reload, meta schema, invoke, live previews).
-- **`@decocms/nextjs`** — `createDecoPreviewPage({ setup })`, an App Router
-  Server Component that renders live previews through Next's RSC pipeline,
-  including sections marked with `"use client"`.
-- **`@decocms/nextjs/setup`** — `createNextSetup(options)`, a one-call site
-  bootstrap: the Next.js analogue of Vite's
-  `createSiteSetup` + `createAdminSetup` + `import.meta.glob`.
-
-This document is the complete recipe a new Next.js site follows to wire all
-all four together. Every code block below is meant to be copied, not
-paraphrased.
-
-## Install
-
-```bash
-bun add @decocms/nextjs @decocms/blocks @decocms/blocks-admin
-```
+# @decocms/nextjs
 
-`next`, `react`, and `react-dom` are peer dependencies — the site already
-has them.
+Deco CMS for any [Next.js](https://nextjs.org) App Router app. It makes no hosting assumptions: no CDN, ISR or platform behaviour is built in. It is a set of small helpers your site calls from its own proxy, layout, pages and `next.config`.
 
-## 1. `next.config` — `withDeco`
+Peers: `@decocms/blocks` (same version), `next` 16, `react` 19; optionally `@opentelemetry/api` (see [Request metric](#request-metric)).
 
-`withDeco` adds three rewrites (mapping the Studio-protocol URLs Next.js
-cannot express as route segments onto `/deco/*`, where the catch-all route
-below serves them) and appends the three `@decocms/*` packages (which ship
-raw TypeScript, not a prebuilt `dist/`) to `transpilePackages`.
+| Import | What it is for |
+| --- | --- |
+| `@decocms/nextjs/proxy` | Draft previews in `proxy.ts`: `decideDraft`, `draftRequestHeaders`, `rewriteToDraftRoute`, `applyDraft`, `isDraftRoutePath`, or `draftProxy` for a site with no proxy of its own. No React and no block map. |
+| `@decocms/nextjs/server` | Draft previews in Server Components: `bindDraft`, `activeDraftPointer`, `contentClient`. |
+| `@decocms/nextjs` | `DraftPreviewIndicator` (the "Preview mode" badge on a draft page), `StudioBridge` (lets Studio's site editor drive the page) and `StudioPage` (tells it which page is on screen), plus the draft names and Studio's origins (below). |
+| `@decocms/nextjs/config` | `withDeco(nextConfig)`: the draft header rules and Studio's dev origins. CommonJS, so `next.config.js` can `require()` it. |
+| `@decocms/nextjs/instrumentation` | `register`, the `instrumentation.ts` hook that records `http.server.request.duration` from Next's own request span, and `serverRequestSpanProcessor()` for a site with its own OpenTelemetry SDK. |
+| `@decocms/nextjs/image-loader` | `createDecoImageLoader(imageUrl)`: a next/image loader over an `ImageUrl` from `@decocms/blocks/image`. |
 
-TypeScript (`next.config.ts`):
+`createCMS` reads `NODE_ENV` to decide dev mode, so `next dev` never swaps the hosted release in over your local content; nothing needs passing. `createCMS({ dev })` still overrides it when a site needs to.
 
-```ts
-import type { NextConfig } from "next";
-import { withDeco } from "@decocms/nextjs/config";
+## Drafts
 
-const nextConfig: NextConfig = {
-  // ...your own config
-};
+```ts
+// src/cms.config.ts: the options both CMS handles share, and where drafts preview
+export const cmsConfig = { content };
+export const preview = { site: "my-store" };
+
+// src/cms.ts and src/cms.proxy.ts
+export const cms = createCMS({ blocks, ...cmsConfig });
+export const proxyCms = createCMS({ blocks: {}, ...cmsConfig }); // no block map in the proxy
+
+// src/proxy.ts
+export async function proxy(request: NextRequest) {
+  if (isDraftRoutePath(request.nextUrl.pathname)) return new NextResponse(null, { status: 404 });
+  const draft = await decideDraft(proxyCms, request, preview);
+  const response =
+    rewriteToDraftRoute(request, draft) ??
+    NextResponse.next({ request: { headers: draftRequestHeaders(request, draft) } });
+  return applyDraft(response, draft);
+}
 
-export default withDeco(nextConfig);
+// src/app/%5Fdraft/[[...path]]/page.tsx: the dynamic draft route (a literal `_draft` folder never routes)
+export const dynamic = "force-dynamic";
+export default async function DraftPage({ params, searchParams }) {
+  await bindDraft(cms, { searchParams: await searchParams, ...preview });
+  const client = contentClient(cms);
+  // … resolve and render the page as on the published route …
+  return <>{page}<DraftPreviewIndicator /></>;
+}
 ```
 
-CommonJS (`next.config.js`) — most Next.js sites still use this form:
+Published pages stay static: the proxy sends only drafted requests to the draft route, sets the draft cookie, forwards the accepted pointer on `x-deco-draft` (removing any copy sent from outside), and marks the response `Cache-Control: no-store, private` and `X-Robots-Tag: noindex, nofollow`. A root layout that reads content calls `bindDraft(cms, preview)` too: it reads the forwarded header.
 
-```js
-/** @type {import('next').NextConfig} */
-const { withDeco } = require("@decocms/nextjs/config");
+### Draft hosts
 
-const nextConfig = {
-  // ...your own config
-};
+v7's allowlist. A draft link (`?__draft=`) previews on the preview hosts the site declares (the `CMS` block's `preview.hosts`, or `createCMS`'s; a site that declares none has none, as in v7) and always on the hosts Deco runs the site on, `<site>.deco.site` and `<site>.deco-cx.workers.dev`. `previewHosts: [...]` replaces the declared list (v7's `DECO_ALLOWED_PREVIEW_HOSTS`, such as `["localhost:3000"]` in development); `previewHosts: "none"` turns previews off on every host. Hosts compare exactly, port included, on the host the visitor asked for (`x-forwarded-host`, else `host`). Pass the same options to `decideDraft` and `bindDraft`. On a host that may not preview, the page renders the release; `?__draft=off` still ends a preview anywhere.
 
-module.exports = withDeco(nextConfig);
-```
+## The layout
 
-`withDeco` merges with a `rewrites`/`transpilePackages` you already have —
-it never replaces them. If your own `rewrites()` returns the array form,
-Deco's rewrites are prepended; if it returns the `{ beforeFiles, afterFiles,
-fallback }` object form, Deco's rewrites are prepended to `beforeFiles`.
+```tsx
+import { StudioBridge } from "@decocms/nextjs";
 
-## 2. The catch-all route
+<body>
+  {children}
+  <StudioBridge site="my-store" />
+</body>
+```
 
-Mount `createDecoRouteHandlers` at `app/deco/[[...deco]]/route.ts` — this
-one file serves the entire admin protocol (decofile, meta, invoke, live
-previews) for both the rewritten public URLs (`/.decofile`, `/live/_meta`,
-`/live/previews/*`) and their `/deco/*` destinations directly.
+Studio's origins are the package's own (`STUDIO_ORIGINS`), so the bridge takes only the site's name. v7's "." edit shortcut is on by default (`editShortcut={false}` turns it off), and `nonce` is optional.
 
-```ts
-// src/app/deco/[[...deco]]/route.ts
-import { createDecoRouteHandlers } from "@decocms/nextjs/routeHandlers";
-import { ensureSetup } from "../../../deco/setup";
+On a page that isn't in Studio's frame, "." (or Ctrl+Shift+E) opens the page in Studio's editor, and Ctrl or Cmd+"." opens it in a new tab; Studio asks a visitor who isn't signed in to sign in first. To open the right page, each CMS page tells the bridge its path template: the root layout stays across navigations, so the page renders the marker, next to the sections it resolved:
 
-export const dynamic = "force-dynamic";
+```tsx
+import { StudioPage } from "@decocms/nextjs";
 
-export const { GET, POST, OPTIONS } = createDecoRouteHandlers({
-  setup: ensureSetup,
-});
+const match = matchRoute(pathname, { routes: pages });
+// …
+return <>{sections}<StudioPage pathTemplate={match.entry.path} /></>;
 ```
 
-`dynamic = "force-dynamic"` is required — this route must never be
-statically cached (decofile reloads, invoke calls, and previews all need a
-fresh response per request).
+It renders a `<meta>` that React places in the `<head>`, so the page's own markup doesn't change. Without it, Studio picks the page from the URL.
 
-### The RSC preview page
+## Names and Studio's origins
 
-Mount `createDecoPreviewPage` at the framework-owned `/deco/preview` path.
-This path is intentionally not configurable: preview GET requests are always
-redirected from the catch-all route to this App Router page, with the query
-string preserved. Other admin requests, including `POST /deco/render`, remain
-on the catch-all handler.
+For a site that needs them in its own code (a route that sets its own headers, a CSP it writes itself), `@decocms/nextjs` exports what the proxy, the pages and `withDeco` use: `DRAFT_PARAM` (`__draft`), `DRAFT_COOKIE` (`__deco_draft`), `DRAFT_HEADER` (`x-deco-draft`), `draftResponseHeaders(pointer)`, `STUDIO_ORIGINS`, `STUDIO_FRAME_ANCESTORS` and `isStudioOrigin(origin)`. They have the same values as `@decocms/tanstack`'s; each binding keeps its own copy and never imports the other.
 
-```tsx
-// src/app/deco/preview/[[...path]]/page.tsx
-import { createDecoPreviewPage } from "@decocms/nextjs";
-import { ensureSetup } from "../../../../deco/setup";
+## next.config
 
-export const dynamic = "force-dynamic";
-
-export default createDecoPreviewPage({ setup: ensureSetup });
+```js
+const { withDeco } = require("@decocms/nextjs/config");
+module.exports = withDeco({ images: { loader: "custom", loaderFile: "./src/image-loader.ts" } });
 ```
 
-The page boundary is essential for Client Components. A route handler can
-produce plain HTML with `react-dom/server`, but that renderer cannot execute
-the client-reference proxies Next creates for modules marked
-`"use client"`. An App Router page is rendered by Next's React Server
-Components pipeline, so it can render a server section tree containing
-Client Components and preserve their hydration metadata.
-
-Do not work around this error by removing `"use client"` from interactive
-components. Keep sections and wrappers as Server Components when they only
-render markup, but retain a Client Component boundary wherever hooks, event
-handlers, browser APIs, or client-only context are required. The RSC preview
-page exists so those two kinds of component can compose exactly as they do in
-the storefront.
-
-Importing the root barrel is correct in this `page.tsx`; the subpath-only
-rule below applies specifically to `route.ts` files.
-
-### Route-handler import rule: subpaths, never the root barrel
-
-**Always import from `@decocms/nextjs/routeHandlers` (or `/config`,
-`/setup`) in a `route.ts` file. Never `import { ... } from "@decocms/nextjs"`
-there.**
-
-App Router route handlers evaluate their entire module graph against
-React's **react-server** build, and this happens regardless of any
-`"use client"` directive in that graph — route handlers have no client
-bundle to move a `"use client"` module into, so the directive is simply
-ignored. The root barrel (`@decocms/nextjs`'s `.` export) re-exports the
-render components (`DecoRootLayout`, `SectionRenderer`, `DecoPageRenderer`,
-...), whose module graph reaches component code that uses client-only React
-APIs (`createContext`, `useContext`, class components with
-`componentDidCatch`, etc.) at module scope. Importing the root barrel from
-a route file pulls that whole graph into react-server evaluation and
-crashes at **import time**, before your handler ever runs, with errors like
-`"...createContext is not a function"` or `"Class extends value undefined
-is not a constructor"` — even if the route handler itself never touches
-those components. The `/routeHandlers`, `/config`, and `/setup` subpaths
-are each scoped to keep their own module graph free of component code, so
-they're safe to import from anywhere, including a route file.
-
-## 3. `src/deco/setup.ts` — `createNextSetup`
-
-The codegen artifacts (`sections.gen.ts`, `meta.gen.json`) are generated into
-`.deco/` at the site root — the same default `@decocms/blocks-cli`'s
-generators use everywhere else (framework artifacts live in the framework's
-folder, not scattered across `src/`). `src/deco/setup.ts` isn't adjacent to
-`.deco/`, so import it through a `deco/*` tsconfig path alias instead of a
-relative path:
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "paths": {
-      "deco/*": [".deco/*"]
-    }
-  }
-}
-```
+`withDeco` puts v7's two draft header rules before your own (a `?__draft=` query, or the draft cookie: no-store, `Vary: Cookie`, noindex) and adds Studio's origins to `allowedDevOrigins`. Each can be turned off: `withDeco(config, { draftHeaders: false, studioOrigins: false })`. Next sets `Cache-Control` and `Vary` itself on dynamic pages, so only `X-Robots-Tag` is sure to arrive from these rules; the proxy's `applyDraft` sets all three on the responses it makes.
+
+## Request metric
 
 ```ts
-// src/deco/setup.ts
-import { createNextSetup } from "@decocms/nextjs/setup";
-import blocks from "deco/blocksManifest.gen"; // .deco/blocksManifest.gen.ts — see below
-import { sectionImports, sectionMeta, syncComponents, loadingFallbacks } from "deco/sections.gen";
-
-export const ensureSetup = createNextSetup({
-  blocks,
-  blocksDir: false, // the manifest replaces the runtime fs read
-  sections: sectionImports,
-  conventions: { meta: sectionMeta, syncComponents, loadingFallbacks },
-  meta: () => import("deco/meta.gen.json").then((m) => m.default),
-});
+// src/instrumentation.ts (or instrumentation.ts at the root, next to app/)
+export { register } from "@decocms/nextjs/instrumentation";
 ```
 
-### Recommended block source: the static-import manifest
-
-`generate-blocks-manifest` (from `@decocms/blocks-cli`) emits
-`.deco/blocksManifest.gen.ts` — a module that **statically imports** every
-`.deco/blocks/*.json` file (raw on-disk filename in the specifier; keys are
-the filename minus `.json`, verbatim, exactly like
-`loadDecofileDirectory`). Passing its default export as `blocks` with
-`blocksDir: false` (as in the snippet above) makes the manifest the sole
-block source and the bootstrap pure — no filesystem access.
-
-Why this is the recommended wiring over the default `blocksDir` runtime
-read:
-
-- **CMS content hot-reloads in `next dev`.** The block JSONs are part of
-  Next's module graph, so editing one (Studio daemon write, sync, manual
-  edit) invalidates the server module graph, re-evaluates the setup module,
-  and rebuilds `createNextSetup`'s memo with the fresh content —
-  ~120–165ms per edit, measured on a 500-block site. The runtime fs read is
-  invisible to the bundler: edits invalidate nothing and dev serves stale
-  content until a restart.
-- **Deploys need no `outputFileTracingIncludes` hack** — the JSON is
-  bundled into the build output instead of read from disk at runtime.
-
-Trade-offs to know about:
-
-- **Content is baked at build time** in production. Studio's
-  `POST /.decofile` still overrides the in-memory snapshot at runtime
-  (live preview/publish keeps working on a warm instance); the baked
-  manifest is the cold-start baseline.
-- **Adding or removing a block *file* requires re-running the generator**
-  (content edits to existing files do not). Wire it into the site's
-  `generate` chain — see the scripts section below.
-
-If you skip the manifest, the default `blocksDir: ".deco/blocks"` runtime
-read still works — just without dev reload, and your deploy must ship the
-directory alongside the server bundle.
-
-Keep the manifest out of any client-reachable import graph (import it only
-from the server-side setup module) so 5MB of CMS JSON never lands in a
-client bundle.
-
-`createNextSetup` returns a **memoized** `ensureSetup()` function — a
-successful bootstrap is cached for the life of the warm serverless
-instance; a *rejected* bootstrap clears the memo so the next call retries
-from scratch (the triggering call still rejects with the original error).
-
-Three call sites need `ensureSetup()`:
-
-1. **The catch-all route** (above) passes it as `{ setup: ensureSetup }` —
-   `createDecoRouteHandlers` awaits it before dispatching every admin
-   request.
-2. **The root layout** (`app/layout.tsx`) must await it directly before
-   rendering, since page rendering (`createDecoPage`'s resolver) has no
-   setup hook of its own:
-
-   ```tsx
-   // src/app/layout.tsx
-   import { DecoRootLayout } from "@decocms/nextjs";
-   import { ensureSetup } from "../deco/setup";
-
-   export default async function RootLayout({ children }: { children: React.ReactNode }) {
-     await ensureSetup();
-     return <DecoRootLayout siteName="my-site">{children}</DecoRootLayout>;
-   }
-   ```
-
-   (`app/layout.tsx` is a Server Component, not a route handler, so it's
-   fine to import the root barrel here — see the rule above.)
-3. **The RSC preview page** passes it to `createDecoPreviewPage`, as shown
-   above. The setup function is memoized, so these call sites share one
-   successful bootstrap per warm process.
-
-### `NextSetupOptions` at a glance
-
-| Option | Purpose |
+Next.js already measures every request it serves: one root span per request (`BaseServer.handleRequest`) that ends with the status, the method and the route's template. `register` gives Next a tracer provider whose only job is that span: when it ends, the request goes to the CMS's telemetry as `http.server.request.duration` (through `recordServerRequest` from `@decocms/blocks/metrics`) (seconds, the same buckets as the upstream clients' `http.client.request.duration`), next to everything else `createCMS` sends. No span is exported anywhere, and every other span Next asks for is a shared non-recording one. With no telemetry destination (no `token` and no `endpoint`) nothing is recorded.
+
+| Label | Value |
 | --- | --- |
-| `blocksDir` | Directory of decofile JSON snapshots (`.deco/blocks` by default), read with a plain fs scan at bootstrap. Pass `false` to skip filesystem loading entirely — the recommended setting when `blocks` carries the static-import manifest (see above). |
-| `blocks` | Extra/override blocks, merged **over** the directory's blocks. Pass the manifest's default export here (with `blocksDir: false`) to make it the sole block source. |
-| `sections` | The lazy section registry — `sectionImports` from `generate-sections --registry` (see below). |
-| `conventions` | `{ meta, syncComponents, loadingFallbacks }` from `sections.gen.ts` — wires the `export const sync/layout/seo/cache/eager/clientOnly` conventions (see below). |
-| `meta` | Lazy admin meta schema loader: `() => import("deco/meta.gen.json").then(m => m.default)`. Wire this even with a trivial schema — without it, `/deco/meta` (and its `/live/_meta` alias) 503s with `"Schema not initialized"`. |
-| `renderShell` | Admin preview shell config (`{ css, fonts }`). |
-| `previewWrapper` | Admin preview wrapper component. |
-| `productionOrigins`, `customMatchers`, `onResolveError`, `onDanglingReference` | Passed through to `createSiteSetup`. |
-| `extend` | Site-specific wiring that must run *after* core setup (section loaders, legacy SEO key shims, curated post-processing). Receives the loaded blocks. |
-
-## 4. `package.json` scripts — non-colliding names
-
-Add three codegen scripts. **Do not name any of these `generate:schema`** —
-FastStore sites already own that script name for their own commerce-schema
-codegen, and a collision silently shadows one of the two generators
-depending on script-merge order. Use these names instead:
-
-```json
-{
-  "scripts": {
-    "generate:deco-meta": "tsx node_modules/@decocms/blocks-cli/scripts/generate-schema.ts",
-    "generate:deco-sections": "tsx node_modules/@decocms/blocks-cli/scripts/generate-sections.ts --registry",
-    "generate:deco-blocks": "tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts"
-  }
-}
-```
+| `http.route` | Next's route template: `/[[...path]]`, `/blog`, `/_draft/[[...path]]`. An RSC request counts under its page's route. `unmatched` when Next names none (an Edge route under `next start`) |
+| `http.request.method` | `GET`, `POST`, …; any other is `_OTHER` |
+| `status_class` | `2xx` … `5xx`; a request that threw is `5xx` |
+| `cache` | `DRAFT` for a draft render (the proxy forwarded `x-deco-draft`, or the request was rewritten onto `/_draft`), otherwise `BYPASS`: Next decides its own cache (`x-nextjs-cache`) on the response, which the span never sees |
+
+- `@opentelemetry/api` is an optional peer: `register` uses the same copy Next does (yours when installed, else Next's compiled one) and does nothing if neither loads.
+- **Your own OpenTelemetry setup** (`@vercel/otel`, `NodeSDK`): only one tracer provider can be registered, so `register` leaves yours alone and logs how to combine them. Add the processor to yours instead: `registerOTel({ serviceName, spanProcessors: ["auto", serverRequestSpanProcessor()] })`.
+- **The proxy**: under `next start` Next runs the proxy through a request span of its own; that one is not counted, and the request the proxy hands on is. A response the proxy makes itself (a redirect, a 404 for a direct `/_draft` hit) never reaches a page and is not counted.
+- **Edge runtime**: `register` does nothing there. Under `next start` an Edge route is still measured by the Node.js server that serves it (`unmatched`, no template); on a host that runs Edge functions on their own, nothing measures them.
 
-Neither script needs an `--out`/`--out-file` flag — both generators default
-to `.deco/`, which is exactly where `src/deco/setup.ts` reads them from via
-the `deco/*` path alias (see above). Only pass `--out`/`--out-file` if your
-site has a reason to put the artifact somewhere else.
-
-- `generate:deco-meta` runs `blocks-cli`'s `generate-schema.ts`, which scans
-  `src/sections/`, `src/loaders/`, and `src/apps/` for `Props` interfaces
-  and emits the JSON Schema the admin's `/deco/meta` endpoint serves, to
-  `.deco/meta.gen.json` by default.
-- `generate:deco-sections` runs `generate-sections.ts` **with `--registry`**
-  — the flag that additionally emits `sectionImports`, the Next.js/webpack
-  equivalent of Vite's `import.meta.glob("./sections/**/*.tsx")` (Next has
-  no `import.meta.glob` or Vite plugin, so this is generated instead of
-  computed at build time). Without `--registry` you only get
-  `sectionMeta`/`syncComponents`/`loadingFallbacks`, not the lazy loader map
-  `setup.ts` needs for its `sections` option. Defaults to
-  `.deco/sections.gen.ts`.
-- `generate:deco-blocks` runs `generate-blocks-manifest.ts`, which emits the
-  static-import blocks manifest (see the recommended-block-source section
-  above) to `.deco/blocksManifest.gen.ts` by default. Regeneration is
-  idempotent — an unchanged block set rewrites nothing, so no-op runs never
-  tickle Next's file watcher.
-
-Run the first two any time `src/sections/` changes, and
-`generate:deco-blocks` any time a block file is **added or removed** in
-`.deco/blocks/` (content edits to existing files don't need it — the static
-imports pick those up by themselves). Simplest is to wire all three into a
-`predev`/`prebuild` `generate` chain.
-
-## 5. `src/sections/` — the entry-file convention
-
-Every non-test `.tsx`/`.ts` file directly under `src/sections/` (recursively)
-becomes a section key, keyed as `site/sections/<path-relative-to-sections-dir>`.
-**This is not opt-in** — `generate-sections.ts` walks the whole directory
-and turns every matching file into a registry entry, whether or not it
-carries any convention exports. Files ending in `.test.ts(x)`, `.spec.ts(x)`,
-`.stories.ts(x)`, or `.gen.ts(x)` are the only ones excluded.
-
-The established pattern is a **thin re-export entry file** per section, with
-the actual component implementation living elsewhere (e.g. alongside its
-own subcomponents, styles, and tests, outside `src/sections/`):
+## Images
 
 ```ts
-// src/sections/Hero.tsx — thin entry file, becomes "site/sections/Hero.tsx"
-export { default } from "../components/Hero/Hero";
-export type { HeroProps as Props } from "../components/Hero/Hero";
+// src/image-loader.ts
+import { vtexCatalogWebp, vtexFileManager } from "@decocms/apps-vtex/image"; // your platform's helpers, if any
+import { createImageUrl, decoCdn } from "@decocms/blocks/image";
+import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
+
+const imageUrl = createImageUrl({
+  providers: [
+    vtexCatalogWebp(),
+    vtexFileManager({ via: "query" }),
+    decoCdn({ quality: "high", fit: "contain", layout: "quality-last" }),
+  ],
+});
+export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
 ```
 
-This keeps `src/sections/` a clean, flat index of exactly what's
-CMS-addressable, instead of a directory contest between "real" component
-code and registry wiring.
-
-### Convention exports
+The loader knows no commerce platform: the site lists its platform's helpers (`@decocms/apps-vtex/image`, `@decocms/apps-shopify/image`) before the Deco CDN, and the first provider that takes a source makes its URL. Any other source goes to `fallback` (`nextImageOptimizer` uses Next's own `/_next/image`), or comes back unchanged. With the providers above, a Next storefront's current loader URLs come out byte for byte (`tests/nextjs-image-loader.golden.test.ts` in the repository), except an already-resized Deco CDN URL in content: it is now re-resized from its `src` instead of becoming `src=image`.
 
-A section's entry file (or the file it re-exports from — the scanner reads
-the entry file's own source, so re-exported `export const` conventions must
-be re-declared or forwarded on the entry file itself, not just the
-implementation file) can opt into these, each read as a literal
-`export const <name> = <value>`:
-
-| Export | Effect |
-| --- | --- |
-| `export const sync = true` | Bundled synchronously (not lazy-loaded) — for above-the-fold, always-rendered sections. |
-| `export const layout = true` | Cached as a layout section (Header, Footer, Theme) — resolved once, not per-page. |
-| `export const seo = true` | SEO section — its resolved props are merged into page-level SEO. |
-| `export const cache = "listing"` | SWR-cached section loader results, keyed by the given cache name. |
-| `export const eager = true` | Prefers eager rendering (defers only past the fold threshold). |
-| `export const neverDefer = true` | Always eager, ignoring the fold threshold entirely. |
-| `export const clientOnly = true` | Skips SSR — client-only rendering. |
-| `export function LoadingFallback` | Skeleton component shown while the section loads. |
-
-## Verifying your setup
-
-No example app in this monorepo exercises these surfaces any more:
-`examples/nextjs-smoke` now follows the next-major Next.js guide, which uses
-`@decocms/blocks` alone. The surfaces above are covered by this package's unit
-tests.
+`examples/nextjs-binding-smoke` in the repository is a complete app, and its `bun run smoke` checks the whole flow on `next start`.

package/dist/DraftPreviewIndicator.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+export interface DraftPreviewIndicatorProps {
+    /** Where "Exit preview" goes; default: the current URL with `?__draft=off`. */
+    exitHref?: string;
+}
+export declare function DraftPreviewIndicator({ exitHref }?: DraftPreviewIndicatorProps): ReactNode;
+//# sourceMappingURL=DraftPreviewIndicator.d.ts.map

package/dist/DraftPreviewIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DraftPreviewIndicator.d.ts","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAAE,0BAA+B,GAAG,SAAS,CAI9F"}

package/dist/DraftPreviewIndicator.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The "Preview mode" badge for the request's draft: a Server Component that
+ * renders `DraftBadge` (`@decocms/blocks/preview`) only when `bindDraft`
+ * bound a draft, so a published page emits nothing.
+ *
+ * Render it inside the page, after `bindDraft` was awaited, never from a
+ * layout: a layout renders alongside the page that fills it, so it may run
+ * before the page bound its draft.
+ */
+import { DraftBadge } from "@decocms/blocks/preview";
+import { activeDraftPointer } from "./server/slot.js";
+export function DraftPreviewIndicator({ exitHref } = {}) {
+    const pointer = activeDraftPointer();
+    if (!pointer)
+        return null;
+    return _jsx(DraftBadge, { pointer: pointer, exitHref: exitHref });
+}
+//# sourceMappingURL=DraftPreviewIndicator.js.map

package/dist/DraftPreviewIndicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DraftPreviewIndicator.js","sourceRoot":"","sources":["../src/DraftPreviewIndicator.tsx"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAOtD,MAAM,UAAU,qBAAqB,CAAC,EAAE,QAAQ,EAAE,GAA+B,EAAE;IACjF,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,KAAC,UAAU,IAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAI,CAAC;AAC9D,CAAC"}

package/dist/StudioBridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `StudioBridge` of `@decocms/blocks/preview` with Studio's origins filled in
+ * (`STUDIO_ORIGINS`, `./studio.ts`): the package owns where Studio runs, so a
+ * site passes only its name. One inline script and no hooks, so a Server
+ * Component renders it as is.
+ */
+import { type StudioBridgeProps as BridgeScriptProps } from "@decocms/blocks/preview";
+import { type ReactNode } from "react";
+/** `site`, and optionally `editShortcut` and `nonce`; Studio's origins are the package's. */
+export type StudioBridgeProps = Omit<BridgeScriptProps, "trustedOrigins">;
+/**
+ * Lets Studio's site editor select and edit sections on the page when Studio
+ * frames it. Render it once, in the root layout's `<body>`.
+ */
+export declare function StudioBridge(props: StudioBridgeProps): ReactNode;
+//# sourceMappingURL=StudioBridge.d.ts.map

package/dist/StudioBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StudioBridge.d.ts","sourceRoot":"","sources":["../src/StudioBridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAEL,KAAK,iBAAiB,IAAI,iBAAiB,EAC5C,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGtD,6FAA6F;AAC7F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,CAEhE"}

package/dist/StudioBridge.js

@@ -0,0 +1,17 @@
+/**
+ * `StudioBridge` of `@decocms/blocks/preview` with Studio's origins filled in
+ * (`STUDIO_ORIGINS`, `./studio.ts`): the package owns where Studio runs, so a
+ * site passes only its name. One inline script and no hooks, so a Server
+ * Component renders it as is.
+ */
+import { StudioBridge as BridgeScript, } from "@decocms/blocks/preview";
+import { createElement } from "react";
+import { STUDIO_ORIGINS } from "./studio.js";
+/**
+ * Lets Studio's site editor select and edit sections on the page when Studio
+ * frames it. Render it once, in the root layout's `<body>`.
+ */
+export function StudioBridge(props) {
+    return createElement(BridgeScript, { ...props, trustedOrigins: STUDIO_ORIGINS });
+}
+//# sourceMappingURL=StudioBridge.js.map

package/dist/StudioBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StudioBridge.js","sourceRoot":"","sources":["../src/StudioBridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,YAAY,IAAI,YAAY,GAE7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAK7C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,OAAO,aAAa,CAAC,YAAY,EAAE,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC,CAAC;AACnF,CAAC"}

package/dist/draft.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The draft names and headers of a Deco Next.js site: the `?__draft=` link,
+ * the cookie that keeps a preview going, the request header the proxy hands
+ * the pages, and the response headers of a page rendered from a draft. The
+ * proxy reads and writes them (`./drafts.ts`, `./proxy`); the pages read the
+ * header (`./server`); `./config/index.cjs` repeats them (`config.test.ts`
+ * holds them equal). This package's own copy: it never imports
+ * `@decocms/tanstack`. No imports, no state: safe in every bundle.
+ */
+/**
+ * The query parameter a draft link carries (`?__draft=<pointer>`, or `off` to
+ * end a preview). The proxy reads it after its host check; reading it
+ * directly would skip that check.
+ */
+export declare const DRAFT_PARAM = "__draft";
+/**
+ * The cookie that keeps a preview going after the first draft link. Like
+ * {@link DRAFT_PARAM}, the proxy reads it after its host check.
+ */
+export declare const DRAFT_COOKIE = "__deco_draft";
+/**
+ * The request header the proxy sets on the request it hands the pages once it
+ * accepted the draft: the pointer, already checked. The proxy removes any
+ * copy that arrives from outside, and `bindDraft` repeats the host check, so a
+ * client can't send one itself.
+ */
+export declare const DRAFT_HEADER = "x-deco-draft";
+/** The URL prefix a drafted request is rewritten onto (`app/%5Fdraft/[[...path]]`). */
+export declare const DRAFT_ROUTE_PREFIX = "/_draft";
+/**
+ * The response headers of a page rendered from a draft: never stored by a
+ * browser or a CDN (`Cache-Control: no-store, private`, `Vary: Cookie`) and
+ * never indexed (`X-Robots-Tag: noindex, nofollow`). `{}` when `pointer` is
+ * `null`, so the result of the draft decision applies as is.
+ */
+export declare function draftResponseHeaders(pointer: string | null | undefined): Record<string, string>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/F"}