Single preview contract for product consumers: collapse boot DTO variants, retire legacy preview paths

[chubes4]

Problem

Product consumers (wp-build is the live case) loading a browser Playground preview through wp-codebox currently face three coexisting generations of architecture, and preview load failures come from the seams between them:

1. Legacy browser-agent generation — task contracts, materializer contracts, the generated PHP runner appended to blueprints (browser-agent-task-payload/v1), and the legacy provider adapter are still wired even though product preview loading no longer needs them.
2. Incremental boot-speedup layers — prepared-runtime transient cache, contained-site reuse, blueprint refs + hydration endpoints — each with its own vocabulary (prepared_runtime, snapshot, blueprint_ref, cache_key, input_hash, preview_ref, runtime_handoff).
3. The new contained-site/SDK facade (wp-codebox/open-or-create-browser-contained-site + window.wpCodeboxBrowser.v1.startBrowserPreview) — the clean path, actively consolidated in recent commits, but coexisting with everything above.

Concrete failure seams

• inline-session-blueprint half-migration. PHP still emits this legacy sentinel as a fallback ref (packages/wordpress-plugin/src/class-wp-codebox-browser-task-builder.php ~L792-803), but the browser runtime rejects it as non-hydratable (packages/wordpress-plugin/assets/browser-runtime.js ~L642-648). A consumer that receives it fails at hydration time with no early server-side error.
• Transient-cache expiry is not a first-class state. Prepared blueprints live in wp_codebox_browser_prepared_runtime_{hash} transients (1-week TTL). Cache miss / expiry / input-hash mismatch surface as downstream hydration failures rather than a clear prepare-new required signal.
• Boot DTO polymorphism. preview_boot, boot, preview_reference, preview_ref, runtime_handoff, executable_session all describe overlapping boot inputs. The task builder recursively discovers prepared runtime across many envelope shapes (class-wp-codebox-browser-task-builder.php ~L710-741) — pure migration compat.
• ~8 overlapping create/open/boot ability generations (create-browser-playground-session, create-browser-contained-site-session, open-browser-contained-site, open-or-create-browser-contained-site, boot-browser-contained-site-session, preview-boot-ref, task/materializer contracts). Descriptors self-document "legacy session envelopes remain available".

Proposed shape

1. One documented product preview path: open-or-create-browser-contained-site → startBrowserPreview(response.preview_boot, { iframe }). Lower-level abilities stay for internal/agent use but leave product docs.
2. One boot DTO for preview: client module URL, remote URL, CORS proxy URL, scope, blueprint ref + hydration endpoint, lease/status metadata. Collapse the variants.
3. Retire inline-session-blueprint: require hydratable refs for product preview sessions; fail early server-side.
4. Model cache lifecycle as first-class preview states: cache miss, expired transient, input-hash mismatch, hydratable ref missing, prepare-new required.
5. Separate "preview site" from "agent/browser task": loading a preview must not require understanding runner invocation, task payloads, materializer contracts, or host delegation phases.
6. Demote legacy surfaces: execute-browser-provider-request (already marked legacy), include_internal_browser_session / include_internal_browser_contract become debug/operator-only.
7. Unify vocabulary: one public naming set (e.g. contained_site.site_id, source_digest, blueprint_ref, hydration_endpoint).
8. Add a product-facing preview contract fixture/test: open-or-create response → startBrowserPreview() input, so consumers cannot fall into legacy paths.

Context

Found while investigating wp-build playground preview load failures. The wp-build side is tracked separately in its own repo (boot-path consolidation: one client boot contract, one warm-boot authority). Recent wp-codebox commits (5aa92e9b, c8b7c7fe, cf5fb33d) already move toward the SDK facade — this issue is about finishing that migration and deleting the seams.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Opus 4.5 via Claude Code
• Used for: Codebase investigation and drafting this issue; findings reviewed by Chris Huber.