From b65497138f101a54e0825eb41a865f5c8d86baef Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 9 Jun 2026 17:19:47 -0700
Subject: [PATCH 1/5] =?UTF-8?q?docs(spec):=20homepage=20demo=20=E2=80=94?=
 =?UTF-8?q?=20expand-to-modal=20on=20launch?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../specs/2026-06-07-demo-modal-design.md     | 103 ++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-07-demo-modal-design.md

diff --git a/docs/superpowers/specs/2026-06-07-demo-modal-design.md b/docs/superpowers/specs/2026-06-07-demo-modal-design.md
new file mode 100644
index 000000000..c1bd6723d
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-07-demo-modal-design.md
@@ -0,0 +1,103 @@
+# Homepage Demo — Expand-to-Modal on Launch
+
+**Date:** 2026-06-07
+**Status:** Design / spec
+**Scope:** `apps/website` homepage `DemoShowcase`. No library/backend changes.
+
+---
+
+## Goal
+
+When a visitor clicks **"Launch live demo"** on the homepage demo section, open the live interactive demo in a **large modal/lightbox** instead of swapping a small inline iframe. This gives a genuinely usable chat surface (near-viewport size, perfect 16:10) without reflowing the page.
+
+## Problem
+
+`DemoShowcase` today is video-first: an inline `BrowserFrame` (~720px wide, capped by the section's `maxWidth: 760`) plays a looping clip with a "Launch live demo ▶" overlay. Clicking it swaps the video for a live `<iframe>` **at that same cramped ~720px frame** — too small to actually chat in.
+
+## Approved decisions (from brainstorming)
+
+- **Modal/lightbox** (not inline grow, not OS fullscreen).
+- **Open animation:** fade backdrop + scale-in (0.96→1); respect `prefers-reduced-motion`.
+- **Footer "Open the full demo ↗"** link: **keep it** (links to the active runtime's standalone site).
+- Tabs (LangGraph | AG-UI) live **inside** the modal so the runtime can be switched while open.
+- Mobile (<640px): the modal becomes a full-screen sheet (ratio relaxed).
+
+---
+
+## Architecture
+
+Split the modal into its own focused, testable component; `DemoShowcase` keeps owning the section + which tab is active and just toggles modal open state.
+
+### Files
+- **New:** `apps/website/src/components/landing/DemoModal.tsx` — the overlay (`'use client'`).
+- **Modify:** `apps/website/src/components/landing/DemoShowcase.tsx` — the inline frame stays *always* the looping video; the launch overlay opens the modal; render `<DemoModal>` when open.
+
+### State
+`DemoShowcase` already has `active: TabKey`. Replace the `launched: Set<TabKey>` (inline-swap) state with `modalOpen: boolean`.
+- `launch()` → `setModalOpen(true)` (records analytics).
+- The modal reads the **same** `active` tab and `setActive` — switching tabs in the modal switches the runtime in place (and the inline section's tab, kept in sync). Each tab's `<iframe src>` is the live demo `href` (`media.href`).
+- Closing sets `modalOpen=false`. The inline frame remains the looping video, so the section still looks alive afterward.
+
+### `DemoModal` interface
+
+```ts
+interface DemoModalProps {
+  open: boolean;
+  onClose: () => void;
+  tabs: { key: TabKey; tabLabel: string; url: string; href: string }[];
+  active: TabKey;
+  onActive: (key: TabKey) => void;
+}
+```
+
+Renders nothing when `!open`. When open:
+- A fixed full-viewport **backdrop** (`rgba(16,18,32,.55)`), `z-index` above the navbar.
+- A centered **frame** reusing the `BrowserFrame` look: header row (window dots · tabs · faux URL = active `url` · `×`), an `<iframe src={activeHref}>` body at **16:10**, and a footer (`Esc or click outside to close · MIT · no signup` left; `Open the full demo ↗` right → active `href`, `target=_blank`).
+- `role="dialog"`, `aria-modal="true"`, `aria-label="Live demo"`.
+
+### Sizing (the "full width, keep ratio" requirement)
+
+Frame width = `min(96vw, calc(90vh * 16 / 10))`; height = `width * 10 / 16`. So it fills whichever axis is tighter while holding a perfect 16:10; the backdrop absorbs the rest. No letterboxing inside the iframe.
+
+**Mobile (`max-width: 640px`):** frame becomes `width: 100vw; height: 100dvh;` (full-screen sheet); the 16:10 constraint is dropped (`aspect-ratio` removed / overridden) because 16:10 at phone width is unusably short. Header + footer stay; the iframe fills the remaining height.
+
+### Open/close behavior & a11y
+- **Open animation:** backdrop opacity 0→1 and frame `transform: scale(.96)→scale(1)` over ~160ms ease-out. Under `prefers-reduced-motion: reduce`, skip the scale (instant or opacity-only).
+- **Close triggers:** `×` button, `Escape` key, click on the backdrop (not the frame).
+- **Focus:** on open, move focus into the modal (the `×` button); trap Tab within the modal; on close, return focus to the launch button. (A small local focus-trap; no new dependency.)
+- **Scroll lock:** set `document.body.style.overflow = 'hidden'` while open; restore on close.
+- **Lazy mount:** the `<iframe>` mounts only when `open` (no demo network/cost until launch).
+
+### Analytics
+- On launch: `trackCtaClick`/`trackExternalLinkClick`-style event, surface `home_demo`, `cta_id: home_demo_launch_${key}` (`langgraph`/`ag_ui`).
+- On "Open the full demo ↗": `trackExternalLinkClick(href, { surface: 'home_demo', cta_id: 'home_demo_full_${key}', ... })`.
+- (Reuse the `AnalyticsSurface`/`CtaId` types; `home_demo_${string}` is already an accepted `CtaId` pattern.)
+
+## Error handling / edge cases
+- iframe loads the demo's own origin (allowed by its proxy) — no special handling; the demo site owns its errors.
+- Tab switch while open swaps `src` (re-loads the other runtime) — acceptable; a brief load is fine.
+- Closing mid-conversation simply unmounts the iframe (no persistence expected for a marketing demo).
+- Multiple rapid open/close: idempotent via the boolean; scroll-lock/focus cleanup in a single effect's teardown.
+
+## Testing
+Website is Next.js; gate locally on `nx lint website` (full build runs in CI). Add a Playwright spec (`apps/website/e2e/`) if the harness supports the homepage:
+- Click "Launch live demo" → a `[role="dialog"]` appears.
+- `Escape` closes it; focus returns to the launch button.
+- Switching the in-modal tab updates the active runtime (assert the faux URL / iframe `src`).
+- Backdrop click closes; frame click does not.
+
+If the homepage isn't covered by the current e2e harness, rely on `nx lint` + `nx build` + manual verification, and note it.
+
+## Non-Goals (YAGNI)
+- No morph/shared-element transition (explicitly deferred).
+- No deep-linking / URL state for the open modal.
+- No OS Fullscreen API.
+- No change to the paired demo CTA buttons below the section, the navbar dropdown, or the videos.
+
+---
+
+## Decomposition (for the plan)
+1. `DemoModal` component (backdrop, frame, tabs, iframe, footer, sizing, a11y: focus-trap + Esc + scroll-lock + reduced-motion).
+2. Wire into `DemoShowcase`: swap `launched` → `modalOpen`; overlay opens modal; keep inline frame as video; pass `active`/`setActive`; analytics.
+3. Mobile full-screen-sheet styles.
+4. (Optional) Playwright e2e for open/close/tab-switch/focus-return.

From 885fc3929173200d16d1edbfab6544c2294cae9e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 9 Jun 2026 17:26:20 -0700
Subject: [PATCH 2/5] =?UTF-8?q?docs(plan):=20homepage=20demo=20expand-to-m?=
 =?UTF-8?q?odal=20=E2=80=94=20task-by-task?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-06-07-demo-modal.md            | 337 ++++++++++++++++++
 1 file changed, 337 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-07-demo-modal.md

diff --git a/docs/superpowers/plans/2026-06-07-demo-modal.md b/docs/superpowers/plans/2026-06-07-demo-modal.md
new file mode 100644
index 000000000..2e4555271
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-07-demo-modal.md
@@ -0,0 +1,337 @@
+# Homepage Demo Expand-to-Modal — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Clicking "Launch live demo" on the homepage opens the live demo in a large, accessible modal/lightbox (near-viewport, 16:10) instead of swapping a cramped inline iframe.
+
+**Architecture:** A new `DemoModal` client component owns the overlay (backdrop, browser-frame chrome, in-modal tabs, lazy iframe, sizing, a11y). `DemoShowcase` keeps the inline frame as a perpetual looping video and toggles a `modalOpen` boolean; the modal shares the section's `active` tab.
+
+**Tech Stack:** Next.js + React (client components, inline styles + a scoped `<style>` block for responsive rules, `@threadplane/design-tokens`), Playwright e2e.
+
+**Reference spec:** `docs/superpowers/specs/2026-06-07-demo-modal-design.md`
+
+**Verification note:** The website has no component unit-test runner. Gate locally on `npx nx lint website` (CI runs the full build). Validate behavior with the dev server and the Task 3 Playwright spec. Commit after each task.
+
+**Working dir:** worktree `.claude/worktrees/demo-modal` (branch `worktree-demo-modal`), off latest `main`.
+
+---
+
+## Task 1: `DemoModal` component
+
+**Files:**
+- Create: `apps/website/src/components/landing/DemoModal.tsx`
+
+- [ ] **Step 1: Create the component**
+
+```tsx
+// apps/website/src/components/landing/DemoModal.tsx
+'use client';
+import { useEffect, useRef } from 'react';
+import { tokens } from '@threadplane/design-tokens';
+import { trackExternalLinkClick } from '../../lib/analytics/client';
+
+type TabKey = 'langgraph' | 'ag-ui';
+
+export interface DemoModalTab {
+  key: TabKey;
+  tabLabel: string;
+  url: string;
+  href: string;
+}
+
+interface DemoModalProps {
+  open: boolean;
+  onClose: () => void;
+  tabs: DemoModalTab[];
+  active: TabKey;
+  onActive: (key: TabKey) => void;
+}
+
+export function DemoModal({ open, onClose, tabs, active, onActive }: DemoModalProps) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  const closeBtnRef = useRef<HTMLButtonElement>(null);
+  const tab = tabs.find((t) => t.key === active) ?? tabs[0];
+
+  // While open: Esc to close, focus trap, body scroll lock.
+  useEffect(() => {
+    if (!open) return;
+    const prevFocus = document.activeElement as HTMLElement | null;
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    closeBtnRef.current?.focus();
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { onClose(); return; }
+      if (e.key !== 'Tab') return;
+      const f = frameRef.current?.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), iframe, [tabindex]:not([tabindex="-1"])',
+      );
+      if (!f || f.length === 0) return;
+      const first = f[0];
+      const last = f[f.length - 1];
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.body.style.overflow = prevOverflow;
+      prevFocus?.focus?.();
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Live demo"
+      onMouseDown={(e) => { if (e.target === e.currentTarget) onClose(); }}
+      style={{
+        position: 'fixed', inset: 0, zIndex: 100,
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        background: 'rgba(16,18,32,.55)',
+        animation: 'demoModalBackdrop .16s ease-out',
+      }}
+    >
+      <style>{`
+        @keyframes demoModalBackdrop { from { opacity: 0 } to { opacity: 1 } }
+        @keyframes demoModalFrame { from { transform: scale(.96); opacity:.6 } to { transform: scale(1); opacity:1 } }
+        .demo-modal__frame {
+          width: min(96vw, calc(90vh * 16 / 10));
+          background: ${tokens.surfaces.surface};
+          border-radius: ${tokens.radius.lg};
+          box-shadow: 0 24px 60px rgba(0,0,0,.45);
+          overflow: hidden;
+          display: flex; flex-direction: column;
+          animation: demoModalFrame .16s ease-out;
+        }
+        .demo-modal__body { width: 100%; aspect-ratio: 16 / 10; background: #15161f; }
+        @media (max-width: 640px) {
+          .demo-modal__frame { width: 100vw; height: 100dvh; border-radius: 0; }
+          .demo-modal__body { aspect-ratio: auto; flex: 1 1 auto; }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          [role="dialog"], .demo-modal__frame { animation: none !important; }
+        }
+      `}</style>
+
+      <div ref={frameRef} className="demo-modal__frame">
+        {/* header: window dots · tabs · faux url · close */}
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '8px 12px', background: tokens.surfaces.surfaceTinted, borderBottom: `1px solid ${tokens.surfaces.border}` }}>
+          <div style={{ display: 'flex', gap: 5 }} aria-hidden="true">
+            {[0, 1, 2].map((i) => <span key={i} style={{ width: 8, height: 8, borderRadius: '50%', background: '#cdd2df' }} />)}
+          </div>
+          <div role="tablist" aria-label="Demo backend" style={{ display: 'flex', gap: 5 }}>
+            {tabs.map((t) => {
+              const on = t.key === active;
+              return (
+                <button key={t.key} role="tab" aria-selected={on} onClick={() => onActive(t.key)}
+                  style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, fontWeight: 600, padding: '6px 12px', borderRadius: 7, border: 'none', cursor: 'pointer',
+                    background: on ? tokens.colors.accent : tokens.colors.accentSurface, color: on ? tokens.colors.textInverted : tokens.colors.textMuted }}>
+                  {t.tabLabel}
+                </button>
+              );
+            })}
+          </div>
+          <span style={{ flex: 1, textAlign: 'center', fontFamily: tokens.typography.fontMono, fontSize: 12, fontWeight: 600, color: tokens.colors.textMuted, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{tab.url}</span>
+          <button ref={closeBtnRef} onClick={onClose} aria-label="Close demo"
+            style={{ width: 28, height: 28, borderRadius: 7, border: 'none', cursor: 'pointer', background: tokens.colors.accentSurface, color: tokens.colors.textSecondary, fontSize: 16, lineHeight: 1 }}>&#215;</button>
+        </div>
+
+        {/* body: lazy live iframe */}
+        <div className="demo-modal__body">
+          <iframe src={tab.href} title={`${tab.tabLabel} live demo`}
+            style={{ width: '100%', height: '100%', border: 'none', display: 'block' }} />
+        </div>
+
+        {/* footer: close hint · open full demo */}
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 14px', borderTop: `1px solid ${tokens.surfaces.border}`, background: tokens.surfaces.surface }}>
+          <span style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, color: tokens.colors.textMuted }}>Esc or click outside to close &middot; MIT &middot; no signup</span>
+          <a href={tab.href} target="_blank" rel="noopener noreferrer"
+            onClick={() => trackExternalLinkClick(tab.href, { surface: 'home_demo', cta_id: `home_demo_full_${tab.key.replace(/-/g, '_')}`, cta_text: 'Open the full demo' })}
+            style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, fontWeight: 600, color: tokens.colors.accent, textDecoration: 'none' }}>Open the full demo &#8599;</a>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+> Verify these token names exist (used elsewhere): `tokens.surfaces.surface`, `tokens.surfaces.surfaceTinted` (used in the old `LiveDemoFrame`), `tokens.surfaces.border`, `tokens.radius.lg`, `tokens.colors.{accent,accentSurface,textInverted,textMuted,textSecondary}`, `tokens.typography.fontMono`. If any differ, substitute the name the codebase already uses. The analytics `cta_id` values match the existing `home_demo_${string}` pattern in `CtaId` (`apps/website/src/lib/analytics/events.ts`).
+
+- [ ] **Step 2: Verify lint**
+
+Run: `npx nx lint website`
+Expected: PASS (no new errors).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/components/landing/DemoModal.tsx
+git commit -m "feat(website): DemoModal — lightbox for the homepage live demo"
+```
+
+---
+
+## Task 2: Wire `DemoModal` into `DemoShowcase`
+
+**Files:**
+- Modify: `apps/website/src/components/landing/DemoShowcase.tsx`
+
+Replace the inline iframe-swap (`launched`/`isLaunched`/`launch`) with a `modalOpen` boolean; the inline frame becomes a perpetual looping video; the launch overlay opens the modal.
+
+- [ ] **Step 1: Update imports + state**
+
+At the top of `DemoShowcase.tsx`, add imports:
+
+```tsx
+import { DemoModal } from './DemoModal';
+import { trackCtaClick } from '../../lib/analytics/client';
+```
+
+Replace the state lines:
+
+```tsx
+const [active, setActive] = useState<TabKey>('langgraph');
+const [launched, setLaunched] = useState<Set<TabKey>>(new Set());
+const media = MEDIA.find((m) => m.key === active)!;
+const isLaunched = launched.has(active);
+const launch = () => setLaunched((prev) => new Set(prev).add(active));
+```
+
+with:
+
+```tsx
+const [active, setActive] = useState<TabKey>('langgraph');
+const [modalOpen, setModalOpen] = useState(false);
+const media = MEDIA.find((m) => m.key === active)!;
+const launch = () => {
+  trackCtaClick({ surface: 'home_demo', destination_url: media.href, cta_id: `home_demo_launch_${active.replace(/-/g, '_')}`, cta_text: 'Launch live demo' });
+  setModalOpen(true);
+};
+```
+
+- [ ] **Step 2: Make the inline frame always the looping video**
+
+Replace the `<BrowserFrame ...>` block (the `{isLaunched ? (<iframe .../>) : (<>...</>)}` conditional) with the video + overlay only — no inline iframe branch:
+
+```tsx
+<BrowserFrame url={media.url} elevation="lg">
+  <div style={{ position: 'relative', width: '100%', aspectRatio: '16 / 10', background: '#15161f' }}>
+    <video key={media.key} autoPlay muted loop playsInline poster={media.poster}
+      style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}>
+      <source src={media.videoWebm} type="video/webm" />
+      <source src={media.videoMp4} type="video/mp4" />
+    </video>
+    <button onClick={launch} aria-label={`Launch ${media.tabLabel} live demo`}
+      style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10,
+        background: 'linear-gradient(180deg, rgba(16,18,32,.15), rgba(16,18,32,.45))', border: 'none', cursor: 'pointer' }}>
+      <span style={{ width: 56, height: 56, borderRadius: '50%', background: 'rgba(255,255,255,.95)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#15161f', fontSize: 22 }}>&#9654;</span>
+      <span style={{ fontFamily: 'Inter, sans-serif', fontWeight: 600, fontSize: 13, color: '#fff', background: 'rgba(0,0,0,.5)', padding: '8px 14px', borderRadius: 8 }}>Launch live demo</span>
+    </button>
+  </div>
+</BrowserFrame>
+```
+
+- [ ] **Step 3: Render the modal**
+
+Just before the closing `</div>` of the component's root `<div style={{ maxWidth: 760, ... }}>`, add:
+
+```tsx
+<DemoModal
+  open={modalOpen}
+  onClose={() => setModalOpen(false)}
+  tabs={MEDIA}
+  active={active}
+  onActive={setActive}
+/>
+```
+
+(`MEDIA` items carry `key`/`tabLabel`/`url`/`href` — structurally compatible with `DemoModalTab[]`.)
+
+- [ ] **Step 4: Verify lint + scan for leftovers**
+
+Run: `npx nx lint website`
+Expected: PASS. Then confirm no stray references remain:
+
+```bash
+grep -n "isLaunched\|launched\|setLaunched" apps/website/src/components/landing/DemoShowcase.tsx
+```
+Expected: no matches.
+
+- [ ] **Step 5: Visual check (dev server)**
+
+Run the website dev server, open the homepage: click "Launch live demo" → a large centered modal opens with the live chat; tabs switch runtime; ×/Esc/backdrop-click close; focus returns to the launch button; the inline section still shows the looping video after closing.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/components/landing/DemoShowcase.tsx
+git commit -m "feat(website): open the live demo in a modal on launch"
+```
+
+---
+
+## Task 3 (optional): Playwright e2e for the modal
+
+**Files:**
+- Create: `apps/website/e2e/demo-modal.spec.ts`
+
+Add only if the website e2e harness covers the homepage `/`. First check the harness:
+
+- [ ] **Step 1: Confirm the harness serves the homepage**
+
+Read `apps/website/e2e/primitives.spec.ts` and the Playwright config (`apps/website/playwright.config.ts` or the project's e2e config) to learn the `baseURL` / `webServer` and the navigation pattern. If the homepage isn't reachable in the harness, STOP this task and note manual verification in the PR instead.
+
+- [ ] **Step 2: Write the spec (match the harness's import + navigation style)**
+
+```ts
+// apps/website/e2e/demo-modal.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('homepage demo: launch opens a modal, Esc closes it', async ({ page }) => {
+  await page.goto('/');
+  const launch = page.getByRole('button', { name: /launch .* live demo/i }).first();
+  await launch.scrollIntoViewIfNeeded();
+  await launch.click();
+
+  const dialog = page.getByRole('dialog', { name: /live demo/i });
+  await expect(dialog).toBeVisible();
+  // live iframe present
+  await expect(dialog.locator('iframe')).toBeVisible();
+
+  // Esc closes and returns focus to the launch button
+  await page.keyboard.press('Escape');
+  await expect(dialog).toBeHidden();
+  await expect(launch).toBeFocused();
+});
+
+test('homepage demo: in-modal tabs switch the runtime', async ({ page }) => {
+  await page.goto('/');
+  await page.getByRole('button', { name: /launch .* live demo/i }).first().click();
+  const dialog = page.getByRole('dialog', { name: /live demo/i });
+  await dialog.getByRole('tab', { name: 'AG-UI' }).click();
+  await expect(dialog.getByText('ag-ui.threadplane.ai')).toBeVisible();
+});
+```
+
+- [ ] **Step 3: Run the spec**
+
+Run: `npx nx e2e website` (or the project's e2e target), targeting `demo-modal.spec.ts`.
+Expected: both tests PASS. (If the harness needs a running dev server/webServer config, follow the pattern from `primitives.spec.ts`.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/e2e/demo-modal.spec.ts
+git commit -m "test(website): e2e for the homepage demo modal"
+```
+
+---
+
+## Final verification
+- [ ] `npx nx lint website` — PASS.
+- [ ] Manual: launch opens the modal at near-viewport 16:10; ×/Esc/backdrop close; focus returns; tab-switch swaps runtime; mobile (<640px) is a full-screen sheet; reduced-motion skips the scale.
+- [ ] Finish via superpowers:finishing-a-development-branch (PR; the CI `website` job — lint + build + e2e — is the green gate).

From 1d1555344b1affd7763d424f5b8b7e41db3e4302 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 9 Jun 2026 17:36:27 -0700
Subject: [PATCH 3/5] =?UTF-8?q?feat(website):=20DemoModal=20=E2=80=94=20li?=
 =?UTF-8?q?ghtbox=20for=20the=20homepage=20live=20demo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/components/landing/DemoModal.tsx      | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 apps/website/src/components/landing/DemoModal.tsx

diff --git a/apps/website/src/components/landing/DemoModal.tsx b/apps/website/src/components/landing/DemoModal.tsx
new file mode 100644
index 000000000..0d073c82c
--- /dev/null
+++ b/apps/website/src/components/landing/DemoModal.tsx
@@ -0,0 +1,130 @@
+// apps/website/src/components/landing/DemoModal.tsx
+'use client';
+import { useEffect, useRef } from 'react';
+import { tokens } from '@threadplane/design-tokens';
+import { trackExternalLinkClick } from '../../lib/analytics/client';
+
+type TabKey = 'langgraph' | 'ag-ui';
+
+export interface DemoModalTab {
+  key: TabKey;
+  tabLabel: string;
+  url: string;
+  href: string;
+}
+
+interface DemoModalProps {
+  open: boolean;
+  onClose: () => void;
+  tabs: DemoModalTab[];
+  active: TabKey;
+  onActive: (key: TabKey) => void;
+}
+
+export function DemoModal({ open, onClose, tabs, active, onActive }: DemoModalProps) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  const closeBtnRef = useRef<HTMLButtonElement>(null);
+  const tab = tabs.find((t) => t.key === active) ?? tabs[0];
+
+  // While open: Esc to close, focus trap, body scroll lock, restore focus on close.
+  useEffect(() => {
+    if (!open) return;
+    const prevFocus = document.activeElement as HTMLElement | null;
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    closeBtnRef.current?.focus();
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { onClose(); return; }
+      if (e.key !== 'Tab') return;
+      const f = frameRef.current?.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), iframe, [tabindex]:not([tabindex="-1"])',
+      );
+      if (!f || f.length === 0) return;
+      const first = f[0];
+      const last = f[f.length - 1];
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.body.style.overflow = prevOverflow;
+      prevFocus?.focus?.();
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Live demo"
+      onMouseDown={(e) => { if (e.target === e.currentTarget) onClose(); }}
+      style={{
+        position: 'fixed', inset: 0, zIndex: 100,
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        background: 'rgba(16,18,32,.55)',
+        animation: 'demoModalBackdrop .16s ease-out',
+      }}
+    >
+      <style>{`
+        @keyframes demoModalBackdrop { from { opacity: 0 } to { opacity: 1 } }
+        @keyframes demoModalFrame { from { transform: scale(.96); opacity:.6 } to { transform: scale(1); opacity:1 } }
+        .demo-modal__frame {
+          width: min(96vw, calc(90vh * 16 / 10));
+          background: ${tokens.surfaces.surface};
+          border-radius: ${tokens.radius.lg};
+          box-shadow: 0 24px 60px rgba(0,0,0,.45);
+          overflow: hidden;
+          display: flex; flex-direction: column;
+          animation: demoModalFrame .16s ease-out;
+        }
+        .demo-modal__body { width: 100%; aspect-ratio: 16 / 10; background: #15161f; }
+        @media (max-width: 640px) {
+          .demo-modal__frame { width: 100vw; height: 100dvh; border-radius: 0; }
+          .demo-modal__body { aspect-ratio: auto; flex: 1 1 auto; }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          [role="dialog"], .demo-modal__frame { animation: none !important; }
+        }
+      `}</style>
+
+      <div ref={frameRef} className="demo-modal__frame">
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '8px 12px', background: tokens.surfaces.surfaceTinted, borderBottom: `1px solid ${tokens.surfaces.border}` }}>
+          <div style={{ display: 'flex', gap: 5 }} aria-hidden="true">
+            {[0, 1, 2].map((i) => <span key={i} style={{ width: 8, height: 8, borderRadius: '50%', background: '#cdd2df' }} />)}
+          </div>
+          <div role="tablist" aria-label="Demo backend" style={{ display: 'flex', gap: 5 }}>
+            {tabs.map((t) => {
+              const on = t.key === active;
+              return (
+                <button key={t.key} role="tab" aria-selected={on} onClick={() => onActive(t.key)}
+                  style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, fontWeight: 600, padding: '6px 12px', borderRadius: 7, border: 'none', cursor: 'pointer',
+                    background: on ? tokens.colors.accent : tokens.colors.accentSurface, color: on ? tokens.colors.textInverted : tokens.colors.textMuted }}>
+                  {t.tabLabel}
+                </button>
+              );
+            })}
+          </div>
+          <span style={{ flex: 1, textAlign: 'center', fontFamily: tokens.typography.fontMono, fontSize: 12, fontWeight: 600, color: tokens.colors.textMuted, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{tab.url}</span>
+          <button ref={closeBtnRef} onClick={onClose} aria-label="Close demo"
+            style={{ width: 28, height: 28, borderRadius: 7, border: 'none', cursor: 'pointer', background: tokens.colors.accentSurface, color: tokens.colors.textSecondary, fontSize: 16, lineHeight: 1 }}>&#215;</button>
+        </div>
+
+        <div className="demo-modal__body">
+          <iframe src={tab.href} title={`${tab.tabLabel} live demo`}
+            style={{ width: '100%', height: '100%', border: 'none', display: 'block' }} />
+        </div>
+
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 14px', borderTop: `1px solid ${tokens.surfaces.border}`, background: tokens.surfaces.surface }}>
+          <span style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, color: tokens.colors.textMuted }}>Esc or click outside to close &middot; MIT &middot; no signup</span>
+          <a href={tab.href} target="_blank" rel="noopener noreferrer"
+            onClick={() => trackExternalLinkClick(tab.href, { surface: 'home_demo', cta_id: `home_demo_full_${tab.key.replace(/-/g, '_')}`, cta_text: 'Open the full demo' })}
+            style={{ fontFamily: 'Inter, sans-serif', fontSize: 12, fontWeight: 600, color: tokens.colors.accent, textDecoration: 'none' }}>Open the full demo &#8599;</a>
+        </div>
+      </div>
+    </div>
+  );
+}

