Automattic / Automattic/blocks-engine
Carry route-scoped presentation assets into Gutenberg
- Dominant language
- PHP
- Stars
- 14
- Forks
- 2
- Avg merge
- 2h 10m
- Merged PRs (30d)
- 561
Description
## Problem
`blocks-engine/wordpress-site-plan/v2` emits route-scoped CSS assets and a generated `functions.php` bootstrap that enqueues them only through `wp_enqueue_scripts`. The generated block theme therefore renders correctly on the frontend while Gutenberg's iframe receives none of the authored presentation layer.
This is not a block-validity failure. Imported blocks can be fully native and pass `wp.blocks.validateBlock` while remaining visually unusable in the editor.
## Reproduction
The current solved corpus was rerun on WordPress 7.0.4 with Blocks Engine `61ab2336392f897283b91bb3c5e555ce89c555ef` and SSI `f3f0977805aadd855a7a05196c5b1e58f4757f9b`:
- `15-saas`: frontend parity passes; 576/576 loaded-editor validations pass; editor renders largely unstyled document flow.
- `89-static-site-importer-architecture`: frontend parity passes; 342/342 loaded-editor validations pass; editor renders largely unstyled document flow.
- A route-scoped 11-page Figma import similarly passes 5,424/5,424 editor validations while its editor omits all six homepage presentation stylesheets.
The generated scaffold currently has an empty `theme.json`, metadata-only `style.css`, and route CSS registered only on `wp_enqueue_scripts`.
## Required Contract
Extend the canonical WordPress site plan so presentation assets explicitly declare:
- stable asset identity and target path;
- content hash and cascade order;
- frontend route/reconciliation scopes;
- equivalent editor post/reconciliation scopes;
- media conditions where applicable;
- frontend/editor applicability.
The generated bootstrap must resolve the edited `WP_Block_Editor_Context::$post` to the same stylesheet set as its frontend route and deliver CSS through WordPress's iframe style seam (`block_editor_settings_all` / `$settings['styles']`). Asset URLs and font references must remain canonical after materialization.
## Acceptance
- Inline and external local CSS fixtures receive equivalent frontend and editor presentation assets.
- Front-page, page-route, and reconciliation-identity scopes are deterministic and covered by contract tests.
- Existing frontend enqueue behavior and ordering remain unchanged.
- The plan validator rejects incomplete or inconsistent editor presentation scope metadata.
- `15-saas`, `89-static-site-importer-architecture`, and the route-scoped Figma fixture can satisfy downstream editor-presentation gates.
## Related
- Automattic/static-site-importer#3
- Automattic/static-site-importer#120
- Automattic/static-site-importer#121
- A linked SSI enforcement issue will consume this contract.
## AI assistance
GPT-5.6 Sol via OpenCode was used to inspect the generated site plan, WordPress editor iframe APIs, reproduce the solved-corpus regressions, and draft this issue. Chris Huber reviewed and directs the work.
Contributor guide
Research direction
Start by tracing the generated functions.php bootstrap, the canonical site plan, and the current wp_enqueue_scripts path. Read the block_editor_settings_all seam and WP_Block_Editor_Context::$post handling to understand how editor styles should match frontend routes. Done means contract tests cover deterministic scopes and both inline and external CSS fixtures receive equivalent editor and frontend assets without changing existing enqueue behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, wordpress
- Domain
- frontend, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100