Add HTML block checker to enforce native Gutenberg blocks

[epeicher]

Related issues

• Related to STU-1439
• Supersedes Improve AI system prompt to enforce Gutenberg blocks over custom HTML #2976

How AI was used in this PR

Claude was used to implement the HTML block checker tool, write tests, and update the system prompt with block pattern references. All code was reviewed and iterated on by the author.

Proposed Changes

• Add html-block-checker.ts: a deterministic tool that parses block content via wp.blocks.parse() in a real browser, identifies core/html blocks wrapping structural HTML (divs, sections, headings, paragraphs, lists, etc.), and flags them with native Gutenberg block replacement suggestions.
• Integrate the HTML block check into validate_blocks so both block markup validation and HTML block misuse detection run in a single call via Promise.all. This was necessary because during testing the AI agent reliably called validate_blocks on every piece of block content but consistently forgot to call check_html_blocks as a separate step — it would validate markup, get a pass, and move on without ever checking for HTML block misuse. By merging both checks into validate_blocks, the HTML block analysis is guaranteed to run every time block content is validated, without relying on the AI to remember a second tool call.
• Register a standalone check_html_blocks tool for independent use.
• Update the system prompt with:
  • Concrete Gutenberg block markup patterns (core/group, core/heading, core/paragraph, core/columns, core/image, core/buttons, core/list, core/separator)
  • Stricter guidelines requiring the AI to plan block structure before writing content
  • Explicit rules against using data-* attributes to bypass the checker
  • Clear list of when core/html is acceptable (SVGs, forms, animation markup, scripts)
• Add 14 tests covering: no HTML blocks, allowed wrapper tags, SVGs, data-* attributes (now flagged), convertible content, deep nesting, replacement suggestions, inner blocks, mixed scenarios, and error handling.

Testing Instructions

• Apply this changes and run npm run cli:build and node apps/cli/dist/cli/main.mjs ai
• Build a site with a prompt that a user would add, focused on the website and potential styles, but not necessarily specifying technical details like (Gutenberg blocks), an example prompt could be "Build a one page site for a luxury furniture brand called Mikado, known for its precision and high quality manufactoring. Use simple Icons for company logos that are clients (Nasa, SpaceX, Uber, Visa, Grab, bose, Discover, dji, Nikon, craftsman, sony). Use light colors", but I encourage you to use a different one.
• Verify that the generated site uses Gutenberg blocks instead of core/html wrappers. For that, you can open <site-domain>/wp-admin/site-editor.php, click on the page and check the Document overview

Additionally, you can try to edit any of the sections and check if you can update the text.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 7bcbc11 vs trunk

app-size

Metric	trunk	7bcbc11	Diff	Change
App Size (Mac)	1252.12 MB	1252.13 MB	+0.01 MB	⚪ 0.0%

site-editor

Metric	trunk	7bcbc11	Diff	Change
load	1936 ms	1586 ms	350 ms	🟢 -18.1%

site-startup

Metric	trunk	7bcbc11	Diff	Change
siteCreation	8109 ms	8148 ms	+39 ms	⚪ 0.0%
siteStartup	3960 ms	4148 ms	+188 ms	🔴 4.7%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[youknowriad]

What I don't like much is the coupling of the system prompt to the core blocks. Aren't the validation changes sufficient.

I'm also wondering why you used a single tool for both kind of validation (block validation and html blocks) instead of using separate tools. I'm not opinionated here as long as the solution works though.

[epeicher]

That's definitely a concern I have too, shared here also. The underlying problem seems to be that the agent tends to use html blocks all the time. Also in this comment I explain the issue I found with using only the tool.

I am going to experiment using external skills as an alternative or a more generic hint that doesn't couple that much with block implementations

[epeicher]

I'm also wondering why you used a single tool for both kind of validation (block validation and html blocks) instead of using separate tools. I'm not opinionated here as long as the solution works though.

This was updated because during testing the AI agent reliably called validate_blocks on every piece of block content but consistently forgot to call check_html_blocks as a separate step

[youknowriad]

Did you find that the changes to the system prompt here are necessary? Can't we just rely on the tool for validation and the agent should be capable to fix things properly based on the errors thrown by the tool (like we do for regular block validation).

[epeicher]

That was my initial approach and didn't work well, the agent was in a loop that took around 45 minutes where:

• Initially created mainly html blocks
• Used the tool to replace the html blocks by other core blocks
• Refined the design and replaced the core blocks by html blocks
• Validated again using the tool and replacing back to core blocks

The final result included a mixture of Groups and html blocks nested. I recorded a video with that first approach, you can skip to the relevant parts and see the loop 3ae9e-pb, for example on the minute 7:20 the agent had validated al the html blocks to use core blocks but it continues until minute 46 to complete the site.

Then I changed the system prompt to emphasize as much as possible using blocks, that improved the usage of blocks

[youknowriad]

I see, but doesn't this mean that the validation tool is now unnecessary (so basically your skill suggestion)?

[epeicher]

Yes, it is a bit redundant now, but I found that the agent still uses it and updates some blocks. I am going to continue testing, and if I don't find that the tool helps, I will remove it

[youknowriad]

One idea @mtias brings up all the time as well, is that maybe instead of asking our system prompt to generate the design in one step, we should split it into two steps: First generate the design in raw HTML + CSS, Second convert the HTML into blocks.

[epeicher]

One idea @mtias brings up all the time as well, is that maybe instead of asking our system prompt to generate the design in one step, we should split it into two steps: First generate the design in raw HTML + CSS, Second convert the HTML into blocks.

I like that approach, as I had success in converting one of the testing sites from html to core blocks in a different session. I am going to iterate over that 👍

[mtias]

Yeah, two clean stages is worth a shot because there are various flows in which design > html+css is more straightforward for the model than design > blocks.

1. Two-pass workflow in the system prompt — Explicitly split site building into "design pass" (HTML/CSS is fine, get the visuals right) and "block conversion pass" (convert everything to core blocks, validate). Right now the prompt mixes both concerns and the agent often stops after the design looks good.
2. Validation gate — The validate_blocks tool exists but the agent treats it as optional. We can make the system prompt stricter: "After writing any template or page content, you MUST run validate_blocks. If any core/html blocks are found that could be core blocks, convert them before proceeding."
3. A post-build audit step — Similar to how /classic-to-blocks is meant to work as a dedicated conversion pass, we could add an automatic "blockify" step at the end of every site build. The system prompt would say: "After building the site and taking screenshots, run a final block audit: list all core/html blocks and convert each one to the appropriate core block equivalent."