From ca343ce1d148fd40f22c23bcca0f1dc314a0ac79 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 9 Jun 2026 17:41:42 -0700
Subject: [PATCH 4/5] feat(website): open the live demo in a modal on launch

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/components/landing/DemoShowcase.tsx   | 46 ++++++++++---------
 1 file changed, 25 insertions(+), 21 deletions(-)

diff --git a/apps/website/src/components/landing/DemoShowcase.tsx b/apps/website/src/components/landing/DemoShowcase.tsx
index f2055d26c..47dda07e7 100644
--- a/apps/website/src/components/landing/DemoShowcase.tsx
+++ b/apps/website/src/components/landing/DemoShowcase.tsx
@@ -4,6 +4,8 @@ import { tokens } from '@threadplane/design-tokens';
 import { BrowserFrame } from '../ui/BrowserFrame';
 import { Button } from '../ui/Button';
 import { DemoCtaPair } from './DemoCtaPair';
+import { DemoModal } from './DemoModal';
+import { trackCtaClick } from '../../lib/analytics/client';
 import { DEMOS } from '../../lib/demos';
 
 type TabKey = (typeof DEMOS)[number]['key'];
@@ -31,10 +33,12 @@ const MEDIA: DemoMedia[] = [
 
 export function DemoShowcase() {
   const [active, setActive] = useState<TabKey>('langgraph');
-  const [launched, setLaunched] = useState<Set<TabKey>>(new Set());
+  const [modalOpen, setModalOpen] = useState(false);
   const media = MEDIA.find((m) => m.key === active)!;
-  const isLaunched = launched.has(active);
-  const launch = () => setLaunched((prev) => new Set(prev).add(active));
+  const launch = () => {
+    trackCtaClick({ surface: 'home_demo', destination_url: media.href, cta_id: `home_demo_launch_${active.replace(/-/g, '_')}`, cta_text: 'Launch live demo' });
+    setModalOpen(true);
+  };
 
   return (
     <div style={{ maxWidth: 760, margin: '0 auto', textAlign: 'center' }}>
@@ -61,24 +65,17 @@ export function DemoShowcase() {
 
       <BrowserFrame url={media.url} elevation="lg">
         <div style={{ position: 'relative', width: '100%', aspectRatio: '16 / 10', background: '#15161f' }}>
-          {isLaunched ? (
-            <iframe src={media.href} title={`${media.tabLabel} live demo`} loading="lazy"
-              style={{ width: '100%', height: '100%', border: 'none', display: 'block' }} />
-          ) : (
-            <>
-              <video key={media.key} autoPlay muted loop playsInline poster={media.poster}
-                style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}>
-                <source src={media.videoWebm} type="video/webm" />
-                <source src={media.videoMp4} type="video/mp4" />
-              </video>
-              <button onClick={launch} aria-label={`Launch ${media.tabLabel} live demo`}
-                style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10,
-                  background: 'linear-gradient(180deg, rgba(16,18,32,.15), rgba(16,18,32,.45))', border: 'none', cursor: 'pointer' }}>
-                <span style={{ width: 56, height: 56, borderRadius: '50%', background: 'rgba(255,255,255,.95)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#15161f', fontSize: 22 }}>&#9654;</span>
-                <span style={{ fontFamily: 'Inter, sans-serif', fontWeight: 600, fontSize: 13, color: '#fff', background: 'rgba(0,0,0,.5)', padding: '8px 14px', borderRadius: 8 }}>Launch live demo</span>
-              </button>
-            </>
-          )}
+          <video key={media.key} autoPlay muted loop playsInline poster={media.poster}
+            style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}>
+            <source src={media.videoWebm} type="video/webm" />
+            <source src={media.videoMp4} type="video/mp4" />
+          </video>
+          <button onClick={launch} aria-label={`Launch ${media.tabLabel} live demo`}
+            style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10,
+              background: 'linear-gradient(180deg, rgba(16,18,32,.15), rgba(16,18,32,.45))', border: 'none', cursor: 'pointer' }}>
+            <span style={{ width: 56, height: 56, borderRadius: '50%', background: 'rgba(255,255,255,.95)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#15161f', fontSize: 22 }}>&#9654;</span>
+            <span style={{ fontFamily: 'Inter, sans-serif', fontWeight: 600, fontSize: 13, color: '#fff', background: 'rgba(0,0,0,.5)', padding: '8px 14px', borderRadius: 8 }}>Launch live demo</span>
+          </button>
         </div>
       </BrowserFrame>
 
