feat: pull-based draft preview

[tlgimenes]

Pull-based draft preview: a site renders its own pages against a Studio sandbox's working-tree draft, fetching the merged decofile itself over a plain GET.

Paired with decocms/studio#5363 (daemon serves GET /_sandbox/decofile, Studio builds the pointer) and deco-sites/faststore-fila#271 (first adopter). Published as 7.28.0-beta.3 under the beta dist-tag.

Why

The old flow POSTed the decofile to /live/previews. Three structural problems: only deco's own runtime honours a POST render (Next renders on GET); it produced one statically-rendered component — no hydration, no navigation, and client components invoked server-side (renderToString cannot call Next's client-reference proxies); and it re-sent a multi-MB payload on every navigation. Pull fixes all three — the payload is fetched once per version.

Shape

GET https://site.com/any/page?__draft=<host[:port]>@<version>
  → authority validated against DECO_PREVIEW_API_DOMAINS (dot-prefixed
    suffix match, label-boundary safe; defaults to the deco-operated domains)
  → GET {derived-scheme}://<host[:port]>/_sandbox/decofile  (cached by version)
  → renders its own route with the draft merged over published blocks

The token carries an authority, never a URL — no scheme, no path, so javascript:/file:/URL-shaped tokens fail at parse time and the domain allowlist decides what may be fetched. Scheme is derived (http only for localhost-ish domains, where an explicit port is also admitted — which is how the desktop link's per-run port travels in the token). <version> is the daemon's content ETag; a save mints a new version, which is what refreshes the frame.

Gating: host allowlist, not a boolean

DECO_ALLOWED_PREVIEW_HOSTS=fila.vtex.app,localhost:3100 — only listed request hosts render drafts. One build commonly serves several domains; host scoping makes the production domain structurally inert: fila.com.br?__draft= does nothing on the same build that previews on fila.vtex.app. Verified on the wire — identical URL, same server: draft under an allowed Host, published (and no cookie) otherwise.

• Unset ⇒ feature completely inert; no dynamic API touched, static/ISR untouched. Upgrading the package can never enable it.
• Enforced twice: middleware returns an inert decision on other hosts (no cookie/rewrite/headers), and ensureDraft re-checks before binding. The host header is spoofable direct-to-origin, but the sandbox handle is the capability — this bounds blast radius, it is not a secret.
• DECO_PREVIEW_API_DOMAINS now defaults to the deco-operated origins (.preview-studio.decocms.com, .local.studio.decocms.com, .localhost); the env is an override (e.g. a ported local link .localhost:60534). Defaults add no SSRF surface — origins remain configuration, never caller input.

Integration surface

ensureDraft(searchParams) is the primary API — await it in every entry point that resolves CMS content (page and generateMetadata; they race). It lives on the page, not a layout: a layout's await does not gate its children (measured — App Router renders them concurrently). Request scoping is React cache(); RequestContext.run is never entered on Next and ALS can't wrap a component's children.

Middleware (@decocms/nextjs/middleware, own subpath so the edge graph never pulls the root barrel): prepareDraft/applyDraft (cookie lifecycle — ?__draft= enters, cookie carries navigation, off exits — plus no-store/noindex headers; cookie is SameSite=None; Secure; HttpOnly; Partitioned since the preview iframe is cross-site), and rewriteToDraftRoute for statically rendered routes only (a static draft render would be cached for real visitors). The rewrite target must be mounted URL-encoded (app/%5Fdraft/…) — a literal _draft folder is a Next private folder, excluded from routing.

createDecoPage is also wired, but a usage survey found its only consumer is this repo's smoke example — real sites hand-roll routes, which is why ensureDraft is the documented path.

Safety & failure modes

Every failure path (malformed pointer incl. a@b@c, disallowed host, unreachable origin, non-2xx, bad JSON) degrades to published. Version cache is bounded (3 entries; multi-MB payloads). Measured limit: Next reserves Cache-Control/Vary on dynamic responses (overwrites middleware and next.config headers()); the wire keeps no-cache, must-revalidate, which still forbids reuse without revalidation — a CDN-level rule is recommended before production. X-Robots-Tag gets through.

Testing

673 tests across the two packages: host allow/deny, suffix defaults + fallback order, cookie, rewrite, gate-never-touches-dynamic-APIs. Verified end-to-end against a real sandbox daemon serving a real store's 440 blocks: entry, cookie navigation, stale-cookie override, ?__draft=off, concurrent distinct drafts, and the host gate above.

Known follow-ups (not in this PR)

• Deferred/lazy sections resolve via /deco/invoke, which does not bind drafts — client-fetched sections render published content.
• .releaserc.json has no prerelease channel; betas were published manually.
• bun run lint already fails on clean main (unrelated files); this branch doesn't add to it.