Experiment: use Static Site Importer for generated local sites

[chubes4]

Summary

• Bundles Static Site Importer into Studio via the existing wp-files/ download chain. A fresh npm install fetches SSI's main zipball, extracts to wp-files/static-site-importer/, and the CLI bundle ships it. No environment variables, no separate clone, no setup steps required.
• Reframes local site generation around a normal static HTML/CSS handoff: the agent writes tmp/static-site/index.html, then imports it with static-site-importer import-theme.
• Updates the deterministic smoke script (apps/cli/scripts/studio-bfb-smoke.mjs) to validate the bundled flow end-to-end: SSI generates and activates a block theme with templates, parts, a front-page pattern, and zero fallback events.

Why

Studio's local site-generation path should not require agents to hand-author Gutenberg block markup or maintain brittle block-format prompt skills. Static Site Importer gives Studio a reusable pipeline:

1. The agent writes familiar static HTML/CSS.
2. Static Site Importer converts that HTML into a WordPress block theme.
3. The generated site remains editable in the Site Editor.

This also supports customer-provided static HTML, migrated templates, and AI-generated prototypes as inputs instead of forcing Studio to discard or rewrite them.

Related upstream projects:

• Static Site Importer: https://github.com/chubes4/static-site-importer
• Block Format Bridge: https://github.com/chubes4/block-format-bridge
• HTML to Blocks Converter: https://github.com/chubes4/html-to-blocks-converter

How SSI gets into the site

npm install
  └─ scripts/download-wp-server-files.ts
       └─ fetches https://github.com/chubes4/static-site-importer/archive/refs/heads/main.zip
            └─ extracts into wp-files/static-site-importer/
                 ├─ static-site-importer.php       (plugin entry)
                 ├─ vendor/autoload.php            (composer deps, committed in SSI repo)
                 └─ includes/.../cli-command.php   (registers `wp static-site-importer`)

apps/cli build
  └─ Vite copies wp-files/ into dist/cli/wp-files/

site_create / site_start
  └─ tools/common/lib/mu-plugins.ts
       └─ symlinks dist/cli/wp-files/static-site-importer/ into the per-site mu-plugins temp dir
            └─ a small loader mu-plugin requires static-site-importer.php
                 └─ SSI's CLI command registers → `wp static-site-importer ...` works

Path resolution lives in apps/cli/lib/dependency-management/paths.ts::getStaticSiteImporterPluginPath(), which mirrors getPhpMyAdminPath() / getSqliteCommandPath() / getBlueprintsPharPath() — all bundled assets resolved against getWpFilesPath().

Iteration model (draft phase)

While the SSI substrate is still rapidly evolving, the downloader pulls main rather than a tagged release. Reviewers automatically pick up upstream fixes by re-running npm install. There's no per-machine setup and no env-var contract — a fresh clone of this PR plus npm install is everything a reviewer needs.

Before this PR un-drafts, swap the URL in scripts/download-wp-server-files.ts for a pinned tag, e.g.:

-		getUrl: () =>
-			'https://github.com/chubes4/static-site-importer/archive/refs/heads/main.zip',
+		getUrl: () =>
+			'https://github.com/chubes4/static-site-importer/archive/refs/tags/v0.4.0.zip',

That locks the substrate to a known-good release for merge.

Verification (Riad-equivalent reviewer simulation)

I created a fresh worktree off this branch in a directory that has no relationship to my local SSI development setup, with no environment variables set, and walked it through the reviewer flow:

$ git worktree add studio@bfb-reviewer-sim bfb-mu-plugin-agent-output-draft
$ cd studio@bfb-reviewer-sim
$ npm install --no-audit --no-fund
   ...
   [static-site-importer] Downloading Static Site Importer (chubes4/static-site-importer @ main) ...
   [static-site-importer] Extracting files from zip ...
   [static-site-importer] Files extracted
   ...
$ ls wp-files/static-site-importer/static-site-importer.php
   wp-files/static-site-importer/static-site-importer.php
$ ls wp-files/static-site-importer/vendor/autoload.php
   wp-files/static-site-importer/vendor/autoload.php
$ cd apps/cli && npm run build
   ✓ built in 2.43s
$ node apps/cli/scripts/studio-bfb-smoke.mjs
   {
       "importer_loaded": true,
       "bfb_loaded": true,
       "h2bc_loaded": true,
       "file:parts/header.html": true,
       "file:parts/footer.html": true,
       "file:templates/front-page.html": true,
       "file:templates/page-home.html": true,
       "file:patterns/page-home.php": true,
       "file:style.css": true,
       "file:theme.json": true,
       "front_page_id": 4,
       "home_page_id": 4,
       "active_theme": "studio-static-importer-smoke",
       "fallback_count": 0,
       "header_html_blocks": 0,
       "footer_html_blocks": 0,
       "pattern_has_blocks": true
   }
   PASS: Studio Static Site Importer smoke generated an editable block theme.