@@ -91,6 +88,13 @@ export function DemoShowcase() {
       <p style={{ fontFamily: tokens.typography.caption.family, fontSize: tokens.typography.caption.size, color: tokens.colors.textMuted, margin: '14px 0 0' }}>
         Video loops instantly · click Launch to open the live, interactive demo · MIT · no signup
       </p>
+      <DemoModal
+        open={modalOpen}
+        onClose={() => setModalOpen(false)}
+        tabs={MEDIA}
+        active={active}
+        onActive={setActive}
+      />
     </div>
   );
 }

From 939c42d925aea339867bb1282a48a2df86f484df Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 9 Jun 2026 17:48:41 -0700
Subject: [PATCH 5/5] test(website): e2e for the homepage demo modal

---
 apps/website/e2e/demo-modal.spec.ts | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 apps/website/e2e/demo-modal.spec.ts

diff --git a/apps/website/e2e/demo-modal.spec.ts b/apps/website/e2e/demo-modal.spec.ts
new file mode 100644
index 000000000..56ed975a6
--- /dev/null
+++ b/apps/website/e2e/demo-modal.spec.ts
@@ -0,0 +1,25 @@
+import { test, expect } from '@playwright/test';
+
+test('homepage demo: launch opens a modal, Esc closes it', async ({ page }) => {
+  await page.goto('/');
+  const launch = page.getByRole('button', { name: /launch .* live demo/i }).first();
+  await launch.scrollIntoViewIfNeeded();
+  await launch.click();
+
+  const dialog = page.getByRole('dialog', { name: /live demo/i });
+  await expect(dialog).toBeVisible();
+  await expect(dialog.locator('iframe')).toBeVisible();
+
+  await page.keyboard.press('Escape');
+  await expect(dialog).toBeHidden();
+  await expect(launch).toBeFocused();
+});
+
+test('homepage demo: in-modal tabs switch the runtime', async ({ page }) => {
+  await page.goto('/');
+  await page.getByRole('button', { name: /launch .* live demo/i }).first().click();
+  const dialog = page.getByRole('dialog', { name: /live demo/i });
+  await expect(dialog).toBeVisible();
+  await dialog.getByRole('tab', { name: 'AG-UI' }).click();
+  await expect(dialog.getByText('ag-ui.threadplane.ai')).toBeVisible();
+});