feat: support Blocks v8 (content protocol) behind a flag

[tlgimenes]

What is this contribution about?

The Studio site editor can now edit sites built on next-major Blocks (@decocms/blocks@8) through the Blocks content protocol. Editing a local deco serve (the account-less /site-editor route, and the Local draft environment when signed in) needs no org flag; the GitHub-backed protocol is behind the org flag below. The editor reads the committed schema and .deco/blocks and never runs the site's code. All of it sits behind the default-off org flag site_editor_content_protocol. With the flag off, Studio behaves as it does today.

What's in

• Protocol from @decocms/blocks. Studio depends on the published @decocms/blocks, pinned exactly at 8.1.0-next.6, and imports its public @decocms/blocks/protocol, /protocol/server, /protocol/conformance, /protocol/storage/fs and /secrets subpaths. See "How Studio gets the protocol" below.

• GitHub backend (API). It serves the protocol over a project's repository:

  • POST /api/:org/decofile/:virtualMcpId/:branch/rpc runs createContentHandler from @decocms/blocks/protocol/server over a storage built on RepoContentClient (apps/api/src/decofile/repo-content-storage.ts).
    • The revision is the branch head; block versions are git blob SHAs.
    • The schema comes from schema.gen.json, then meta.gen.json, then the default branch. It is served only when it says "blocksMajor": 8; a v7 site reads as schemaless and any write to it is refused (Unsupported), so even a direct API call can't write a v7 site.
    • A missing draft branch reads as the default branch, and the first write creates it.
    • Writes are guarded on the branch head. A provider conflict comes back as "stale", so the protocol core retries.
    • A tracked blocks.gen.json is regenerated in the same commit (gen-artifact.ts, shared with the existing commit coalescer).
  • GET .../changes answers what the draft branch changed against production, for the site's ?__draft= pointer. Like v7's read and save, every /rpc answer carries the pointer's token (X-Deco-Draft-Token, X-Deco-Api-Host headers, since the body is the protocol's). See "Draft previews" below.
  • These routes return 404 while the flag is off.

• Which backend a project uses (web). One selector decides:

  • flag off → legacy (except a local deco serve connection, which is always v8);
  • connected to deco serve → protocol on the local server;
  • Local tunnel → legacy;
  • Fast Preview (cms) session whose branch has a committed schema → protocol on GitHub;
  • anything else → legacy.

  Sandbox sessions stay legacy. A failed GitHub check is never read as "no schema": the project shows as unavailable and the check retries.

• Reading and writing (web).

  • One batched blocks.list + schema.get per poll, using ifNoneMatch, at describe.pollIntervalMs and on window focus.
  • Each save is one blocks.apply, and the client adopts the returned revision.
  • On GitHub, the ?__draft= link is the v7 Fast Preview pointer, naming the branch's changes (see "Draft previews" below). "Exit preview" still uses ?__draft=off.

