Prove generated-block compatibility across WordPress and Gutenberg

[noeltock]

Problem

The generated template prop must remain compatible with WordPress 7.1 while Gutenberg 24.0 deprecates it. We need runtime evidence before changing that contract. Closes #118.

Solution

Build one representative generated plugin and run identical ZIP bytes through isolated WordPress 7.1, WordPress 7.1.2 and WordPress 7.1.2/Gutenberg 24.0.0 lanes. Keep the generator and public release receipt unchanged.

Behaviour	Read first	Proof
Same artifact, observed runtime pins and exact child trees	scripts/proof-gutenberg-compat.mjs	Three-lane runtime suite passed
Existing editor, frontend and pattern checks remain authoritative	scripts/proof-playwright.mjs	Reused browser assertions; warnings retained and authenticated editor teardown completed before anonymous navigation
Explicit development-only command and migration boundary	docs/development.md, docs/reference.md	Documentation tied to pinned upstream hook implementations

Diff

+224 −3 · 8 files · no generator or dependency change

 generated pattern fixture -> build one ZIP
+ same ZIP -> WP 7.1 -> WP 7.1.2 -> WP 7.1.2 + Gutenberg 24.0.0
+ isolated configs/ports -> observed versions and retained commands
 existing browser field/save/reopen/frontend/pattern checks
+ exact inserted/saved/reopened child-tree comparison
+ authenticated editor teardown -> anonymous frontend navigation
+ console warnings -> explicit template deprecation observation
 public release proof: unchanged WordPress 7.1 identity

Testing & verification

Reviewed revision: c2cb0f4 · Node 22.23.1, OrbStack.

• npm run typecheck passed.
• node --check scripts/proof-gutenberg-compat.mjs passed.
• npm run verify passed: 709 tests, four existing skips, plus typecheck/build/package checks. The subsequent navigation correction passed 27 focused proof-contract tests.
• BLOCK_RUNNER_COMPAT_OUTPUT_DIR=/tmp/block-runner-compat-final npx --no-install vitest run --config vitest.gutenberg-compat.config.ts passed all three lanes. Each retained exactly seven native descendants after insertion/save/reopen, matching saved/reopened hashes and clean editor state; supported edits, bundled media and pattern isolation passed. All lanes observed PHP 8.3.35, Chromium 149.0.7827.55 and Twenty Twenty-Five 1.5. Core versions were exactly 7.1 / 7.1.2 / 7.1.2; Gutenberg was absent / absent / 24.0.0. The plugin lane retained the template-prop deprecation; all lanes had zero console/page errors.
• npm run test:proof:wordpress passed in CI with both native controls and required automated acceptance.
• A native Heading control reproduced the Gutenberg lane's HTTP 400 post-lock beacon with the generated plugin deactivated. Leaving the editor while authenticated before clearing cookies removed the error in the matched control. No runtime errors are suppressed.

Exact-head CI passed: Node 20.19.0/22.13.0/24.0.0, package boundary and the shared WordPress browser suite.

Not verified: release, model benchmarks, manual acceptance or collaborative editing. None are claimed.

Retained local receipt: /tmp/block-runner-compat-final/compatibility.json; per-lane command/browser evidence lives beside it. Matched native controls are in /tmp/block-runner-compat-native-control-before and /tmp/block-runner-compat-native-control-after.

• Same zip hash across all lanes: sha256:763c32b7c4c0b664cf38423a5057fbf2ae219ce7ef6cf39030ef44314616f495.
• Same input hash across all lanes: sha256:649d3f2c2a813926397b4dacf3e8377b9d1b8a9f9313163bb806c3b55ff4d1d0.
• Same template hash across all lanes: sha256:536fed11f5b61802957f4030613f423bbdee331f6ade73125a7e1bd360f89dbb.

Risk / rollout

Development proof orchestration, warning capture and the editor-to-visitor navigation order change. The current template prop remains in place. The Gutenberg 24.0 hook retains the prop while warning; WordPress 7.1 lacks its settings-only fallback.

Detection: explicit suite fails on wrong versions, empty/duplicate children, lost edits, failed pattern isolation or runtime errors. Rollback: revert this PR; no migration or package publication.