[youknowriad]

Related issues

• Related to STU-2562: the second half of the preview step of porting Rich Tabor's rebuild.
• Stacked on Preview header: Start/Stop, address field actions, and a More menu when narrow #5272 (preview header). Review that one first; this PR's base will move to trunk once it merges.

How AI was used in this PR

Claude Code ported the rebuild's preview lifecycle, using Rich's build as the spec. Before writing code, I confirmed four choices:

• Follow Rich's stopped layout.
• Take screenshots in both apps, into one shared cache.
• Port the particles and logo, but skip the stop "dust" animation.
• Ship the header and the lifecycle as two PRs.

Claude checked the result live in studio ui (capture, stop, start, light and dark). In the packaged Desktop app, a temporary e2e probe confirmed that the webview capture saved the page and that the stopped site showed it. I reviewed the diff.

Proposed Changes

• A stopped site gives the chat the room.
  • Beside a chat, the preview collapses when the site stops.
  • An empty chat then shows the site's last screenshot. Clicking it starts the site, and a play button appears on hover.
  • A chat with messages keeps its transcript.
  • On a site's own page (no chat), the pane shows the same screenshot.
  • The big "Start site" button is gone. Start stays at the top right of the header, as in the rebuild: in the preview header, or in the chat header once the preview has collapsed.
• The screenshot is the page you last looked at.
  • It's saved shortly after each page finishes loading in the preview. Admin and sign-in screens are skipped.
  • It works in both apps:
    • Desktop captures the preview webview.
    • studio ui captures through the browser the CLI already uses for the agent's screenshots, only when it's installed, so it never downloads one.
  • Until now, studio ui never showed a screenshot, and Desktop only took one when a site started.
• Starting a site shows Rich's particle field with the WordPress logo, in the chat or in the pane, until the preview opens. Reduced motion gets a still field.
• Every empty chat looks the same, running or stopped: Rich's dot field, with the screenshot on top when the site is stopped. It replaces the old animated WordPress-logo background in chats; the welcome screen keeps that one.
• No more suggested prompts in an empty chat, as in the rebuild. The composer's "replace your draft?" check, which only served them, goes too.

Both apps share one cache, ~/.studio/previews, in @studio/common:

• File names: each is a hash of the site id.
• Older screenshots: Desktop's existing thumbnails still show until a new screenshot is saved.
• Desktop: an IPC handler captures the webview (only the window hosting it may ask).
• studio ui: a route captures through a function the CLI passes in, checking the page is on the requested site.

Differences from Rich's build

• No stop "dust" animation: the pane collapses as soon as the site stops, so the dust would barely be visible.
• No reveal swirl and no sidebar "selection wave": the particles ease in and out, and that's it.
• Duplicating a site: the copy still gets the older Desktop thumbnail, not the newest screenshot.

Screenshots

studio ui, a site's own page: stopped, hovering the screenshot, starting:

A new chat while the site runs, then after it stops:

Dark mode:

The packaged Desktop app, stopped after the first load:

Testing Instructions

1. Open a running site and browse a couple of pages. Stop it from the header Start/Stop: the preview collapses, and an empty chat shows the last page you looked at. Hover it for the play button, then click it: the site starts with the particles and logo, then the preview reopens.
2. In a chat that has messages, stopping the site collapses the preview and keeps the transcript.
3. Open WP Admin in the preview, then stop the site: the screenshot is still the last front-end page.
4. Repeat in studio ui, which now shows screenshots too, and in dark mode.

Checks run:

• eslint and typecheck.
• Unit tests across apps/ui, apps/studio, apps/local, packages/common and the CLI commands: 1,990 passing. New tests cover the cache, the capture trigger and the stopped chat.
• sites and localization e2e on a packaged build: passing. One sites test failed when run alongside localization, because that test changes the app language; it passed when sites ran on its own.

Pre-merge Checklist

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

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing 38e908c vs trunk

app-size

Metric	trunk	38e908c	Diff	Change
App Size (Mac)	944.54 MB	944.54 MB	0.01 MB	⚪ 0.0%

site-editor

Metric	trunk	38e908c	Diff	Change
load	1185 ms	1246 ms	+61 ms	🔴 5.1%

site-startup

Metric	trunk	38e908c	Diff	Change
siteCreation	7063 ms	7070 ms	+7 ms	⚪ 0.0%
siteStartup	4376 ms	4400 ms	+24 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

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