Tests

• npm run typecheck (all workspaces) — clean
• npx eslint <touched files> — clean
• npx vitest run — 1483 passed across 157 test files, including 9 in tools/common/lib/tests/mu-plugins.test.ts (3 new SSI tests cover loader + symlink presence when the plugin path is provided, and absence when it isn't)
• apps/cli/scripts/studio-bfb-smoke.mjs — passes end-to-end against a freshly-bundled site

Notes

• This bundles two unrelated prompt/UI tweaks from the same iteration into the SSI commit: dropping two outdated guidance lines from apps/cli/ai/system-prompt.ts (now superseded by the SSI workflow itself), and a welcome-text wording change in apps/cli/ai/ui.ts ("block themes" → "WordPress sites"). Both are minor, both ride along.
• Unstacked from Fix AI screenshot local site resolution #3307 (which fixes take_screenshot/share_screenshot URL resolution for local sites). The two PRs touch separate concerns; Experiment: use Static Site Importer for generated local sites #3309 no longer rides on top of Fix AI screenshot local site resolution #3307 and can land independently.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Sonnet 4.5)
• Used for: Drafted the wp-files download entry, mu-plugin contract refactor (env-var → bundled-path option), CLI entry-point wiring, smoke-script clean-up, and the new mu-plugins tests under Chris's direction and review. The original draft of this PR (commit 2f336e86) was authored separately by OpenCode/GPT-5.5; the iteration on top is Claude Code's.

[chubes4]

Testing it with lots of different prompts using automated benchmarks.

Site build prompts being tested: https://github.com/chubes4/homeboy-rigs/tree/main/Automattic/studio/bench/prompts/site-build

Here is a screenshot from the first passing (all valid blocks matching the frontend) generation from last night:

[youknowriad]

I'm giving this PR a try. Quick questions though:

• how does the block conversion work? Is it hard-coded rules? like conceptually how does it work. My guess is that it's only core blocks right?

• why not a nodeJS converter instead of php (to allow for using the same tool for both remote and local sites), we can't install mu plugins on remote sites.

[youknowriad]

Not sure what I'm doing wrong, this is not working for me

[chubes4]

how does the block conversion work?

My initial approach was to mirror the client side rawHandler in Gutenberg, using the core HTML API. Yes only core blocks for now. Non-supported blocks fallback to core/html.

There is some hardcoding, but I am trying my best to make it more about generic pattern recognition.

My approach has been to run many different prompts, fix the gaps, and run again. The quality has improved significantly over time.

Even with hardcoding, there are certain patterns the AI is likely to use. I think we could account for most of them and handle edge cases as they come up.

why not a nodeJS converter instead of php

Honestly, I did not think of that. I had started this experiment a while back for a plugin that creates content at scale. The site editor angle is new.

Eventually, this could be the responsibility of Gutenberg, instead of Studio.

Not sure what I'm doing wrong

You did nothing wrong, it was me who accidentally left a local path in the original draft 🥇. Sorry about that!

[youknowriad]

I think this PR is trying to do too much, change how we transform blocks but also change other things in the system prompt... I've also fallen into this trap on previous PRs and it's very hard to gain confidence about whether the change you're making is the right one or not.

I would like to suggestion smaller steps. For the static site import (or block transformation) which is the main thing this PR is trying to achieve. I'm wondering if there's a simple solution that avoid building a php transformer entirely and just rely fully on the raw handler. The advantage is that it will work consistently and support any blocks that is available on the site. We could achieve it by using an eval in playwright like we do today for block validation, it's just that instead of block validation, we'll be doing block transformation directly.

[chubes4]

Thanks for the feedback. I will see if I can come up with a simpler approach. I do want to keep experimenting with this, because I already built the PHP transformer, and have been getting good results with it.

For the system prompt, I think we should gradually be moving design and workflow constraints out of the system prompt and into a skill. As part of this experiment, I tweaked the prompt to try and speed up generation by reducing the number of steps.

I am running some benchmarks that track the agent's font choices, color choices, and design decisions in a database over the course of many eval runs with a given system prompt. This can help us measure the impact of prompt changes on output with hard data and make sound decisions.

The idea is that eventually, Studio Code can become a general-purpose WordPress agent that is powerful enough to be the daily driver for the average WordPress developer.

[youknowriad]

I think we should gradually be moving design and workflow constraints out of the system prompt and into a skill.

I think that makes sense yeah :)

Looking forward to see where these experiments lead.