v8 N-16: drafts are the fast-preview pointer, with only the branch's changes over the local release

[tlgimenes]

What

Draft previews go back to the v7 "fast preview" protocol: Studio mints a pointer that the SDK fetches. The only change from v7 is the answer: the pointer returns only what the draft branch changed compared with production, not a whole decofile. cms.forDraft(pointer) layers those changes over the production snapshot the server already has in memory.

There's no /preview route, no "preparing" state, no overlay or blob uploads to object storage, no /api/_delivery draft routes and no overlay grants. Drafts don't need site/token.

Spec: deco-sites/docs-tanstack#5 (into #4's branch): content-delivery#draft-previews, hosted-drafts (#who-may-preview), api-reference (#draft-pointers, #loaders), content (#write-a-loader), releases-and-drafts.

Draft pointer contract (what the SDK enforces)

• Pointer (in ?__draft= and the __deco_draft cookie, v7's name; ?__draft=off ends a preview): <studio host>/api/<org>/decofile/<project>/<branch>/changes?token=<draft token>@<version>. The version is the commit of the editor's last save; Studio doesn't read it, it only gives each save a new address.
• Allowed hosts (v7's rule, 773229cc): the preview API domains v7 shipped: the .decocms.com suffix (studio.decocms.com, pr-*.pr.studio.decocms.com, local.studio.decocms.com) and localhost, 127.0.0.1, [::1], *.localhost. DECO_PREVIEW_API_DOMAINS (a comma list; a leading dot is a suffix match on a label boundary, anything else an exact host) replaces the list, exactly as in v7. Never content. A port is allowed only on loopback hosts and local.studio.decocms.com. Anything else is refused before any fetch: look-alikes (evil-decocms.com, studio.decocms.com.evil.example), metadata IPs, userinfo, schemes, // paths.
• Request: GET https://<host><path>&v=<version> (?v= when the path has no query). The scheme comes from the domain that admitted the host: plain http only for localhost, *.localhost, 127.0.0.1 and [::1]. The pointer's __variant parameters are removed first. The request has no cookies, no authorization and no site token, and redirect: "manual" means a redirect is a failure. A response that was redirected anyway (a fetch polyfill such as React Native's or whatwg-fetch ignoring redirect: "manual"), or whose URL has another origin, is refused. The version is URL-encoded into v.
• Accepted response: status 200 only, at most 16 MiB (refused while streaming, or up front on content-length), within 10 s. The body must be exactly { "format": 1, "set": { "<block>": <block JSON> }, "delete": ["<block>"] }: no other keys, string names, no repeats, and set and delete disjoint.
• Layering: production is captured once per client: the client's release, the content module or the latest hosted release. A block in set replaces production's whole (draft wins per file). A block in delete is absent from lookup and list. Every other block is production's own object, and production is never mutated. list is production's names plus set's, minus delete. Forced variants apply on top. The draft's revision is the opaque <release revision>~<version>, and forRevision can't reach it.
• Failure: a parse error, refused host, network error, timeout, non-200, oversize or bad shape makes every call on that client return LOADER_FAILED, with the cause. It never falls back to published content.
• Caching: changes are kept per pointer without its variants, so every variant shares one fetch. Each is reused for up to 60 s (so the token is checked again), with at most 3 per CMS, and all are dropped when the release changes or on a hot reload. Failures aren't reused.
• local: a pointer whose version is local (deco serve) names no draft. Nothing is fetched, and only its forced variants apply.
• Release checks: these are unchanged. A draft client schedules the same background check as any client, and it never runs in front of the draft.

Breaking changes (v8 prerelease)

• Loader.load() takes no pointer. Drafts are the CMS's job and work over any loader, so custom-loader drafts are gone.
• remoteLoader serves releases only.
• Removed from @decocms/blocks/protocol: computeBlockHash, computeOverlayVersion, DRAFT_OVERLAY_FORMAT, DraftOverlay. Removed from /protocol/conformance: draftOverlayFixtures.
• parseDraftPointer now also accepts a bracketed IPv6 host ([::1]:4000). (preview.sources, added earlier in this PR, is removed again in 773229cc in favour of v7's DECO_PREVIEW_API_DOMAINS.)

CMS settings block

One optional, well-known saved block, CMS (.deco/blocks/CMS.json), of the built-in type cms-settings, replaces the telemetry and analytics built-ins and the Telemetry / Analytics saved blocks outright (v8 is prerelease-only, so there are no aliases):

{ "__resolveType": "cms-settings",
  "preview":   { "hosts": ["staging.example.com"] },
  "telemetry": { "enabled": true, "metrics": true, "errorSampleRate": 0.05, "traceSampleRate": 0 },
  "analytics": { "enabled": true, "collector": "…" } }

• Each section keeps the fields and defaults its old block had. Without the block, every default applies. Any field can have variants.
• Code keeps destinations, secrets and caps: telemetry: { endpoint, headers, limits } and analytics' code options, as before, plus preview: { hosts }, the most content may allow (as telemetry.limits caps the rates).
• Read path: cms.settings() is typed, with defaults filled in and caps applied. It reads the current production release already in memory: the bundled content at boot and offline, and the hosted release once the background check swaps it in. It never fetches, never reads a draft and never rejects. Telemetry, analytics (AnalyticsScript in the root layout reads (await cms.settings()).analytics) and the draft helpers all use it. The result is frozen.
• deco schema emits cms-settings. deco check points a leftover telemetry/analytics block at CMS and warns on a CMS of another type.
• Migration (deco-v7-to-v8-migration skill, siteSettings.ts): folds a v7 site's Site-block previewHosts into preview.hosts, trimmed and lowercased as v7 compared them. An invalid entry is reported. On TanStack Start, the <site>.deco.site / <site>.deco-cx.workers.dev hosts v7 added for DECO_SITE_NAME are added too, or reported when the name isn't found. It also folds a literal OneDollarStats collectorAddress and an already-migrated site's Telemetry.json / Analytics.json into their sections, variants included. It's idempotent and never replaces a CMS of another type. Settings that lived only in the environment are listed in the report.
• Site editor: Studio's "Settings" entry opens this block's form, showing the defaults. Its first save creates CMS.json with blocks.apply guarded by ifMatch: { CMS: null } (feat: support Blocks v8 (content protocol) behind a flag studio#7728).

Preview hosts

• Host patterns: exact names, *.name wildcards (whole leading label, matched label by label from the right, at least two labels after the *), "*", optional ports, and exact IPs. Matching is lowercase, ignores one trailing dot and compares punycode.
  • Look-alikes such as x.example.com.attacker.com never match.
  • A URL with a username or password, or a hostname with an empty label (a..example.com), matches only "*".
  • createCMS throws on an invalid code pattern; content drops one. A content entry counts only when it falls within code's list.
  • No cap and no block: every host may preview, as before.
• Enforcement: cms.draftPointer(request) / cms.draftCookie(request) (they replace the free draftPointer, draftCookie and DRAFT_COOKIE) ignore a draft on a host outside the effective list, so the request gets published content, never an error. ?__draft=off works on any host. This isn't access control (the signed, expiring token in the pointer is); it keeps drafts off public domains, caches and search.
• A draft never reaches the settings. Settings read only the release path, so a draft can't allow its own host or change telemetry.
• Review fixes (e7a1d1d1, 963fd2b4):
  • Each createCMS call is a handle with its own block map on the shared instance, which still shares content, caps, telemetry and update checks. Before, Next's proxy.ts importing the app's cms replaced the app's block map, and PLPs answered 500 on faststore-fila. The documented recipe works again, and faststore-fila's proxyCms.ts workaround is deleted. The same block map returns the same handle, and an instance stored by an older package copy is replaced rather than adopted.
  • A custom loader's update() keeps the last release in memory. Settings no longer fall back to the defaults (every host) until the next load.
  • The settings are deep-frozen, so one caller can't change them for every request.

Restored legacy secret guard exemption (63b07191)

A v7 website/loaders/secret.ts block marks its encrypted string "format": "secret", so the v8 secret guard refused every blocks.apply that carried one once a v7 site was edited through the content protocol. The exemption that upstream ccdf6c25 had added was lost; this restores it. v8 Secret fields stay strictly validated.

deco serve has no token (9a45c8c7, 85bf7112)

There's no bearer token, --token or DECO_SERVE_TOKEN. What protects the server is unchanged: it listens on loopback by default, browser requests need an allowed Origin, and Host must be its own address. --host 0.0.0.0 prints a 127.0.0.1 site-editor link. --host is case-insensitive, and a refused origin is logged once with the --allow-origin to pass.

Update (46c0ea4b, product-owner decision): deco serve now answers every origin (CORS reflects Origin, with Vary: Origin; Chrome's private-network preflight is still answered). Removed --allow-origin, the Studio origin allowlist, the refused-origin 403 and its log line, and the Host check. With no token either, any website open in the browser can read and write the content, so the docs say to run it only while editing.

Update (c606a458, product-owner decision): deco serve shows and links localhost: every startup line and the site-editor link (#endpoint=http%3A%2F%2Flocalhost%3A<port>%2Frpc, also for --host 0.0.0.0/::), and without --host it listens on 127.0.0.1 and ::1 on one port (::1 skipped where IPv6 is unavailable), so http://localhost:<port> reaches it either way. --host still listens on that one address.

Product-owner fixes (773229cc)

• Content protocol handler has no auth. createContentHandler/createAssetHandler lose token, authorize and the receipt scope (server/auth.ts deleted); the client loses token. Who may call the handler is the mounting server's job: deco serve on loopback, Studio's /rpc behind Studio's session. ErrorCode.Unauthorized/Forbidden stay as vocabulary for such a host.
• Unused protocol options deleted: requestKey + idempotency receipts (describe.writes), ifSchemaMatch (+ Conflict.data.schema), the ref parameter and refs/autoCreate, and describe.limits with the read/batch limits (list, schema, batch response) and their limits options. blocks.apply keeps its own guards as internal constants (500 names, 1 MiB per entry, 8 MiB per request); ifMatch and assets.maxBytes stay; a removed parameter is now an unknown one (InvalidParams). ContentStorage: snapshot() and readSchema() take no options; StorageDescription loses refs/idempotency/limits; getReceipt, StoredReceipt, CommitAttempt.ref/receipt and applyRequestDigest/APPLY_DIGEST_DOMAIN are gone. resolvedRef and expectedSchemaVersion (the secret guard's) stay. Conformance suite updated (no limit/idempotency/ref/token cases; apply guards checked against the constants; apply/unknown-params covers the removed names).
• Draft cookie is __deco_draft again (v7's name), still HttpOnly; Secure; SameSite=None; Partitioned, and ?__draft=off.
• Draft pointer hosts follow v7 (see the contract above); preview.sources is removed.
• Telemetry reads v7's names as aliases: DECO_OTEL_{METRICS,LOGS,TRACES}_ENDPOINT → OTEL_EXPORTER_OTLP_{METRICS,LOGS,TRACES}_ENDPOINT (full per-signal URLs, now honoured too), DECO_OTEL_HEADERS → OTEL_EXPORTER_OTLP_HEADERS, and DECO_OTEL_AUTH_TOKEN as the authorization header unless the headers set one. The standard name wins when both are set; a signal with no URL is dropped.
• Downstream: Studio's GitHub storage (repo-content-storage.ts) must drop refs/idempotency, its ref checks and the { ref } arguments to snapshot/readSchema; nothing in Studio used the other removed options.

Commits

• 773229cc product-owner fixes (above): no handler auth, unused protocol options deleted, __deco_draft, v7 draft hosts + DECO_PREVIEW_API_DOMAINS, DECO_OTEL_* aliases.

• e07ae05d review fixes: refuse a redirected draft response (or one from outside preview.sources) even when a fetch polyfill followed the redirect; URL-encode the version. Conformance DP-21.

• 5f9dd074 fast-preview drafts: the pointer returns only the branch's changes; draftChanges.ts (fetch, checks, layering), preview.sources, Loader.load() without a pointer. Removes the overlay/blob/grant machinery and its protocol exports, fixtures and DO-1..18 conformance; adds DP-1..20.

• 5020aea2 overlays (superseded by 5f9dd074): loader, protocol helpers, conformance DO-1..DO-14.

• b69e7634 no preview-server concept (comments, DO-18 wording, HD-18 one-host recipe gating pointer and cookie); check-schedule tests (HP-5..8, cms interval tests) await exactly the background work they scheduled, so they no longer flake under load.

• 0141f5a5 deco schema: @format on a type alias reaches every field of that type (plain, optional, nullable, listed, literal select), so /** @format color */ type TextTone = "black" | "white" gets v7's format: "color" with its values kept. A field's own @format wins. Unit test + conformance sch-26; documented in schema.mdx.

• 3a985534 v7→v8 migration skill: unwraps v7 async-rendering wrappers (website/sections/Rendering/Lazy.tsx, SingleDeferred.tsx, Deferred.tsx) to the sections they held, in pages and saved blocks; idempotent, with fixtures.

• 32650f6b review fixes (overlay parts superseded):

  • grant expiry on warm servers (manifest max-age, 60 s CMS draft TTL)
  • forDraft schedules the release check
  • per-caller block budget
  • one shared BoundedMap (LRU, optional size) instead of two map classes
  • the composed-view cache is removed, since ContentStore already keeps drafts

• 63b07191 restored legacy secret guard exemption (above).

• 9a45c8c7, 85bf7112 deco serve has no token; link on a wildcard host, case-insensitive --host, refused origins logged.

• dddefd54 the CMS settings block, cms.settings(), host patterns, cms.draftPointer/cms.draftCookie, schema/check support, migration fold, docs.

• e7a1d1d1 review fixes: per-call block maps (the Next proxy bug), settings held across a custom loader's update, frozen settings, userinfo and empty-label hosts, migration host normalisation and the TanStack deco-hosted hosts, the stale observability fixture.

• 963fd2b4 an instance stored by an older package copy is replaced, not adopted.

• 766b0ff7 schema.get with no schema yet returns { notModified: false, version: null, resolvedRef, schema: null } instead of NotFound (no .deco folder is still NotFound); blocks.list/blocks.apply already work without one. Conformance schema/absent + cp-31; docs: content-protocol "No schema yet" (docs commit befb394e, imported by deco-sites/docs-tanstack#4). Studio side: feat: support Blocks v8 (content protocol) behind a flag studio#7728.

Tests

• bun run check (typecheck, biome, knip) passes.
• bun run test at 773229cc: 1863 passed, 64 skipped (71 files).
• Conformance DP-1..DP-21 (delivery.test.ts), one per documented claim:
  • request shape (URL, v, no variants, no cookies/credentials/site token, no redirects)
  • set/delete layering, and list as the union minus deletes
  • production captured once per client
  • opaque revision
  • host allowlist with bypass attempts (look-alikes, sibling/sub domains, loopback, metadata IP, userinfo, scheme, //, backslash, uppercase)
  • DECO_PREVIEW_API_DOMAINS replacing the default, not settable from content
  • scheme per host
  • non-200 and redirects
  • 16 MiB while streaming and by content-length
  • 10 s timeout
  • strict shape
  • failures as LOADER_FAILED on every call, never reused
  • bad token
  • 60 s / 3-entry reuse
  • no site/token needed or sent
  • local pointers
  • forced variants sharing one fetch
  • empty changes
  • release checks never in front of a draft
  • __proto__ entries
  • a redirected response refused even when the fetch followed it
• HD-2/3/4/8/15/16, CD-1, RD-7, H-5, HRI-10, AR-08/11/18/22/66, RD-02, X21, dd-11, si-10, cms/settings unit tests: rewritten for the pointer flow. Bracketed IPv6 pointer parsing is in draft.test.ts.

Decisions (product owner)

1. There are no preview servers. A server that renders a draft is a production server rendering the draft a pointer names. The release check is unconditional and identical whether or not it serves drafts. Done in the SDK comments, DO-18, the HD-18 recipe and the docs.
2. Drafts are the v7 fast-preview pointer, returning only the branch's changes (supersedes the overlay design: no /preview, no preparing state, no object-storage overlays, no grants). Accepted with the docs' decisions:
   • Loader.load() has no pointer.
   • The default source is exactly studio.decocms.com. Superseded by decision 6.
   • An old link shows the branch's current changes while its token is valid.
   • A local version names no draft.
3. Editor-form differences (Eitri app): the color picker is fixed in deco schema (@format on a type alias reaches its fields). The other differences are accepted.
4. Async rendering: v8 has none, and the migration unwraps v7 Lazy/Deferred wrappers.
5. One CMS settings block. Preview hosts, telemetry and analytics live in the optional saved block CMS (type cms-settings), which replaces the telemetry/analytics built-ins and blocks outright. Code holds destinations, secrets and caps, including preview.hosts. cms.settings() reads only the production release in memory, never a draft and never the network. Drafts on a host outside the list get published content. The site editor edits the block under "Settings". There's no channel-manifest setting and no protocol change.
6. v7 compatibility, fewer mechanisms (773229cc): deco serve and the protocol handler have no token (Studio's session protects its /rpc); the cookie is v7's __deco_draft; draft hosts are v7's domains with DECO_PREVIEW_API_DOMAINS; v7's DECO_OTEL_* names keep working; unused protocol options (request keys, schema preconditions, refs, advertised limits) are deleted.

---

Stack: v8 ← … ← 15 ← 16

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig

---

Summary by cubic

Hosted drafts now load as a pointer to only the branch's changes, layered over the production snapshot already in memory. The PR also centralizes preview, telemetry and analytics settings in the CMS block, moves draft helpers onto the CMS, and drops the content protocol's shared authentication and deco serve's bearer token, origin allowlist, and Host check. The conformance tests now read the docs from deco-sites/docs-tanstack.

Drafts and settings

• A draft pointer fetches only the branch's changes — a { format, set, delete } document — layers them over production, applies tombstones and variants, and fails with LOADER_FAILED without a published fallback. Its hosts follow v7's patterns exactly (.decocms.com suffix, local.studio.decocms.com, localhost, 127.0.0.1, *.localhost; [::1] is no longer a default, but a listed [::1] still counts as loopback), with DECO_PREVIEW_API_DOMAINS replacing the list.
• The draft cookie is __deco_draft again and preview.sources is gone. cms.settings() reads release settings without fetching, applies defaults and caps, and gates cms.draftPointer() and cms.draftCookie() by configured preview hosts.
• telemetry and analytics built-ins are replaced by the cms-settings block; existing sites must migrate these settings into .deco/blocks/CMS.json, and telemetry also reads v7's DECO_OTEL_* environment names as aliases.
• The shared instance returns a handle per block map, so a second bundle no longer replaces another's; a stale stored instance from an older package copy is replaced, and settings survive an update (last release kept in memory, deep-frozen) instead of falling back to defaults.
• The content protocol handler no longer authenticates: neither the handler nor its client takes a token, and who may call it is the mounting server's job (Studio's session, deco serve on loopback). Request keys and idempotency receipts, ifSchemaMatch, ref params and describe.limits are removed; blocks.apply keeps its own guards (500 names, 1 MiB per entry, 8 MiB per request).
• Host matching for preview.hosts tightens: URL credentials make a host unreadable except by *, and an empty label matches nothing but *.

Migration and tooling

• The v7 migration skill now supports native apps, Next.js/VTEX and non-ejected FastStore storefronts, folds legacy site settings into CMS.json, and unwraps v7 async-rendering wrappers. Lessons from a second TanStack + VTEX storefront cover the removed /deco/invoke (one server function per call site), gating draft bypass on cms.draftPointer, module-level config singletons as cross-request state, and parity gotchas (pin request.cf, track flake counts). The FastStore one covers a vendored runtime built from the published package, Pages Router SSG drafts hooked into Next's compiled runtimes, listing the dev host in preview.hosts, and deco check gating the build. A placeholder site name replaces fila-store in the deployment skill.
• previewHosts are trimmed, lowercased and validated as host patterns, with the TanStack default hosts (<site>.deco.site, <site>.deco-cx.workers.dev) added when the site name is found; @decocms/blocks/cli exports the host parser.
• Schema generation preserves literal order and alias-level @format annotations, maps datetime to date-time, avoids saved-block pickers for free-form maps, and stamps every schema with blocksMajor: 8 — the only signal Studio reads to tell a v8 site from a v7 one — which deco check requires.
• schema.get reports "no schema yet" as schema: null (with version: null) instead of NotFound, so clients can list and edit blocks without typed forms and keep polling until one appears.
• deco serve has no bearer token, --allow-origin, or Host check: it answers any origin's CORS, so it's for editing only, and without --host it listens on 127.0.0.1 and ::1 on one port, so every startup line and the site-editor link say localhost.
• Legacy website/loaders/secret.ts blocks are excluded from the v8 secret guard so their existing ciphertext is preserved.

^{Written for commit 73bc4f3. Summary will update on new commits.}