Epic: Playground — experience deckd in the browser

[jonocodes]

Epic: fully-mocked public demo — "experience deckd in the browser"

A public, backend-free demo page where any visitor experiences the press→world-reacts loop of deckd. Virtual apps run in the browser, tick on a clock, and speak the real wire protocol; pressing a deck button visibly moves the world (music plays, volume changes, apps switch) even though nothing real is happening.

The key insight

Once app-switching is a real feature, the only difference between "demo" and "product" is where the state comes from. The frontend already renders whatever ServerMessage stream arrives via useDeckdSocket — it can't tell a real Python daemon from a fake in-browser one. So we mock at that single seam and everything downstream is the real UI.

Sequencing (Tier 1 → gate → Tier 2)

Tier 1 and Tier 2 are two presentation layers on one foundation (MockDaemon + virtual apps + clock). The bulk of the work lands before either tier; Tier 1 proves the stream is alive cheaply; Tier 2 is mostly a UI skin. So we build the foundation, ship Tier 1, evaluate, then commit to Tier 2.

Work items

• Spike: prototype the Playground press→feedback loop #149 — Spike: prototype the press→feedback loop (de-risk; gates the epic)
• MockDaemon foundation: in-browser virtual backend #150 — MockDaemon foundation (shared by both tiers)
• Virtual apps: 2–3 stateful ticking apps for the demo #151 — Virtual apps (music, sensors, +1)
• Demo app-switch affordance (no OS focus in browser) #152 — Demo app-switch affordance
• Tier 1: feedback line / toasts for the Playground #153 — Tier 1: feedback line / toasts
• Gate — evaluate Tier 1 before building Tier 2: does it feel alive? is the seam clean? is the mirror clearly worth it? (decision, not code)
• Tier 2: mirror screen panel for the Playground #154 — Tier 2: mirror screen panel
• Guided coach-marks / onboarding overlay for the demo #155 — Guided coach-marks / onboarding overlay
• Public deploy + drift guard + "Try it live" link #156 — Public deploy + drift guard + "Try it live" link

Non-goals (locked)

• Tier 3 virtual desktop (draggable windows / fake OS) — scrapped.
• Real integrations, persistence, or auth.
• No mock code in the production client bundle — demo/dev-only entry, tree-shaken out of prod.

Cross-cutting constraints

• Honesty: the mock may only emit messages that validate against protocol.generated.ts (drift-guarded, see Public deploy + drift guard + "Try it live" link #156 / Enforce Python and TypeScript protocol parity #76) — no advertising features the product lacks.
• Determinism: virtual apps use no Math.random / wall-clock, so they double as fixtures for the focus-driven app-switching logic.
• Accessibility: honor prefers-reduced-motion; touch- and keyboard-accessible.

Prior art informing the design

• Interactive-demo tooling (Arcade, Navattic, Storylane) → cold visitors need light guidance (→ coach-marks, Guided coach-marks / onboarding overlay for the demo #155).
• In-browser OS sims (daedalOS, Puter) → full desktops are their own product; not worth it when the deck is the hero (→ Tier 3 scrapped).

[jonocodes]

Update: named Playground, spike #149 landed on main, scope tuned

Naming. The interactive backend-free page is now the Playground (activated by ?playground). "Demo" stays reserved for the existing ?demo=<name> static fixtures in demo.ts — the Playground builds on that plumbing but is a distinct concept. "Showcase" was avoided (already a fixture name, the Gallery concept, and the README branch; also implies passive display).

Scope tuning (breadth over depth). Priority is surfacing every clickable surface/button, not perfect simulation fidelity. So: the app-switch affordance (#152) and reaching all chrome views matter more than a deep music sim (#151 can start shallow), and the mirror panel (#154) is less critical than making all surfaces reachable. Issues kept as-is; just reprioritized.

Spike #149 — done, gate passed, committed to main. A MockDaemon (in client/src/playground/) speaks the real wire protocol into the useDeckdSocket callback surface; App branches to it on ?playground. One virtual music app ticks on a 250ms clock. Verified in a real browser: position advanced 42→44s over 2s while playing, froze on pause, transport works — all through the real MediaCell/media-store, no backend. The seam is as clean as hoped: ~2 small files + a ~3-line branch in App.tsx. Landed as feat(playground): backend-free MockDaemon spike + virtual music app (#149).