Support new blank or child themes in Studio Code

[sejas]

Related issues

• Closes STU-2017

When asked to customize a site running an installed theme (e.g. Ollie), Studio Code edited the theme's files directly. Any later theme update would silently wipe every customization — the exact failure reported in STU-2017.

How AI was used in this PR

AI assisted with implementation, code review, and simplification passes; all changes were verified with unit tests, typecheck, and lint.

Proposed Changes

• Studio Code now defaults to creating a child theme when customizing an installed third-party theme: scaffold_theme accepts a parentTheme slug and scaffolds a minimal block child theme (inherits the parent's templates, parts, patterns, theme.json settings, and styles) and activates it. Customizations survive parent theme updates.
• The child scaffold defensively enqueues the parent's style.css (Theme Handbook pattern), so parents that enqueue via get_stylesheet_uri() keep their styling when the child is active.
• The agent's instructions now forbid editing installed third-party theme files by default. Themes Studio Code itself created remain directly editable. If the user explicitly asks to edit an installed theme's files, the agent warns once about the update-wipe risk and then complies.
• Guardrails reject invalid setups with actionable errors: parent not installed, grandchild themes (points to the real parent slug), parent equal to the child slug.

Testing Instructions

Child theme check:

• Run npm run cli:build && node apps/cli/dist/cli/main.mjs code
• Install Ollie or any other theme from the themes directory.
• Ask the agent to customize existing theme
• Expect a scaffold_theme call with parentTheme: 'ollie', all edits under the new child theme directory, and wp-content/themes/ollie/ untouched.
• Then ask it to edit the Ollie theme files directly — expect a single warning about updates overwriting changes before it complies.
• Test the new eval: npm run eval -- --filter-pattern "child theme"

Keep working with themes built from scratch:

• Run npm run cli:build && node apps/cli/dist/cli/main.mjs code
• Select a site where you built the theme from scratch
• Ask the agent to modify the theme
• Confirm it keeps working as usual and it doesn't create a child theme
• Test the new eval: npm run eval -- --filter-pattern "single-page site"

Child	Existing theme
Prompt: Create a new site about the odyssey using the Ollie theme	Prompt: Create a new site about Prince of Egypt

Pre-merge Checklist

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

[wpmobilebot]

📊 Performance Test Results

Comparing 39fe6a5 vs trunk

app-size

Metric	trunk	39fe6a5	Diff	Change
App Size (Mac)	1353.03 MB	1353.03 MB	0.01 MB	⚪ 0.0%

site-editor

Metric	trunk	39fe6a5	Diff	Change
load	1110 ms	1029 ms	81 ms	🟢 -7.3%

site-startup

Metric	trunk	39fe6a5	Diff	Change
siteCreation	6992 ms	7002 ms	+10 ms	⚪ 0.0%
siteStartup	2350 ms	2350 ms	0 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

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

[youknowriad]

Do you think we can write an eval that actually breaks in trunk but passes in this branch?

[sejas]

Do you think we can write an eval that actually breaks in trunk but passes in this branch?

Yes! I added an eval to test a blank theme and another to test the child theme behaviors:

3e47f82

[youknowriad]

I wonder if we can move the assertions of this eval to one of the previous ones to keep the evals a bit more fast/contained.

[sejas]

Great suggestion! I added it to "single-page site build keeps every turn under 60s" 87b15ce

[youknowriad]

That feels like a useless unit test.

[sejas]

Agreed! Removed it. c7dcebb

We still have other similar unit tests that were added in other PRs.