fix(preview): hide starter scaffold during generation

[iamjr15]

Summary

• Keep the animated Cheatcode mark visible while a fresh app-builder scaffold boots and the model generates the requested app.
• Persist an explicit building → ready preview-content transition instead of treating an open port as finished content.
• Keep the same loader over a newly mounted iframe until its document has actually loaded.

Linear

Not linked — direct production UX fix requested during preview reliability QA.

Plan

No repository plan document; the implementation plan and acceptance evidence are in the task transcript.

What's Included

Typed readiness contract

• Adds data-app-preview-status to the persisted/replayed UI-message contract.
• Emits building only for freshly scaffolded template projects and ready after successful model execution.

Browser presentation

• Hydrates and applies readiness transitions through the existing workspace surface controller.
• Hides internal readiness events from the transcript.
• Shows the branded loader during generation and until the final iframe load event.
• Leaves follow-up edits on existing projects visible for normal hot reload.

Documentation

• Documents the internal scaffold boundary and user-facing readiness behavior in the owning package READMEs.

Architecture

The agent Worker owns content readiness because it knows whether a workspace was freshly scaffolded and when model generation completed. The typed stream part is persisted with the run, replayed after refresh, and projected into memory-only web UI state. The web client never inspects cross-origin iframe contents or guesses with a timer.

Decisions Made

Decision	Choice	Alternatives Considered	Reasoning
Readiness owner	Agent Worker emits typed state	Timer; iframe text inspection	Deterministic, replayable, and cross-origin safe
Scaffold lifecycle	Keep it internal	Remove starter project	A valid project is still needed to boot and verify the managed server
Existing projects	Keep iframe visible	Hide on every run	Preserves live iteration and avoids regressing follow-up edits
Initial iframe load	Branded overlay until load	Immediate reveal	Prevents a white/partial document flash after generation

Edge Cases Handled

Scenario	Handling
Historical transcript without the new part	Defaults to existing preview behavior
Follow-up run in an existing project	Does not enter the fresh-scaffold loading state
Page refresh during generation	Persisted building state restores the loader
Reduced-motion preference	Existing Cheatcode loader disables animation

How to Review

1. Start with packages/types/src/ui-message.ts and agent-run-app-builder.ts for the contract.
2. Check use-sandbox-surface-sync.ts for live and hydrated event projection.
3. Review preview-side-panel.tsx for the presentation transition.

Test Plan

• pnpm turbo skills:build
• pnpm turbo typecheck lint build --force — 55/55 tasks
• pnpm architecture:check — 849 modules / 1761 dependencies
• pnpm deadcode
• git diff --check
• Verify a fresh production app-builder run never exposes “Sandbox preview is live.”
• Verify the final generated app replaces the animated mark and remains live on refresh.