• Connecting to deco serve. No token anywhere: Studio never sends one, ignores token= in old links, remembers the endpoint per browser, reconnects on its own, accepts only 127.0.0.1/localhost/[::1] /rpc endpoints.

  • 7d1a2c79c: deco serve now answers every origin (blocks#619), so the empty state shows plain npx @decocms/blocks serve on any Studio origin; the --allow-origin guidance, its en/pt-br strings and the official-origin check are gone, and the e2e stub reflects any Origin.
  • c97b68ba3: deco serve is on localhost (blocks#619): the default endpoint is http://localhost:4545/rpc and every label shows localhost:<port>; links and remembered endpoints on 127.0.0.1 or [::1] still open and are read as localhost, so a returning user's stored server matches a new link.
  • The CLI prints <studio>/site-editor#endpoint=…&token=…. /site-editor takes the token out of the URL and keeps it for this tab only, so a reload keeps the connection. Signed in, the same link pasted into the draft selector's Local option connects a project.
  • Only servers on this machine are accepted (127.0.0.1, localhost, [::1], *.localhost).
  • The screen shows the server address and folder. The first request is what triggers Chrome's local-network prompt.
  • The editor shows a "Local server" chip (and "Read-only" when deco serve --read-only). There is no Disconnect: on /site-editor the connection follows one rule (see "Guided site editor empty state"); in a project, choosing a draft in the selector leaves Local.
  • Uploads go to PUT <server>/assets/<name> and respect describe.assets.maxBytes. On a deco serve connection, /assets/… thumbnails load from the dev app.

• v8 content shapes.

  • A name in the manifest is a block type, not a saved block. Saved-block names can't reuse a block type's name.
  • The page list, "new page" and the URL field use the manifest's pages group, so the built-in page and route blocks such as post appear.
  • Lazy<T> fields edit T and save the {"__resolveType":"lazy","value":…} wrapper; lazy is never offered as a pick.
  • The built-in multivariate wraps each variant's value in lazy; the legacy multivariate names keep plain values.
  • Redirects read and write both the nested and the flat shape, each in the shape it was read. New redirects use the nested shape. Flat redirects get an optional status (301/302/307/308) and discardQueryParameters, and keep fields the editor doesn't know.

• Secret widget. Write-only:

  • What the editor types is encrypted in the browser with describe.secrets.publicKey (RSA-OAEP/SHA-256 + AES-256-GCM, the protocol's ciphertext format). Only {"__resolveType":"secret","ciphertext":…} is sent.
  • With no public key, the field asks for .deco/secrets.pub.
  • v7 secrets say they can't be edited here.
  • While the backend is undecided or unreachable, the field shows a message instead of the legacy secret field, which would post plaintext to the site's encrypt action.

• What isn't available on the protocol. Nothing renders in place, and the add-section gallery shows each block's name, description and schema @image. Loader-backed pickers fall back to the schema's options or free text. Run, runnable loaders and actions, and app install are hidden.

• Settings (CMS settings block, v8). A "Settings" row in the Content sidebar opens the form of the site's well-known CMS block (type cms-settings: preview hosts, telemetry, analytics), from the schema. It knows only that name and type. It's offered only when the schema describes the type, so not on v7 sites or on 8.1.0-next.3, and a CMS block of another type gets an explanation instead of a form.

  • With no block yet, the form shows the defaults. The first change creates CMS.json with one blocks.apply guarded by ifMatch: { CMS: null } (b4bfc9124), so a CMS created meanwhile, of any type, is never replaced.
  • If the guard refuses the save, the editor reads the content again once the branch's writes settle, then shows the saved block or the explanation. After a guarded save lands, saves are unguarded like any other block's.
  • The guard goes through useSaveBlock / useDebouncedSaveBlock (SaveGuard, decided when the save runs) to applyProtocolPatch. Only the content-protocol backend sends it.

• Other.

  • site-editor is now a reserved organization slug.
  • Docs: none in this repo any more. main retired the docs workspace ([chore]: retire legacy documentation workspace #7763), so the "Next-major Blocks sites" section this branch added to agentic-cms.mdx was dropped in the merge; see "Merged main" below for what still needs a home.

Flag: site_editor_content_protocol, off by default. It gates the GitHub-backed protocol only; /site-editor and the Local draft environment work without it. It is not in DEFAULT_ON_FLAGS and has no settings UI. Turn it on for an org with ORGANIZATION_SETTINGS_UPDATE, passing { "flags": { "site_editor_content_protocol": true } }.

How Studio gets the protocol

From npm: @decocms/[email protected] (exact pin, dist-tag next) is a dependency of apps/api, apps/web and packages/e2e. Nothing is vendored: the old packages/shared/src/vendor/blocks-protocol, its SYNC.md and scripts/sync-blocks-protocol.ts are gone. Every import maps to a public export:

Studio uses	From
client, errors, types, storage contract, file-name rule	@decocms/blocks/protocol
createContentHandler (GitHub endpoint, deco-serve e2e stub)	@decocms/blocks/protocol/server
runConformance (GitHub e2e)	@decocms/blocks/protocol/conformance
createFsStorage (deco-serve e2e stub)	@decocms/blocks/protocol/storage/fs
encryptSecret (secret field)	@decocms/blocks/secrets

Three pieces the vendored copy exposed have no public export, and the framework wasn't widened for them:

• Ciphertext parser (ciphertext, secrets): @decocms/shared/secret-ciphertext is a small reading of the documented v1.<wrappedKey>.<iv>.<ciphertext> format. It checks that a Secret field holds a well-formed ciphertext, and gives tests what they need to decrypt one. Encryption itself uses encryptSecret.
• In-memory storage (storage/memory): the deco-serve e2e stub now runs the public filesystem storage in a temp working tree, like deco serve, and reads the saved files from disk.
• Asset handler (server/assets): dropped from the stub, since no spec uploads.

@decocms/blocks ships TypeScript sources. Bun (API) and Vite (web) load them as they are. Playwright runs on Node, which won't strip types under node_modules, so e2e imports the runtime pieces through packages/e2e/fixtures/blocks-protocol.ts. That file registers tsx first, the same way the package's own deco bin does. @decocms/blocks and tsx are on the e2e import allowlist.

Async rendering is off on v8. v8 has no async rendering out of the box, so on v8 sites the site editor offers no async-render control on section rows or page SEO, and never writes a Lazy wrapper. The v7→v8 migration strips Lazy wrappers, so v8 shows no async-render UI at all. The controls appear only once Studio knows the site is v7, not while the backend is still being detected. v7 is unchanged.

Out of scope

• The hosted control plane: managed drafts, sync, releases, channels, rollback and site tokens.
• Durable write receipts, ifSchemaMatch, ref/refs and read limits: removed from the protocol (v8 N-16: drafts are the fast-preview pointer, with only the branch's changes over the local release blocks#619). The GitHub storage is bound to the branch in the URL; since 8.1.0-next.6 its describe() no longer returns refs/idempotency, and a ref param is rejected as an unknown parameter (Invalid params).
• ifMatch on ordinary saves (autosave is last writer wins). The one exception is Settings' first save, which is create-only.
• Running deco serve inside sandbox pods.
• The account-less workspace.
• Uploads to Deco's hosted asset storage: on GitHub, uploads still go to Studio's file storage.

Production safety

Verdict: safe to merge with site_editor_content_protocol off everywhere. An independent re-audit at 7bd82f5b0 found nothing that changes v7 sites; its two remaining code items are fixed in a01bb071f (see below). v7 behaviour equals main.

Which sites are v8 (the blocksMajor rule). The schema's file name (schema.gen.json / meta.gen.json) does not tell the version. deco schema writes an explicit top-level "blocksMajor": 8, and deco check rejects a v8 schema without it. Studio treats a site as v8 only when its committed schema has blocksMajor === 8 (strict equality). Everything else is v7: a missing field, 7, "8", 9, null, a schema that doesn't parse, no schema file, or a failed GitHub read (retried every 5 s; a site already known to be v8 stays v8). The web (isV8Schema) and the API's /rpc storage apply the same rule: on a v7 site /rpc reads as schemaless and refuses every write.

Gating matrix

Surface	v7 site / flag off	Gate
/rpc, /changes	404	org flag site_editor_content_protocol (a failed settings read answers 404)
/rpc with the flag on, v7 site	schema reads as missing; writes refused (Unsupported)	blocksMajor === 8 at the branch head
Decofile GET/PATCH (classic editor, v7 draft links)	unchanged, no org-settings read	none needed
Editor backend choice, new blocks editor, v8 badge	classic editor, new_blocks_editor flag as today, no badge	flag and blocksMajor === 8
Preview toolbar, visual edit, variant tabs	as on main	v8 only
Schema form (resolve-schema)	identical to main on every block of two real v7 metas (76 and 226 blocks)	recursion cap only bounds self-referencing types
deco serve discovery, no-schema editor	not reachable	/site-editor route and the protocol path only
Local draft URL save	public URLs saved as on main; localhost probed as deco serve (3 s) then saved as the tunnel	—
/site-editor	public by design (no login); site-editor is a reserved org slug	pre-deploy slug check below
Docker / Helm deco	@decocms/blocks is a devDependency only; .bin/deco is Studio's CLI	exact pin 8.1.0-next.6 in api, web and e2e

Fixed after the re-audit (a01bb071f)

• /rpc now enforces blocksMajor server-side (repo-content-storage.ts): readSchema returns no schema unless it is v8, and commit throws Unsupported: not a Blocks v8 site. New e2e: a v7 schema over /rpc with the flag on is not served and not written.
• resolve-schema.ts: array items whose $ref is a union (a matcher inside Multi) stay resolved as on main, so nested matchers keep their branch schema and defaults. Re-run over the two real v7 metas: 0 of 76 and 0 of 226 blocks differ from main (previously multi.ts/negate.ts differed).

Release order

1. Merge with the flag off everywhere. Pre-deploy: run the slug check below; docker build the API image and confirm /health answers (CI's docker-smoke builds the sandbox image, not the API image).
2. Before enabling anywhere: release @decocms/blocks with BLOCKS_MAJOR (deco schema writing "blocksMajor": 8), bump Studio's exact pin, and re-run deco schema and commit in each v8 site (storefront-tanstack, blog-tanstack, faststore). Until then no site is recognized as v8 (the safe failure: they stay v7).
3. Enable the flag for one internal, v8-only org.
4. Watch API errors (/rpc, /changes) and GitHub API usage / rate limiting for that org.
5. Widen to more orgs.

How did you verify your code works?

Run on the final tree (5d1756b52):

Check	Result
bun run fmt:check	passed
bun run lint (oxlint)	passed
bun run knip	passed (two configuration hints about packages/runtime, a package this PR doesn't touch)
bun run check (typecheck of every workspace)	passed
bun run test	10170 pass, 0 fail
tsc --noEmit for web, api, shared and e2e on every commit of the branch	0 errors on each

New or updated unit tests:

• the backend selection rules, including a failed GitHub check;
• the poll merge;
• loopback-only site editor links;
• manifest-driven pages and the page type for new pages;
• flat redirects keeping unknown fields;
• Lazy<T> and multivariate values;
• the secret encrypt round trip;
• reserved slugs.

Upstream (Blocks protocol) tests: vitest packages/blocks/src/protocol, 492 pass, plus a new test that a legacy secret loader block passes the secret guard.

E2E. content-protocol-deco-serve.spec.ts passes locally against the published package (4/4, and 8/8 with --repeat-each=2). With the Settings tests (b4bfc9124): 7/7 against the local framework link. Under a heavily loaded machine, refuses a link to a server off this machine once missed its 5 s wait; it passed on every rerun. content-protocol-github.spec.ts loads and runs, but it needs the e2e API environment (the GitHub stub and its env). Against a plain dev server it fails on sign-up rate limits and on the missing stub, so CI is the signal for it.

• content-protocol-github.spec.ts:
  • the full protocol conformance suite against the GitHub endpoint;
  • flag off gives 404; anonymous callers get 401;
  • a branch other than the bound one is refused;
  • the first write creates the branch;
  • a tracked blocks.gen.json is regenerated;
  • a legacy site's secret loader block saves.
• content-protocol-deco-serve.spec.ts:
  • Settings: the defaults show, and the first save creates CMS.json with ifMatch: { CMS: null }; the second save carries no guard;
  • a CMS of another type written behind the editor's back survives the first save, and the editor explains it;
  • the /site-editor link flow, including that the server address is shown;
  • a link to a server off this machine is refused;
  • editing a plain field, a Lazy<T> field (stored wrapped) and a secret: the stored ciphertext decrypts with the test's key, and the plaintext never appears in storage or in a request.

Run them with bun run --cwd=packages/e2e test:e2e content-protocol. The existing decofile-api.spec.ts and fast-preview-git-sync.spec.ts are unchanged.

Screenshots/Demonstration

To add: the /site-editor screen (server address and folder), the "Local server" chip, the secret widget, and the page list on a v8 site.

How to Test

1. Turn on site_editor_content_protocol for a test org.
2. GitHub: open a Fast Preview project whose branch has .deco/schema.gen.json.
   • The blocks list and the schema load without the site running.
   • Edit a field: each save is one commit on the draft branch.
   • The preview opens the real site with ?__draft=….
3. deco serve: in a v8 site run npx @decocms/blocks serve --preview localhost:<app port> (with the app's dev server running) and open the /site-editor#endpoint=… link it prints (no token: deco serve has none).
   • Allow Chrome's local-network prompt.
   • Edits are written to the working tree, and uploads go to the server's assets.
   • Stop the server: the chip says to start it. Restart it with a new token: the chip asks you to reconnect.
4. Open /site-editor#endpoint=https://example.com/rpc&token=x: you should see "This site editor link is incomplete", in the New Layout whatever the preference says.
5. Turn the flag off: the editor is back on the legacy path, and /rpc and /changes return 404.

Migration Notes

• No database migrations.
• Pre-deploy step: site-editor is now a reserved org slug. Before deploying, confirm no existing organization uses it (SELECT id, slug FROM organization WHERE slug = 'site-editor'; must return no rows); I couldn't check production data. The check is also documented next to the route in apps/web/src/router.tsx.

Follow-ups

• Move the exact pin from 8.1.0-next.6 to the stable @decocms/blocks@8 once it's released.
• Durable write receipts and ifMatch on every save, with managed drafts.
• deco serve in sandbox pods, so sandbox sessions on v8 sites can use the protocol.
• Blog tab detection from the manifest, and the page types each section is allowed on.

Review Checklist

• PR title is clear and descriptive
• Changes are tested and working (unit, typecheck, lint, format, knip and web build green; deco-serve e2e green locally; GitHub e2e runs in CI)
• Documentation is updated
• No breaking changes (the GitHub-backed protocol is behind a default-off flag; /site-editor is reachable only by URL; the Local option keeps today's tunnel behaviour for any non-deco serve URL)

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig

Draft previews: the Fast Preview pointer, changes only

v8 keeps v7's Fast Preview protocol: the site gets a ?__draft= pointer and fetches it. The only change is what the pointer answers: what the draft branch changed against production, not the whole decofile. The site's cms.forDraft(pointer) layers it over the production content it already has (blocks docs: /next/content-delivery#draft-previews; SDK side: decocms/blocks#619).

Pointer (same shape as v7, with a /changes suffix)

• <apiHost>/api/<org>/decofile/<vmcp>/<branch>/changes?token=<draft token>@<revision>.
• The token is the existing v7 draft token (signDraftToken): HMAC-signed, scoped to org, project and branch, 6 hours.
• The version is the last revision the editor saw. Studio doesn't read it; a new save gives the pointer a new address, so the preview refetches.
• The token comes the v7 way: v7's read and save return it in their body, and every /rpc answer (session only, so a draft token can never mint another) carries it in the X-Deco-Draft-Token and X-Deco-Api-Host headers. The editor's protocol client stashes it, and replaces it only an hour before its 6-hour expiry, so polling doesn't reload the preview iframe. There is no separate token route.

Answer (GET .../changes, apps/api/src/decofile/draft-changes.ts)

• {format: 1, set: {name: block JSON}, delete: [names]}, computed from Git on every request. Nothing is prepared or stored.
• Studio diffs the branch head against its merge base with the production branch, file by file. The merge base comes from a dedicated RepoContentClient.mergeBase (GitHub: compare?per_page=1, reading only merge_base_commit; GitLab/Bitbucket: their merge-base endpoints), never the full compare payload, so a branch far from production doesn't time out:
  • an edited block file wins whole;
  • a deleted file becomes a tombstone;
  • aliases resolve by the shared key rule;
  • only changed bodies are read, through the blob cache.
• A computed answer is reused for up to 60 s per branch head (at most 100 heads), so repeated preview requests cost one getBranch call. A new save is a new head.
• A branch that doesn't exist yet changed nothing ({format: 1, set: {}, delete: []}), so a pointer minted before the first save works.
• Cache-Control: no-store, Access-Control-Allow-Origin: *.
• Errors: 401 without a valid token or session, 404 with the flag off, 409 on a provider conflict, 413 over 8 MiB of changed blocks, 422 when a changed block isn't valid JSON ({error, file} names it), 502 for the Git provider.
• Known gap: unscheduled blog planning posts aren't projected into /changes the way the v7 anonymous read projects them (projectPlanningPostsForPreview), so they don't show in v8 previews yet. Documented; blog-tanstack doesn't use drafts today.

v7 unchanged

• The plain GET .../:branch and PATCH behave exactly as on main: whole decofile for the anonymous ?token= read, and a fresh token on every editor read and write.

Editor

• useProtocolDraft builds the pointer from the stashed token and the current revision. There is no readiness state: until the first /rpc answer there is no pointer, as with v7 before its first read.

Tests

• draft-changes.test.ts: merge base, aliases, __proto__, app roots, missing branch, size limit, delete-only branch, rename (delete + set), deleting the winning spelling of an aliased name, malformed block JSON, per-head reuse.
• e2e (content-protocol-github.spec.ts): flag off and anonymous access, /rpc answers carry the token and a token can't call /rpc, a save shows only its changes in /changes, the token is scoped to its branch, and the v7 read of the same branch still returns the whole decofile. decofile-api.spec.ts (v7) is unchanged.
• The GitHub e2e stub compares commit shas, as GitHub does.

Replaced the overlay delivery with the changes pointer

• Removed POST .../preview, revisionOnBranch, GET .../site-connection, the /rpc post-commit overlay hook, overlay uploads to object storage, /api/_delivery (draft-delivery.ts), overlay grants and site tokens, the "Preparing preview" state and draft-preview-loop.test.ts (it ran the overlay SDK; the changes SDK isn't published yet).
• draft-token.ts, paths.ts, key-utils.ts and org-fs.ts are back to main.

Testing v8 locally

• /site-editor (no account): a top-level route that is not gated: no org flag and no preference. It always renders in the New Layout (the project-first app takeover), even when the user's New Layout preference is off; a route-scoped override (ForceProjectFirstNav, set only by routes/site-editor.tsx) does that without a second copy of the layout. It opens the same Site Editor app a project launches (its Preview and Content tabs; Preview has the page picker; Content edits blocks and saves through deco serve), full screen with no sidebar. Hosted features are hidden: no chat, GitHub, drafts, publishing/releases or Code tab. It talks to a local deco serve over the content protocol. The connection arrives in the URL (/site-editor#endpoint=…&token=…); Studio removes the token from the address bar, keeps it for that tab only, and strips it from analytics. Only servers on this machine are accepted.
• Site Editor active in the sidebar: in the New Layout rail, the Site Editor app entry is active at /:org/:project/site-editor (and its Content and Code tabs) and at /site-editor. Signed in on /site-editor, the rail lists the user's orgs, then the Site Editor entry, highlighted (aria-current="page", linking to /site-editor); signed out there is no rail. There is no org there, so no recent app is recorded.
• Verified against a migrated storefront: storefront-tanstack (feat/next-major, @decocms/[email protected]) with deco serve --preview localhost:5190, driven with Playwright, signed out at /site-editor and signed in through a project's Local environment: the schema loads (recursive commerce Product types no longer freeze the tab), the preview frames the real storefront, a text edit lands in .deco/blocks/pages-home.json and shows in the preview about 2s later, and Replace image uploads through deco serve (/assets/<name>). Site-side fixes that made this work: frame loads get frame-ancestors for Studio instead of X-Frame-Options: SAMEORIGIN, vite dev skips the edge cache, and the dev server reloads open pages when the content module changes.
• Preview URL: deco serve reports the app URL in the content protocol's describe (describe.preview.url). Set it with deco serve --preview localhost:8001 (host:port or a full URL); by default it reads server.port from the Vite config, else http://localhost:5173. Studio loads it in the Preview tab only if it is a loopback URL. The signed-in Local draft environment uses the same value.
• Signed in: the Local draft environment. In the draft environment selector, Local replaces the old localhost option. Paste a deco serve link and Studio checks the server answers, then switches the project to v8 (inline errors when the server stopped or restarted with a new token). Any other URL is a tunnel, handled exactly as today (v7). Works for every org without a flag; the GitHub-backed protocol stays behind site_editor_content_protocol.
• Variant tabs on v8: a v8 site has no x-deco-matchers-override, so a variant tab forces its variant in the preview's ?__draft= pointer instead. It adds one reserved __variant=<block>@<path>=<index> parameter per forced variant, and cms.forDraft applies them (v8 N-15: preview a forced variant through the draft pointer; dev reload recipes blocks#618). For local deco serve it is a pointer to the serve endpoint carrying only the forced variants, never the token. On the GitHub backend they go into the Fast Preview pointer. v7 projects keep the header. Verified live against storefront-tanstack: variant 2 shows on its tab, variant 1 comes back on its tab, and a forced variant survives the reload after a save.
• v8 notice: a small v8 badge with a tooltip in the header of /site-editor and the signed-in site editor, on v8 sites only. v7 sites show nothing new.
• New blocks editor on v8: every content-protocol (v8) site gets the redesigned blocks editor, on /site-editor (no org) and signed in, whatever the org's new_blocks_editor flag; v7 sites keep following the flag. While the site's version is detected the editor stays in its loading state instead of flashing the old one (bbf06e2).

Guided site editor empty state

/site-editor follows one rule, with no way to disconnect:

1. Find the server: the endpoint in the link's hash (#endpoint=…, which wins), or else the last one used in this browser, then the default 127.0.0.1:4545.
2. If it answers, the editor opens.
3. If not, the empty state shows and keeps looking, backing off from 1s to 15s and pausing while the tab is hidden. The editor opens as soon as the server answers.
4. If the server stops while editing, the page goes back to the empty state and reopens the editor on its own when the server is back.

The empty state explains the site editor, shows the deco serve command to copy (with --allow-origin <origin> when Studio isn't on an official address), the "Looking for deco serve on …" line, and docs links. deco serve on another port prints a link with #endpoint=…; opening it is how you reach that port (there is no address field). On a deployed Studio that doesn't have Chrome's local-network permission yet, a single "Look for deco serve on this computer" button starts the search, so Chrome's prompt comes after a click; a denied permission is explained.

Guided messages remain only where the server answered but can't be used: out of date (asks for a token), version mismatch, another program on the port, an error, and read-only (chip). Verified headless with Playwright: a fresh context with nothing on 4545 shows the empty state; /site-editor#endpoint=http%3A%2F%2F127.0.0.1%3A4547%2Frpc opens the storefront editor; stopping the server returns to the empty state and restarting it reopens the editor; no disconnect control anywhere.

No schema yet (72ce0c33c): without .deco/schema.gen.json, the editor (/site-editor and the Local draft) still opens. Content lists every saved block grouped by __resolveType; a block opens as plain fields inferred from its JSON plus the raw JSON editor, and a save keeps every untouched value exactly; Preview's Blocks panel shows the current page the same way. One banner (npx @decocms/blocks schema with copy, docs link) goes away on its own when the schema appears. Reads schema.get's new schema: null (decocms/blocks#619 766b0ff7) and an older server's NotFound alike. Verified headless with Playwright on a storefront-tanstack copy with the schema removed: list, open, edit and save round-trip, then deco schema and the banner left.

---

Framework side: decocms/blocks v8 stack #602–#614 (spec: decocms/blocks#585). Studio consumes it as @decocms/[email protected] from npm.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig

---

Summary by cubic

Adds editing Blocks v8 sites through the Blocks content protocol, from published @decocms/[email protected]. A site is v8 only when its committed schema says "blocksMajor": 8; legacy projects are unchanged. A local deco serve needs no org flag; the GitHub-backed protocol sits behind the default-off site_editor_content_protocol flag.

What changes

• POST /api/:org/decofile/:virtualMcpId/:branch/rpc serves the protocol over the repository (git blob shas as versions, branch head as revision), regenerates blocks.gen.json in the same commit, and refuses any read or write on a v7 site.
• Drafts keep v7's Fast Preview pointer through GET .../changes, which answers {format:1, set, delete} — what the branch changed against production since their merge base, computed per request and cached briefly per head. The token comes from the v7 decofile read body, fetched on load and again after each save.
• /site-editor and the signed-in Local draft connect to a loopback deco serve with no token; the GitHub-backed protocol needs the flag.
• One content backend per project and branch; a failed GitHub probe leaves the project on v7 quietly. The editor polls one batched blocks.list + schema.get with ifNoneMatch; each save is one blocks.apply adopting the returned revision.
• v8 shapes: manifest short block-type names (blocked as new block names), Lazy<T> wrappers, the built-in multivariate, flat redirects with optional status/discardQueryParameters, and write-only Secret fields encrypted in the browser.
• A Settings row edits the site's cms-settings block; the first save is create-only, guarded with ifMatch {CMS: null}. With no schema yet, blocks open in plain fields inferred from their JSON plus the raw JSON editor.
• No async rendering UI on v8; v8 sites always get the redesigned blocks editor. Variant tabs force their variant into the preview's ?__draft= pointer through reserved __variant parameters.
• Uploads go to PUT <server>/assets/<name> within describe.assets.maxBytes; the preview loads describe.preview.url (loopback only); the add-section gallery shows schema images since site code never runs.
• @decocms/blocks is a devDependency in the API, so the Docker image runs Studio's CLI by path and the Blocks deco bin never shadows it. Before deploying, confirm no existing org uses the now-reserved site-editor slug.

Since the merge with main, the studio docs moved to deco-sites/docs-tanstack (main retired the docs workspace) and the bun.lock is main's plus only the pinned @decocms/[email protected] and its nested zod.

^{Written for commit 55f6063. Summary will update on new commits.}

Moved to published @decocms/[email protected]

• apps/api, apps/web and packages/e2e now depend on @decocms/blocks@^8.1.0-next.3 from npm (compiled dist); bun.lock has no local paths.

• Dropped the tsx raw-.ts loader (packages/e2e/fixtures/blocks-protocol.ts) and tsx from e2e devDependencies; e2e fixtures import @decocms/blocks/protocol/{server,storage/fs,conformance} directly.

• Typecheck, lint, fmt, knip, unit tests (1391 pass) and both builds pass. Two GitHub content-protocol e2e failures predate this bump (spec expects preview.origin where the protocol returns preview.url; the legacy-secret fixture encrypted: "0a1b2c3d" is rejected as malformed ciphertext) and are tracked separately.

• Fixed both GitHub content-protocol e2e failures (3332863): the spec now expects preview.url, and a bun patch carries the dropped upstream legacy website/loaders/secret.ts exemption (blocks ccdf6c25) into @decocms/[email protected] until a release includes it; v8 secrets stay strict.

• Removed the v8 unwrap-only "Disable async rendering" control (2f3f994): the v7→v8 migration strips async-render wrappers, so v8 sites show no async-render UI; v7 is unchanged.

On published @decocms/[email protected]

• apps/api, apps/web and packages/e2e now depend on @decocms/blocks@^8.1.0-next.4 (bc5b85e).
• The bun secret-guard patch is gone: next.4 ships the legacy website/loaders/secret.ts exemption upstream, so patches/@decocms%[email protected] and its patchedDependencies entry are removed. legacy-secret-guard.test.ts passes without it; v8 Secret fields stay strict.
• Typecheck (api, web) and unit tests (10295 pass, 0 fail) pass.

On published @decocms/[email protected]

• apps/api (devDependency), apps/web and packages/e2e pin @decocms/blocks exactly at 8.1.0-next.6 (b163a2d). bun.lock changes only the @decocms/blocks entries (version + integrity; its deps and peers are identical to next.4), and bun install --frozen-lockfile passes, so every other package resolves as before.
• The next.4 shim in repo-content-storage.ts (refs, idempotency: null in describe()) is gone; the e2e check that blocks.list rejects a ref param is back (now -32602 Invalid params: an unknown parameter).
• next.6 answers schema.get without a schema as a result instead of NotFound; the v7-site e2e check now asserts it never reads as a v8 schema (4a1e921). next.6 also ships the SDK side of the draft changes pointer.
• Typecheck, lint, format, unit tests (10466 pass, 0 fail) and the GitHub content-protocol e2e (10/10, one worker) pass.

Merged main (a702910, 55f6063)

• Merged origin/main (no rebase; feat/blocks-v8-hosted stays stacked on this branch).
• Docs workspace retired ([chore]: retire legacy documentation workspace #7763): accepted main's deletion of apps/docs, including agentic-cms.mdx (en and pt-br), which this branch had extended. The Blocks site-editor docs live in deco-sites/docs-tanstack (storefront/blocks/next/site-editor.mdx), which already covers deco serve, /site-editor, uploads to public/assets/, write-only secrets via .deco/secrets.pub, schema-only pickers and gallery cards. These Studio-side details from the dropped section have no home yet:
  • Studio treats a site as v8 only when its schema declares "blocksMajor": 8; any other site keeps the v7 editor, and v8 sites show a v8 badge.
  • Signed in: draft selector Advanced → Local takes the deco serve link, checks the server answers before switching, shows a Local server chip, reconnects on restart, and leaves Local when a draft is chosen. A tunnel URL there still works for v7 sites.
  • Studio accepts only links to a server on your machine; 127.0.0.1 and [::1] links open as localhost.
  • Fast Preview sessions use the protocol only when the branch's committed schema has "blocksMajor": 8 and the org has site_editor_content_protocol (off by default): each save is one commit on the draft branch, the schema comes from that branch (or the default branch), and the preview gets a ?__draft= link. Sessions with a sandbox stay on the existing path.
• bun.lock: main's lockfile plus only @decocms/[email protected] (apps/api, apps/web, packages/e2e) and its nested [email protected]: a 7-line diff against main. bun install --frozen-lockfile accepts it unchanged, so every other package resolves exactly as on main.
• No other conflicts; main's changes to apps/api/package.json, apps/web/src/router.tsx, query-keys.ts and tool-io.ts merged cleanly. v7 behaviour is main's.
• Typecheck, lint, format, knip and unit tests (10470 pass, 0 fail) pass. Content-protocol e2e (one worker): 15/17 on the first run; the two failures (Local draft option, refuses an off-machine link) pass on a rerun of just those tests (2/2).