Migrate the block factory to SCF Blocks V3 (WP 7.1 forces it)

[Schmandarine]

WordPress 7.1 (ships 19 Aug 2026) iframes the post editor unconditionally, which kills the apiVersion: 2 mechanism the block factory relies on for in-canvas field editing. SCF Blocks V3 is the supported replacement — and it is better than what it replaces.

Verified in a running editor 2026-08-11, not inferred. Playground with the theme mounted, SCF + Gutenberg active, a V2 and a V3 block on one page:

Check	Observed
iframe[name="editor-canvas"]	1 — with an apiVersion: 2 block inserted, not just registered
V2 block toolbar	["Example Hero","Drag","Move up","Move down","Align block","Options"] — no Switch-to-Edit
V3 block toolbar	Edit Block present
V3 registered versions	apiVersion: 3 | acf_block_version: 3
Repeater	756px panel (50% of a 1512px viewport) vs the 280px sidebar

Two findings from that run:

• apiVersion is derived, not set. The test block.json contained only acf.blockVersion: 3 and WordPress registered it as apiVersion: 3. The "never apiVersion 3" rule was guarding a value SCF fills in itself (includes/blocks.php:151).
• supports.mode is injected by SCF regardless (blocks.php:101, :575). Removing it from block.json is cosmetic, not functional.

Caveat: --wp=beta and --wp=<7.1-RC2 zip> both silently fell back to 7.0.3, so the run used WP 7.0.3 + the Gutenberg plugin — the documented route to the iframed state (gutenberg#75475, GB 22.6, "only affects classic themes"). Re-run on real 7.1 after 19 Aug to close that gap.

Must ship as one change

Code and docs disagreeing is worse than either being stale.

• my-acf-blocks/*/block.json: add acf.blockVersion: 3, remove apiVersion: 2 and supports.mode
• Raise the SCF floor: 6.0+ → 6.8.4+ in inc/dependencies.php and the README. Blocks V3 needs 6.6+; 6.8.4 is where the expanded-editor controls and hardened inline editing landed. This is a dependency change, not just a JSON edit
• /create-block + /edit-block: write V3, stop writing supports.mode
• AGENTS.md: invert the "never apiVersion: 3" hard rule
• my-acf-blocks/ACF-BLOCK-EDIT-MODE.md: rewrite as a post-mortem — it documents a constraint that ended
• Iframe audit on block CSS/JS: no .wp-admin / #wpadminbar selectors, no admin-chrome offsets like calc(100vw - 160px), no !important walls written to beat leaking admin styles, editor styles via editorStyle in block.json rather than enqueue_block_editor_assets
• Consider autoInlineEditing for text-led blocks — templates then need acf_inline_editing_field_is_empty() instead of a bare get_field() truthiness check

UI detail worth documenting

"Edit Block" opens a field popover which itself contains an "Open in Expanded Editor" button — two clicks, not one. The expanded editor is a full-height right-side panel at ~50% viewport width, not a centred modal.

Agent surface

/create-block, /edit-block, AGENTS.md, block templates in create → needs a @brmbh/cli release. Until published, scaffolded sites keep the old instructions via their devDependency.

---

Context: vault Automatic-Brain/Projects/brmbh-agentic-wp-suite/Development/WP-7.1-Impact.md